{"id":17626674,"url":"https://github.com/Query-farm/duckdb-extension-clickhouse-sql","last_synced_at":"2025-08-21T12:30:57.386Z","repository":{"id":247065784,"uuid":"824934359","full_name":"quackscience/duckdb-extension-clickhouse-sql","owner":"quackscience","description":"DuckDB Community Extension implementing ClickHouse SQL Dialect macros and Custom functions for DuckDB","archived":false,"fork":false,"pushed_at":"2024-11-23T12:14:46.000Z","size":145,"stargazers_count":42,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-15T03:34:30.511Z","etag":null,"topics":["chdb","chsql","clickhouse","clickhouse-database","clickhouse-server","duckdb","duckdb-community","duckdb-extension","duckdb-server","quackpipe","sql"],"latest_commit_sha":null,"homepage":"https://duckdb.org/community_extensions/extensions/chsql.html","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quackscience.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-06T10:30:09.000Z","updated_at":"2024-11-29T19:37:32.000Z","dependencies_parsed_at":"2024-07-20T17:24:09.356Z","dependency_job_id":"e1b46ceb-ed7f-4a56-badd-04d3728a0c29","html_url":"https://github.com/quackscience/duckdb-extension-clickhouse-sql","commit_stats":{"total_commits":78,"total_committers":5,"mean_commits":15.6,"dds":0.1923076923076923,"last_synced_commit":"a000d4f2a5f9e1c13cddcd75ea2d3351466f1706"},"previous_names":["lmangani/duckdb-extension-clickhouse-sql","quackscience/duckdb-extension-clickhouse-sql"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quackscience%2Fduckdb-extension-clickhouse-sql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quackscience%2Fduckdb-extension-clickhouse-sql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quackscience%2Fduckdb-extension-clickhouse-sql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quackscience%2Fduckdb-extension-clickhouse-sql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quackscience","download_url":"https://codeload.github.com/quackscience/duckdb-extension-clickhouse-sql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230511482,"owners_count":18237658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chdb","chsql","clickhouse","clickhouse-database","clickhouse-server","duckdb","duckdb-community","duckdb-extension","duckdb-server","quackpipe","sql"],"created_at":"2024-10-22T23:20:33.143Z","updated_at":"2025-08-21T12:30:57.367Z","avatar_url":"https://github.com/quackscience.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://community-extensions.duckdb.org/extensions/chsql.html\" target=\"_blank\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/9003897d-db6f-4a79-9443-9b72766b511b\" width=200\u003e\n\u003c/a\u003e\n\n# DuckDB ClickHouse SQL extension\n\nThe DuckDB [chsql](https://community-extensions.duckdb.org/extensions/chsql.html) community extension implements popular **ClickHouse SQL** syntax macros and functions,\u003cbr\u003e\nmaking it easier for users to transition between the two database systems ⭐ designed for [Quackpipe](https://github.com/metrico/quackpipe) \n\n\u003cbr\u003e\n\n## Installation\n\n**chsql** is distributed as a [DuckDB Community Extension](https://github.com/duckdb/community-extensions) and can be installed using SQL:\n\n```sql\nINSTALL chsql FROM community;\nLOAD chsql;\n```\n\nIf you previously installed the `chsql` extension, upgrade using the FORCE command\n```sql\nFORCE INSTALL chsql FROM community;\nLOAD chsql;\n```\n\n## Usage Examples\nOnce installed, the [macro functions](https://community-extensions.duckdb.org/extensions/chsql.html#added-functions) provided by the extension can be used just like built-in functions.\n\nHere's a random example out of 100s using the `IPv4StringToNum` and `IPv4NumToString` functions:\n\n```sql\n--- Install and load chsql\nD INSTALL chsql FROM community;\nD LOAD chsql;\n\n--- Use any of the 100+ ClickHouse Macros\nD SELECT IPv4StringToNum('127.0.0.1'), IPv4NumToString(2130706433);\n┌──────────────────────────────┬─────────────────────────────┐\n│ ipv4stringtonum('127.0.0.1') │ ipv4numtostring(2130706433) │\n│ int32 │ varchar │\n├──────────────────────────────┼─────────────────────────────┤\n│ 2130706433 │ 127.0.0.1 │\n└──────────────────────────────┴─────────────────────────────┘\n```\n\n### Remote Queries\nThe built-in `ch_scan` function can be used to query remote ClickHouse servers using the HTTP/s API\n\n```sql\n--- Set optional X-Header Authentication\nD CREATE SECRET extra_http_headers (\n TYPE HTTP,\n EXTRA_HTTP_HEADERS MAP{\n 'X-ClickHouse-User': 'user',\n 'X-ClickHouse-Key': 'password'\n }\n );\n--- Query using the HTTP API\nD SELECT * FROM ch_scan(\"SELECT number * 2 FROM numbers(10)\", \"https://play.clickhouse.com\");\n```\n\n## Supported Functions\n\n👉 The [list of supported aliases](https://community-extensions.duckdb.org/extensions/chsql.html#added-functions) is available on the [dedicated extension page](https://community-extensions.duckdb.org/extensions/chsql.html)\u003cbr\u003e\n👉 The combined list of [supported functions](https://quackpipe.fly.dev/?user=default#TE9BRCBjaHNxbDsgU0VMRUNUIERJU1RJTkNUIE9OKGZ1bmN0aW9uX25hbWUpIGZ1bmN0aW9uX25hbWUgYXMgbmFtZQpGUk9NIGR1Y2tkYl9mdW5jdGlvbnMoKSBXSEVSRSBuYW1lIElOIChTRUxFQ1QgbmFtZSBGUk9NIGNoX3NjYW4oJyBTRUxFQ1QgbmFtZSBGUk9NIHN5c3RlbS5mdW5jdGlvbnMnLCdodHRwczovL3BsYXkuY2xpY2tob3VzZS5jb20nKSBPUkRFUiBCWSBuYW1lKSBPUkRFUiBCWSBuYW1lOw==) can be obtained using an [SQL Join](https://quackpipe.fly.dev/?user=default#TE9BRCBjaHNxbDsgU0VMRUNUIERJU1RJTkNUIE9OKGZ1bmN0aW9uX25hbWUpIGZ1bmN0aW9uX25hbWUgYXMgbmFtZQpGUk9NIGR1Y2tkYl9mdW5jdGlvbnMoKSBXSEVSRSBuYW1lIElOIChTRUxFQ1QgbmFtZSBGUk9NIGNoX3NjYW4oJyBTRUxFQ1QgbmFtZSBGUk9NIHN5c3RlbS5mdW5jdGlvbnMnLCdodHRwczovL3BsYXkuY2xpY2tob3VzZS5jb20nKSBPUkRFUiBCWSBuYW1lKSBPUkRFUiBCWSBuYW1lOw==)\n\n## System Table\n`chsql` loosely emulates ClickHouse system tables within DuckDB for client compatibility\n\n### Table Views\n- [x] `system.databases`\n- [x] `system.tables`\n- [x] `system.columns`\n- [x] `system.functions`\n- [x] `system.uptime`\n- [x] `system.disks`\n### Scalar\n- [x] `uptime()`\n\n\n\u003cbr\u003e\n\n\n## Motivation\n\n\u003e Why is the DuckDB + chsql combo fun and useful\n\n✔ DuckDB SQL is awesome and full of great functions.\u003cbr\u003e\n✔ ClickHouse SQL is awesome and full of great functions. \n\n✔ The DuckDB library is ~51M and modular. Can LOAD extensions.\u003cbr\u003e\n❌ The ClickHouse monolith is ~551M and growing. No extensions. \n\n✔ DuckDB is open source and _protected by a no-profit foundation._\u003cbr\u003e\n❌ ClickHouse is open core and _controlled by for-profit corporation._ \n\n✔ DuckDB embedded is fast, mature and elegantly integrated in many languages.\u003cbr\u003e\n❌ chdb is still experimental, unstable and _currently only supports Python_. \n\n\u003cimg src=\"https://github.com/user-attachments/assets/a17efd68-d2e1-42a7-8ab9-1ea4c2ff11e3\" width=700 /\u003e\n\n\u003cbr\u003e\n\n\u003cbr\u003e\n\n\n## Functions\n| function | fun_type | description | comment | example |\n| ---------------------- | ----------- | -------------------------------------------------------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| IPv4NumToString | macro | Cast IPv4 address from numeric to string format | | SELECT IPv4NumToString(2130706433); |\n| IPv4StringToNum | macro | Cast IPv4 address from string to numeric format | | SELECT IPv4StringToNum('127.0.0.1'); |\n| arrayExists | macro | Check if any element of the array satisfies the condition | | SELECT arrayExists(x -\u003e x = 1, [1, 2, 3]); |\n| arrayJoin | macro | Unroll an array into multiple rows | | SELECT arrayJoin([1, 2, 3]); |\n| arrayMap | macro | Applies a function to each element of an array | | SELECT arrayMap(x -\u003e x + 1, [1, 2, 3]); |\n| bitCount | macro | Counts the number of set bits in an integer | | SELECT bitCount(15); |\n| ch_scan | table_macro | Query a remote ClickHouse server using HTTP/s API | Returns the query results | SELECT * FROM ch_scan('SELECT version()','https://play.clickhouse.com', format := 'parquet'); |\n| domain | macro | Extracts the domain from a URL | | SELECT domain('https://clickhouse.com/docs'); |\n| empty | macro | Check if a string is empty | | SELECT empty(''); |\n| extractAllGroups | macro | Extracts all matching groups from a string using a regular expression | | SELECT extractAllGroups('(\\\\d+)', 'abc123'); |\n| formatDateTime | macro | Formats a DateTime value into a string | | SELECT formatDateTime(now(), '%Y-%m-%d'); |\n| generateUUIDv4 | macro | Generate a UUID v4 value | | SELECT generateUUIDv4(); |\n| ifNull | macro | Returns the first argument if not NULL, otherwise the second | | SELECT ifNull(NULL, 'default'); |\n| intDiv | macro | Performs integer division | | SELECT intDiv(10, 3); |\n| intDivOZero | macro | Performs integer division but returns zero instead of throwing an error for division by zero | | SELECT intDivOZero(10, 0); |\n| intDivOrNull | macro | Performs integer division but returns NULL instead of throwing an error for division by zero | | SELECT intDivOrNull(10, 0); |\n| leftPad | macro | Pads a string on the left to a specified length | | SELECT leftPad('abc', 5, '*'); |\n| lengthUTF8 | macro | Returns the length of a string in UTF-8 characters | | SELECT lengthUTF8('Привет'); |\n| match | macro | Performs a regular expression match on a string | | SELECT match('abc123', '\\\\d+'); |\n| minus | macro | Performs subtraction of two numbers | | SELECT minus(5, 3); |\n| modulo | macro | Calculates the remainder of division (modulus) | | SELECT modulo(10, 3); |\n| moduloOrZero | macro | Calculates modulus but returns zero instead of error on division by zero | | SELECT moduloOrZero(10, 0); |\n| notEmpty | macro | Check if a string is not empty | | SELECT notEmpty('abc'); |\n| numbers | table_macro | Generates a sequence of numbers starting from 0 | Returns a table with a single column (UInt64) | SELECT * FROM numbers(10); |\n| parseURL | macro | Extracts parts of a URL | | SELECT parseURL('https://clickhouse.com', 'host'); |\n| path | macro | Extracts the path from a URL | | SELECT path('https://clickhouse.com/docs'); |\n| plus | macro | Performs addition of two numbers | | SELECT plus(5, 3); |\n| protocol | macro | Extracts the protocol from a URL | | SELECT protocol('https://clickhouse.com'); |\n| read_parquet_mergetree | function | Merge parquet files using a primary sorting key for fast range queries | experimental | COPY (SELECT * FROM read_parquet_mergetree(['/folder/*.parquet'], 'sortkey') TO 'sorted.parquet'; |\n| rightPad | macro | Pads a string on the right to a specified length | | SELECT rightPad('abc', 5, '*'); |\n| splitByChar | macro | Splits a string by a given character | | SELECT splitByChar(',', 'a,b,c'); |\n| toDayOfMonth | macro | Extracts the day of the month from a date | | SELECT toDayOfMonth('2023-09-10'); |\n| toFixedString | macro | Converts a value to a fixed-length string | | SELECT toFixedString('abc', 5); |\n| toFloat | macro | Converts a value to a float | | SELECT toFloat('123.45'); |\n| toFloatOrNull | macro | Converts a value to float or returns NULL if the conversion fails | | SELECT toFloatOrNull('abc'); |\n| toFloatOrZero | macro | Converts a value to float or returns zero if the conversion fails | | SELECT toFloatOrZero('abc'); |\n| toHour | macro | Extracts the hour from a DateTime value | | SELECT toHour(now()); |\n| toInt128 | macro | Converts a value to a 128-bit integer | | SELECT toInt128('123456789012345678901234567890'); |\n| toInt128OrNull | macro | Converts to a 128-bit integer or returns NULL on failure | | SELECT toInt128OrNull('abc'); |\n| toInt128OrZero | macro | Converts to a 128-bit integer or returns zero on failure | | SELECT toInt128OrZero('abc'); |\n| toInt16 | macro | Converts a value to a 16-bit integer | | SELECT toInt16('123'); |\n| toInt16OrNull | macro | Converts to a 16-bit integer or returns NULL on failure | | SELECT toInt16OrNull('abc'); |\n| toInt16OrZero | macro | Converts to a 16-bit integer or returns zero on failure | | SELECT toInt16OrZero('abc'); |\n| toInt256 | macro | Converts a value to a 256-bit integer | | SELECT toInt256('12345678901234567890123456789012345678901234567890123456789012345678901234567890'); |\n| toInt256OrNull | macro | Converts to a 256-bit integer or returns NULL on failure | | SELECT toInt256OrNull('abc'); |\n| toInt256OrZero | macro | Converts to a 256-bit integer or returns zero on failure | | SELECT toInt256OrZero('abc'); |\n| toInt32 | macro | Converts a value to a 32-bit integer | | SELECT toInt32('123'); |\n| toInt32OrNull | macro | Converts to a 32-bit integer or returns NULL on failure | | SELECT toInt32OrNull('abc'); |\n| toInt32OrZero | macro | Converts to a 32-bit integer or returns zero on failure | | SELECT toInt32OrZero('abc'); |\n| toInt64 | macro | Converts a value to a 64-bit integer | | SELECT toInt64('123'); |\n| toInt64OrNull | macro | Converts to a 64-bit integer or returns NULL on failure | | SELECT toInt64OrNull('abc'); |\n| toInt64OrZero | macro | Converts to a 64-bit integer or returns zero on failure | | SELECT toInt64OrZero('abc'); |\n| toInt8 | macro | Converts a value to an 8-bit integer | | SELECT toInt8('123'); |\n| toInt8OrNull | macro | Converts to an 8-bit integer or returns NULL on failure | | SELECT toInt8OrNull('abc'); |\n| toInt8OrZero | macro | Converts to an 8-bit integer or returns zero on failure | | SELECT toInt8OrZero('abc'); |\n| toMinute | macro | Extracts the minute from a DateTime value | | SELECT toMinute(now()); |\n| toMonth | macro | Extracts the month from a Date value | | SELECT toMonth('2023-09-10'); |\n| toSecond | macro | Extracts the second from a DateTime value | | SELECT toSecond(now()); |\n| toString | macro | Converts a value to a string | | SELECT toString(123); |\n| toUInt16 | macro | Converts a value to an unsigned 16-bit integer | | SELECT toUInt16('123'); |\n| toUInt16OrNull | macro | Converts to an unsigned 16-bit integer or returns NULL on failure | | SELECT toUInt16OrNull('abc'); |\n| toUInt16OrZero | macro | Converts to an unsigned 16-bit integer or returns zero on failure | | SELECT toUInt16OrZero('abc'); |\n| toUInt32 | macro | Converts a value to an unsigned 32-bit integer | | SELECT toUInt32('123'); |\n| toUInt32OrNull | macro | Converts to an unsigned 32-bit integer or returns NULL on failure | | SELECT toUInt32OrNull('abc'); |\n| toUInt32OrZero | macro | Converts to an unsigned 32-bit integer or returns zero on failure | | SELECT toUInt32OrZero('abc'); |\n| toUInt64 | macro | Converts a value to an unsigned 64-bit integer | | SELECT toUInt64('123'); |\n| toUInt64OrNull | macro | Converts to an unsigned 64-bit integer or returns NULL on failure | | SELECT toUInt64OrNull('abc'); |\n| toUInt64OrZero | macro | Converts to an unsigned 64-bit integer or returns zero on failure | | SELECT toUInt64OrZero('abc'); |\n| toUInt8 | macro | Converts a value to an unsigned 8-bit integer | | SELECT toUInt8('123'); |\n| toUInt8OrNull | macro | Converts to an unsigned 8-bit integer or returns NULL on failure | | SELECT toUInt8OrNull('abc'); |\n| toUInt8OrZero | macro | Converts to an unsigned 8-bit integer or returns zero on failure | | SELECT toUInt8OrZero('abc'); |\n| toYYYYMM | macro | Formats a Date to 'YYYYMM' string format | | SELECT toYYYYMM('2023-09-10'); |\n| toYYYYMMDD | macro | Formats a Date to 'YYYYMMDD' string format | | SELECT toYYYYMMDD('2023-09-10'); |\n| toYYYYMMDDhhmmss | macro | Formats a DateTime to 'YYYYMMDDhhmmss' string format | | SELECT toYYYYMMDDhhmmss(now()); |\n| toYear | macro | Extracts the year from a Date or DateTime value | | SELECT toYear('2023-09-10'); |\n| topLevelDomain | macro | Extracts the top-level domain (TLD) from a URL | | SELECT topLevelDomain('https://example.com'); |\n| tupleConcat | macro | Concatenates two tuples into one tuple | | SELECT tupleConcat((1, 'a'), (2, 'b')); |\n| tupleDivide | macro | Performs element-wise division between two tuples | | SELECT tupleDivide((10, 20), (2, 5)); |\n| tupleDivideByNumber | macro | Divides each element of a tuple by a number | | SELECT tupleDivideByNumber((10, 20), 2); |\n| tupleIntDiv | macro | Performs element-wise integer division between two tuples | | SELECT tupleIntDiv((10, 20), (3, 4)); |\n| tupleIntDivByNumber | macro | Performs integer division of each element of a tuple by a number | | SELECT tupleIntDivByNumber((10, 20), 3); |\n| tupleMinus | macro | Performs element-wise subtraction between two tuples | | SELECT tupleMinus((10, 20), (5, 3)); |\n| tupleModulo | macro | Performs element-wise modulus between two tuples | | SELECT tupleModulo((10, 20), (3, 6)); |\n| tupleModuloByNumber | macro | Calculates the modulus of each element of a tuple by a number | | SELECT tupleModuloByNumber((10, 20), 3); |\n| tupleMultiply | macro | Performs element-wise multiplication between two tuples | | SELECT tupleMultiply((10, 20), (2, 5)); |\n| tupleMultiplyByNumber | macro | Multiplies each element of a tuple by a number | | SELECT tupleMultiplyByNumber((10, 20), 3); |\n| tuplePlus | macro | Performs element-wise addition between two tuples | | SELECT tuplePlus((1, 2), (3, 4)); |\n| url | table_macro | Performs queries against remote URLs using the specified format | Supports JSON, CSV, PARQUET, TEXT, BLOB | SELECT * FROM url('https://urleng.com/test','JSON'); |\n| JSONExtract | macro | Extracts JSON data based on key from a JSON object | | SELECT JSONExtract(json_column, 'user.name'); |\n| JSONExtractString | macro | Extracts JSON data as a VARCHAR from a JSON object | | SELECT JSONExtractString(json_column, 'user.email'); |\n| JSONExtractUInt | macro | Extracts JSON data as an unsigned integer from a JSON object | | SELECT JSONExtractUInt(json_column, 'user.age'); |\n| JSONExtractInt | macro | Extracts JSON data as a 32-bit integer from a JSON object | | SELECT JSONExtractInt(json_column, 'user.balance'); |\n| JSONExtractFloat | macro | Extracts JSON data as a double from a JSON object | | SELECT JSONExtractFloat(json_column, 'user.score'); |\n| JSONExtractRaw | macro | Extracts raw JSON data based on key from a JSON object | | SELECT JSONExtractRaw(json_column, 'user.address'); |\n| JSONHas | macro | Checks if a JSON key exists and is not null | | SELECT JSONHas(json_column, 'user.active'); |\n| JSONLength | macro | Returns the length of a JSON array | | SELECT JSONLength(json_column, 'items'); |\n| JSONType | macro | Determines the type of JSON element at the given path | | SELECT JSONType(json_column, 'user.data'); |\n| JSONExtractKeys | macro | Extracts keys from a JSON object | | SELECT JSONExtractKeys(json_column); |\n| JSONExtractValues | macro | Extracts all values as text from a JSON object | | SELECT JSONExtractValues(json_column); |\n| equals | macro | Checks if two values are equal | | SELECT equals(column_a, column_b); |\n| notEquals | macro | Checks if two values are not equal | | SELECT notEquals(column_a, column_b); |\n| less | macro | Checks if one value is less than another | | SELECT less(column_a, column_b); |\n| greater | macro | Checks if one value is greater than another | | SELECT greater(column_a, column_b); |\n| lessOrEquals | macro | Checks if one value is less than or equal to another | | SELECT lessOrEquals(column_a, column_b); |\n| greaterOrEquals | macro | Checks if one value is greater than or equal to another | | SELECT greaterOrEquals(column_a, column_b); |\n| dictGet | macro | Retrieves an attribute from a VARIABLE string or MAP | | SELECT dictGet('dictionary_name', 'attribute'); |\n\n###### Disclaimer\n\u003e DuckDB ® is a trademark of DuckDB Foundation. ClickHouse® is a trademark of ClickHouse Inc. All trademarks, service marks, and logos mentioned or depicted are the property of their respective owners. The use of any third-party trademarks, brand names, product names, and company names is purely informative or intended as parody and does not imply endorsement, affiliation, or association with the respective owners.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuery-farm%2Fduckdb-extension-clickhouse-sql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQuery-farm%2Fduckdb-extension-clickhouse-sql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuery-farm%2Fduckdb-extension-clickhouse-sql/lists"}