-
Notifications
You must be signed in to change notification settings - Fork 28
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs): add ClickHouse connector to docs package
- Loading branch information
Showing
9 changed files
with
206 additions
and
23 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # ClickHouse | ||
|
|
||
| ## Installation | ||
|
|
||
| 1. Install package | ||
|
|
||
| **If you are developing with binary, the package is already bundled in the binary. You can skip this step.** | ||
|
|
||
| ```bash | ||
| npm i @vulcan-sql/extension-driver-clickhouse | ||
| ``` | ||
|
|
||
| 2. Update `vulcan.yaml`, and enable the extension. | ||
|
|
||
| ```yaml | ||
| extensions: | ||
| ... | ||
| // highlight-next-line | ||
| ch: '@vulcan-sql/extension-driver-clickhouse' # Add this line | ||
| ``` | ||
|
|
||
| 3. Create a new profile in `profiles.yaml` or in your profile files. For example: | ||
|
|
||
| ```yaml | ||
| - name: ch # profile name | ||
| type: clickhouse | ||
| connection: | ||
| host: www.example.com:8123 | ||
| request_timeout: 60000 | ||
| compression: | ||
| request: true | ||
| max_open_connections: 10 | ||
| username: user | ||
| password: pass | ||
| database: hello-clickhouse | ||
| allow: '*' | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| Please check [arguments of ClickHouse Client](https://clickhouse.com/docs/en/integrations/language-clients/nodejs) for further information. | ||
|
|
||
| | Name | Required | Default | Description | | ||
| | -------------------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | host | N | http://localhost:8123 | ClickHouse instance URL. | | ||
| | request_timeout | N | 30000 | The request timeout in milliseconds. | | ||
| | max_open_connections | N | Infinity | Maximum number of sockets to allow per host. | | ||
| | compression | N | | Data applications operating with large datasets over the wire can benefit from enabling compression. Currently, only GZIP is supported using zlib.Please see [Compression docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#compression). | | ||
| | username | N | default | The name of the user on whose behalf requests are made. | | ||
| | password | N | | The user password. | | ||
| | application | N | VulcanSQL | The name of the application using the Node.js client. | | ||
| | database | N | default | Database name to use. | | ||
| | clickhouse_settings | N | | ClickHouse settings to apply to all requests. please see the [Advance Settings](https://clickhouse.com/docs/en/operations/settings), and [Definition](https://github.com/ClickHouse/clickhouse-js/blob/0.1.1/src/settings.ts) | | ||
| | tls | N | | Configure TLS certificates. Please see [TLS docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#tls-certificates). | | ||
| | session_id | N | | ClickHouse Session ID to send with every request. | | ||
| | keep_alive | N | | HTTP Keep-Alive related settings. Please see [Keep Alive docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#keep-alive) | | ||
|
|
||
| At the above, it not contains `log` option, because the `logs` need to define a Logger class and assign to it, so it could not set by `profiles.yaml`. | ||
|
|
||
| ## Note | ||
|
|
||
| The ClickHouse support parameterized query to prevent SQL Injection by prepared statement. The named placeholder define by `{name:type}`, please see [Query with Parameters](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#queries-with-parameters). | ||
|
|
||
| However, The VulcanSQL API support API query parameter is JSON format, so it not support [variety types like ClickHouse](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#supported-clickhouse-data-types), The VulcanSQL will only support to convert below types: | ||
|
|
||
| - `boolean` to `Boolean` ClickHouse type | ||
| - `number` to `Int` or `Float` ClickHouse type | ||
| - `string` to `String` ClickHouse type | ||
|
|
||
| Therefore, if you would like to query the data is a special type from ClickHouse, e.g: `Array(Unit8)`, `Record<K, V>`, `Date`, `DateTime` ...etc, you could use the ClickHouse [Regular Function](https://clickhouse.com/docs/en/sql-reference/functions) or [Type Conversion Function](https://clickhouse.com/docs/en/sql-reference/functions/type-conversion-functions) to do it. | ||
|
|
||
| Example: | ||
|
|
||
| ```sql | ||
| -- If the val from API query parameter is '1990-11-01', and the born_date columns type is Date32 type | ||
| -- What is the toDate function, please see https://clickhouse.com/docs/en/sql-reference/functions/type-conversion-functions#todate | ||
| SELECT * FROM users WHERE born_date = toDate({val:String}); | ||
| ``` | ||
|
|
||
| ## ⚠️ Caution | ||
|
|
||
| ClickHouse driver currently not yet support for caching datasets feature. If you use the ClickHouse driver with caching dataset feature, it will be failed. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # ClickHouse | ||
|
|
||
| Connect with your ClickHouse servers via the official [Node.js Driver](https://clickhouse.com/docs/en/integrations/language-clients/nodejs). | ||
|
|
||
| ## Installation | ||
|
|
||
| 1. Install package | ||
|
|
||
| ```bash | ||
| npm i @vulcan-sql/extension-driver-clickhouse | ||
| ``` | ||
|
|
||
| :::info | ||
| If you run VulcanSQL with Docker, you should use the command `vulcan-install @vulcan-sql/extension-driver-clickhouse` instead. | ||
|
|
||
| ::: | ||
|
|
||
| 2. Update `vulcan.yaml`, and enable the extension. | ||
|
|
||
| ```yaml | ||
| extensions: | ||
| ... | ||
| // highlight-next-line | ||
| ch: '@vulcan-sql/extension-driver-clickhouse' # Add this line | ||
| ``` | ||
|
|
||
| 3. Create a new profile in `profiles.yaml` or in your profile files. For example: | ||
|
|
||
| ```yaml | ||
| - name: ch # profile name | ||
| type: clickhouse | ||
| connection: | ||
| host: www.example.com:8123 | ||
| request_timeout: 60000 | ||
| compression: | ||
| request: true | ||
| max_open_connections: 10 | ||
| username: user | ||
| password: pass | ||
| database: hello-clickhouse | ||
| allow: '*' | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| Please check [arguments of ClickHouse Client](https://clickhouse.com/docs/en/integrations/language-clients/nodejs) for further information. | ||
|
|
||
| | Name | Required | Default | Description | | ||
| | -------------------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | host | N | http://localhost:8123 | ClickHouse instance URL. | | ||
| | request_timeout | N | 30000 | The request timeout in milliseconds. | | ||
| | max_open_connections | N | Infinity | Maximum number of sockets to allow per host. | | ||
| | compression | N | | Data applications operating with large datasets over the wire can benefit from enabling compression. Currently, only GZIP is supported using zlib.Please see [Compression docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#compression). | | ||
| | username | N | default | The name of the user on whose behalf requests are made. | | ||
| | password | N | | The user password. | | ||
| | application | N | VulcanSQL | The name of the application using the Node.js client. | | ||
| | database | N | default | Database name to use. | | ||
| | clickhouse_settings | N | | ClickHouse settings to apply to all requests. please see the [Advance Settings](https://clickhouse.com/docs/en/operations/settings), and [Definition](https://github.com/ClickHouse/clickhouse-js/blob/0.1.1/src/settings.ts) | | ||
| | tls | N | | Configure TLS certificates. Please see [TLS docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#tls-certificates). | | ||
| | session_id | N | | ClickHouse Session ID to send with every request. | | ||
| | keep_alive | N | | HTTP Keep-Alive related settings. Please see [Keep Alive docs](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#keep-alive) | | ||
|
|
||
| At the above, it not contains `log` option, because the `logs` need to define a Logger class and assign to it, so it could not set by `profiles.yaml`. | ||
|
|
||
| ## Note | ||
|
|
||
| The ClickHouse support parameterized query to prevent SQL Injection by prepared statement. The named placeholder define by `{name:type}`, please see [Query with Parameters](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#queries-with-parameters). | ||
|
|
||
| However, The VulcanSQL API support API query parameter is JSON format, so it not support [variety types like ClickHouse](https://clickhouse.com/docs/en/integrations/language-clients/nodejs#supported-clickhouse-data-types), The VulcanSQL will only support to convert below types: | ||
|
|
||
| - `boolean` to `Boolean` ClickHouse type | ||
| - `number` to `Int` or `Float` ClickHouse type | ||
| - `string` to `String` ClickHouse type | ||
|
|
||
| Therefore, if you would like to query the data is a special type from ClickHouse, e.g: `Array(Unit8)`, `Record<K, V>`, `Date`, `DateTime` ...etc, you could use the ClickHouse [Regular Function](https://clickhouse.com/docs/en/sql-reference/functions) or [Type Conversion Function](https://clickhouse.com/docs/en/sql-reference/functions/type-conversion-functions) to do it. | ||
|
|
||
| Example: | ||
|
|
||
| ```sql | ||
| -- If the val from API query parameter is '1990-11-01', and the born_date columns type is Date32 type | ||
| -- What is the toDate function, please see https://clickhouse.com/docs/en/sql-reference/functions/type-conversion-functions#todate | ||
| SELECT * FROM users WHERE born_date = toDate({val:String}); | ||
| ``` | ||
|
|
||
| ## ⚠️ Caution | ||
|
|
||
| ClickHouse driver currently not yet support for caching datasets feature. If you use the ClickHouse driver with caching dataset feature, it will be failed. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.