{"id":22693093,"url":"https://github.com/depyronick/clickhouse-client","last_synced_at":"2025-10-24T22:39:03.931Z","repository":{"id":42620510,"uuid":"429619715","full_name":"depyronick/clickhouse-client","owner":"depyronick","description":"ClickHouse Client for NodeJS","archived":false,"fork":false,"pushed_at":"2024-01-29T12:42:12.000Z","size":656,"stargazers_count":51,"open_issues_count":6,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-07T10:39:26.413Z","etag":null,"topics":["clickhouse","clickhouse-client","database","driver","javascript","node","node-clickhouse","nodejs","nodejs-clickhouse","typescript"],"latest_commit_sha":null,"homepage":"https://clickhouse.js.org","language":"TypeScript","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/depyronick.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-11-19T00:22:46.000Z","updated_at":"2025-06-10T18:13:11.000Z","dependencies_parsed_at":"2024-01-29T14:44:04.129Z","dependency_job_id":null,"html_url":"https://github.com/depyronick/clickhouse-client","commit_stats":{"total_commits":88,"total_committers":6,"mean_commits":"14.666666666666666","dds":"0.10227272727272729","last_synced_commit":"1d833bbe9deb5c26e6183b2b34a8d8075092e4d8"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/depyronick/clickhouse-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fclickhouse-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fclickhouse-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fclickhouse-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fclickhouse-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/depyronick","download_url":"https://codeload.github.com/depyronick/clickhouse-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/depyronick%2Fclickhouse-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280878344,"owners_count":26406641,"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","status":"online","status_checked_at":"2025-10-24T02:00:06.418Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["clickhouse","clickhouse-client","database","driver","javascript","node","node-clickhouse","nodejs","nodejs-clickhouse","typescript"],"created_at":"2024-12-10T02:09:05.101Z","updated_at":"2025-10-24T22:39:03.893Z","avatar_url":"https://github.com/depyronick.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## clickhouse-client for NodeJS\n\n[ClickHouse®](https://clickhouse.com/) is an open-source, high performance columnar OLAP database management system for real-time analytics using SQL. ClickHouse combined with TypeScript helps you develop better type safety with your ClickHouse queries, giving you end-to-end typing.\n\n## Installation\n\nInstall the following package:\n\n```bash\n$ npm i --save @depyronick/clickhouse-client\n```\n\n## Quick Start\n\n- [Importing the module](#importing-the-module)\n- [Methods](#methods)\n  - **[Query](#query)**\n    - [`ClickHouseClient.query\u003cT\u003e(query: string): Observable\u003cstring | T\u003e`](#clickhouseclientquerytquery-string-observablestring--t)\n    - [`ClickHouseClient.queryPromise\u003cT\u003e(query: string): Promise\u003cstring | T[]\u003e`](#clickhouseclientquerypromisetquery-string-promisestring--t)\n  - **[Query with parameters](#query-with-params)**\n    - [`ClickHouseClient.query\u003cT\u003e(query: string, params: Record\u003cstring, string | number\u003e): Observable\u003cstring | T\u003e`](#clickhouseclientquerytquery-string-params-recordstring-string--number-observablestring--t)\n    - [`ClickHouseClient.queryPromise\u003cT\u003e(query: string, params: Record\u003cstring, string | number\u003e): Promise\u003cstring | T[]\u003e`](#clickhouseclientquerypromisetquery-string-params-recordstring-string--number-promisestring--t)\n  - **[Insert](#insert)**\n    - [`ClickHouseClient.insert\u003cT\u003e(table: string, data: T[]): Observable\u003cvoid\u003e`](#clickhouseclientinsertttable-string-data-t-observablevoid)\n    - [`ClickHouseClient.insertPromise\u003cT\u003e(table: string, data: T[]): Promise\u003cvoid\u003e`](#clickhouseclientinsertpromisettable-string-data-t-promisevoid)\n  - **[Other](#other)**\n    - [`ClickHouseClient.ping(timeout: number = 3000): Promise\u003cboolean\u003e`](#clickhouseclientpingtimeout-number--3000-promiseboolean)\n- [Notes](#notes)\n\n### Importing the module\n\nOnce the installation process is complete, you can import the `ClickHouseClient`\n\n```javascript\nconst { ClickHouseClient } = require('@depyronick/clickhouse-client');\n\n// or:\n// import { ClickHouseClient } from '@depyronick/clickhouse-client';\n\nconst analyticsServer = new ClickHouseClient({\n  host: '127.0.0.1',\n  password: '7h3ul71m473p4555w0rd'\n});\n\n// you can create multiple clients\nconst chatServer = new ClickHouseClient({\n  host: '127.0.0.2',\n  password: '7h3ul71m473p4555w0rd'\n});\n```\n\n`new ClickHouseClient(options: ClickHouseOptions)` will create a ClickHouse client with the specified connection options.\n\nSee **[ClickHouseOptions](https://github.com/depyronick/clickhouse-client/blob/main/src/client/interfaces/ClickHouseClientOptions.ts 'ClickHouseOptions')** object for more information.\n\n### Methods\n\n#### Query\n\n##### `ClickHouseClient.query\u003cT\u003e(query: string): Observable\u003cstring | T\u003e`\n\n```javascript\nthis.analyticsServer.query('SELECT * FROM visits LIMIT 10').subscribe({\n  error: (err) =\u003e {\n    // called when an error occurred during query\n  },\n  next: (row) =\u003e {\n    // if specified format is any of JSON formats, `row` here is the json representation of the row\n    // if format is not any of JSON, then `row` represents string chunk from http stream\n  },\n  complete: () =\u003e {\n    // called when stream is completed\n  }\n});\n```\n\n##### `ClickHouseClient.queryPromise\u003cT\u003e(query: string): Promise\u003cstring | T[]\u003e`\n\n```javascript\nthis.analyticsServer\n  .queryPromise('SELECT * FROM visits LIMIT 10')\n  .then((rows) =\u003e {\n    // if specified format is any of JSON formats, rows is an array of all retrieved rows\n    // if not, then rows is the raw string result from clickhouse-server\n  })\n  .catch((err) =\u003e {\n    // called when an error occurred during query\n  });\n\n// or\n\nconst rows = await this.analyticsServer.queryPromise(\n  'SELECT * FROM visits LIMIT 10'\n);\n```\n\n#### Query with params\n\nClickhouse-server supports performing queries with paramaters. Both `query` and `queryPromise` accept a second argument which respresents the query paramaters value as a `Record\u003cstring, string | number\u003e`.\n\nThe query can contain parameters placeholders that have the following syntax:\n\n```sql\n{\u003cname\u003e:\u003cdata type\u003e}\n-- a parameter called \"limit\" that will be interpreted as an 8-bit unsigned integer\n{limit:UInt8}\n```\n\nSo, you can pass parameters as the following:\n\n```sql\nSELECT * FROM visits LIMIT {limit:UInt8}\n```\n\n[Official documentation (HTTP Interface - Query with paramters)](https://clickhouse.com/docs/en/interfaces/http#cli-queries-with-parameters)\n\n##### `ClickHouseClient.query\u003cT\u003e(query: string, params: Record\u003cstring, string | number\u003e): Observable\u003cstring | T\u003e`\n\n```javascript\nconst yersterday = new Date();\nyesterday.setDate(yesterday.getDate() - 1);\n\nconst params = {\n  yesterday: yesterday.getTime(),\n  osName: 'OSX'\n};\n\nconst query =\n  'SELECT * FROM visits WHERE timestamp \u003e= {yesterday:DateTime} AND os = {osName:String} LIMIT 10';\n\nthis.analyticsServer.query(query, params).subscribe({\n  error: (err) =\u003e {\n    // called when an error occurred during query\n  },\n  next: (row) =\u003e {\n    // if specified format is any of JSON formats, `row` here is the json representation of the row\n    // if format is not any of JSON, then `row` represents string chunk from http stream\n  },\n  complete: () =\u003e {\n    // called when stream is completed\n  }\n});\n```\n\n##### `ClickHouseClient.queryPromise\u003cT\u003e(query: string, params: Record\u003cstring, string | number\u003e): Promise\u003cstring | T[]\u003e`\n\n```javascript\nconst yersterday = new Date();\nyesterday.setDate(yesterday.getDate() - 1);\n\nconst params = {\n  yesterday: yesterday.getTime(),\n  osName: 'OSX'\n};\n\nconst query =\n  'SELECT * FROM visits WHERE timestamp \u003e= {yesterday:DateTime} AND os = {osName:String} LIMIT 10';\n\nthis.analyticsServer\n  .queryPromise(query, params)\n  .then((rows) =\u003e {\n    // if specified format is any of JSON formats, rows is an array of all retrieved rows\n    // if not, then rows is the raw string result from clickhouse-server\n  })\n  .catch((err) =\u003e {\n    // called when an error occurred during query\n  });\n\n// or\n\nconst rows = await this.analyticsServer.queryPromise(query, params);\n```\n\n#### Insert\n\n##### `ClickHouseClient.insert\u003cT\u003e(table: string, data: T[]): Observable\u003cvoid\u003e`\n\nThe `insert` method accepts two inputs.\n\n- `table` is the name of the table that you'll be inserting data to.\n  - Table value could be prefixed with database like `analytics_db.visits`.\n- `data: T[]` array of JSON objects to insert.\n\n```javascript\nanalyticsServer\n  .insert('visits', [\n    {\n      timestamp: new Date().getTime(),\n      ip: '127.0.0.1',\n      os: 'OSX',\n      userAgent:\n        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/95.0.4638.69 Safari/537.36',\n      version: '1.0.0'\n    }\n  ])\n  .subscribe({\n    error: (err) =\u003e {\n      // called when an error occurred during insert\n    },\n    next: () =\u003e {\n      // currently next does not emits anything for inserts\n    },\n    complete: () =\u003e {\n      // called when insert is completed\n    }\n  });\n```\n\n#### `ClickHouseClient.insertPromise\u003cT\u003e(table: string, data: T[]): Promise\u003cvoid\u003e`\n\nThe `insertPromise` method accepts the same inputs as `insert` but returns a Promise, instead of Observable.\n\n```javascript\nanalyticsServer\n  .insertPromise('visits', [\n    {\n      timestamp: new Date().getTime(),\n      ip: '127.0.0.1',\n      os: 'OSX',\n      userAgent:\n        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/95.0.4638.69 Safari/537.36',\n      version: '1.0.0'\n    }\n  ])\n  .then(() =\u003e {\n    // insert was success\n  })\n  .catch((err) =\u003e {\n    // called when an error occurred during insert\n  });\n```\n\n#### Other\n\n##### `ClickHouseClient.ping(timeout: number = 3000): Promise\u003cboolean\u003e`\n\nThe `ping` method accepts one input.\n\n- `timeout` is the time in milliseconds to wait for the server to send ping response `Ok.\\n`.\n\n```javascript\n// if you're using async/await\nconst ping = await analyticsServer.ping();\n\n// or\n\nanalyticsServer\n  .then((pingResult) =\u003e {\n    // ping result is a boolean\n    // it will return `true` if we were able to receive `Ok.\\n`\n    // and `false` if anything but `Ok.\\n`\n  })\n  .catch((reason) =\u003e {\n    // reason is the full response of the error\n    // see more details at https://axios-http.com/docs/handling_errors\n  });\n```\n\n## Notes\n\n- This repository will be actively maintained and improved.\n- Planning to implement TCP protocol, if ClickHouse decides to [documentate](https://clickhouse.com/docs/en/interfaces/tcp/ 'documentate') it.\n- Planning to implement inserts with streams.\n- This library supports http response compressions such as brotli, gzip and deflate.\n\n## Stay in touch\n\n- Author - [Ali Demirci](https://github.com/depyronick)\n\n## License\n\n[MIT licensed](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepyronick%2Fclickhouse-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdepyronick%2Fclickhouse-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdepyronick%2Fclickhouse-client/lists"}