# @depyronick/clickhouse-client 中文文档

规范地址：https://npmcn.com/package/%40depyronick/clickhouse-client/

版本：2\.1\.0
npm 元数据更新时间：2026-01-21T11:47:51.472Z
中文译文更新时间：2026-11-12T00:27:07.701Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40depyronick/clickhouse-client
原文对照：https://npmcn.com/package/%40depyronick/clickhouse-client/?lang=original
项目主页：https://github.com/depyronick/clickhouse-client#readme
源码仓库：https://github.com/depyronick/clickhouse-client

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：193 kB，30 个文件
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2021-11-19T00:20:11.498Z
- 最新版本发布：2026-01-21T11:47:51.341Z
- 近 30 天下载量：5101（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：21（近 12 个月 1 个）

## 中文简介

点击节点JS的家用客户端 .

## 安装

```sh
npm install @depyronick/clickhouse-client
```

也可以使用：`pnpm add @depyronick/clickhouse-client`、`yarn add @depyronick/clickhouse-client`、`bun add @depyronick/clickhouse-client`

## README

## 节点JS 的点击之家客户端

[点击之家](https://clickhouse.com/) 是使用SQL进行实时分析的开源高性能专栏OLAP数据库管理系统. 与 TypeScript 结合的 ClickHouse 帮助您在您的 ClickHouse 查询中开发更好的类型安全性, 并给予您端到端的打字功能 .

## 安装

安装以下软件包:

```bash
$ npm i --save @depyronick/clickhouse-client
```

## 快速启动

-   [导入模块](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-importing-the-module)
-   [方法](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-methods)
    -   **[查询](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-query)**
        -   [`ClickHouseClient.query<T>(query: string): Observable<string | T>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientquerytquery-string-observablestring--t)
        -   [`ClickHouseClient.queryPromise<T>(query: string): Promise<string | T[]>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientquerypromisetquery-string-promisestring--t)
    -   **[查询参数](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-query-with-params)**
        -   [`ClickHouseClient.query<T>(query: string, params: Record<string, string | number>): Observable<string | T>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientquerytquery-string-params-recordstring-string--number-observablestring--t)
        -   [`ClickHouseClient.queryPromise<T>(query: string, params: Record<string, string | number>): Promise<string | T[]>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientquerypromisetquery-string-params-recordstring-string--number-promisestring--t)
    -   **[插入](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-insert)**
        -   [`ClickHouseClient.insert<T>(table: string, data: T[]): Observable<void>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientinsertttable-string-data-t-observablevoid)
        -   [`ClickHouseClient.insertPromise<T>(table: string, data: T[]): Promise<void>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientinsertpromisettable-string-data-t-promisevoid)
        -   [`ClickHouseClient.insertRaw(table: string, data: string | Buffer | Readable, format: ClickHouseDataFormat): Observable<void>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientinsertrawtable-string-data-string--buffer--readable-format-clickhousedataformat-observablevoid)
    -   **[其它](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-other)**
        -   [`ClickHouseClient.ping(timeout: number = 3000): Promise<boolean>`](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-clickhouseclientpingtimeout-number--3000-promiseboolean)
-   [页:1](https://npmcn.com/package/%40depyronick/clickhouse-client/#readme-notes)

### 导入模块

一旦安装过程完成,您就可以导入 `ClickHouseClient`

```javascript
const { ClickHouseClient } = require('@depyronick/clickhouse-client');

// or:
// import { ClickHouseClient } from '@depyronick/clickhouse-client';

const analyticsServer = new ClickHouseClient({
  host: '127.0.0.1',
  password: '7h3ul71m473p4555w0rd'
});

// you can create multiple clients
const chatServer = new ClickHouseClient({
  host: '127.0.0.2',
  password: '7h3ul71m473p4555w0rd'
});
```

`new ClickHouseClient(options: ClickHouseOptions)` 将创建具有指定连接选项的 ClickHouse 客户端.

见 **[点击之家选项](https://github.com/depyronick/clickhouse-client/blob/main/src/client/interfaces/ClickHouseClientOptions.ts "ClickHouseOptions")** 对象以获取更多信息.

### 方法

#### 查询

##### `ClickHouseClient.query<T>(query: string): Observable<string | T>`

```javascript
this.analyticsServer.query('SELECT * FROM visits LIMIT 10').subscribe({
  error: (err) => {
    // called when an error occurred during query
  },
  next: (row) => {
    // if specified format is any of JSON formats, `row` here is the json representation of the row
    // if format is not any of JSON, then `row` represents string chunk from http stream
  },
  complete: () => {
    // called when stream is completed
  }
});
```

##### `ClickHouseClient.queryPromise<T>(query: string): Promise<string | T[]>`

```javascript
this.analyticsServer
  .queryPromise('SELECT * FROM visits LIMIT 10')
  .then((rows) => {
    // if specified format is any of JSON formats, rows is an array of all retrieved rows
    // if not, then rows is the raw string result from clickhouse-server
  })
  .catch((err) => {
    // called when an error occurred during query
  });

// or

const rows = await this.analyticsServer.queryPromise(
  'SELECT * FROM visits LIMIT 10'
);
```

#### 用参数查询

点击house-server支持使用参数执行查询. 两者 `query` 财务报告和审定财务报表 `queryPromise` 接受将查询参数值重新显示为 `Record<string, string | number>`。 。 。 .

查询中可以包含具有以下语法的参数占位符:

```sql
{<name>:<data type>}
-- a parameter called "limit" that will be interpreted as an 8-bit unsigned integer
{limit:UInt8}
```

因此,你可以通过参数如下:

```sql
SELECT * FROM visits LIMIT {limit:UInt8}
```

[官方文档( HTTP 接口 - 有参数查询)](https://clickhouse.com/docs/en/interfaces/http#cli-queries-with-parameters)

##### `ClickHouseClient.query<T>(query: string, params: Record<string, string | number>): Observable<string | T>`

```javascript
const yersterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);

const params = {
  yesterday: yesterday.getTime(),
  osName: 'OSX'
};

const query =
  'SELECT * FROM visits WHERE timestamp >= {yesterday:DateTime} AND os = {osName:String} LIMIT 10';

this.analyticsServer.query(query, params).subscribe({
  error: (err) => {
    // called when an error occurred during query
  },
  next: (row) => {
    // if specified format is any of JSON formats, `row` here is the json representation of the row
    // if format is not any of JSON, then `row` represents string chunk from http stream
  },
  complete: () => {
    // called when stream is completed
  }
});
```

##### `ClickHouseClient.queryPromise<T>(query: string, params: Record<string, string | number>): Promise<string | T[]>`

```javascript
const yersterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);

const params = {
  yesterday: yesterday.getTime(),
  osName: 'OSX'
};

const query =
  'SELECT * FROM visits WHERE timestamp >= {yesterday:DateTime} AND os = {osName:String} LIMIT 10';

this.analyticsServer
  .queryPromise(query, params)
  .then((rows) => {
    // if specified format is any of JSON formats, rows is an array of all retrieved rows
    // if not, then rows is the raw string result from clickhouse-server
  })
  .catch((err) => {
    // called when an error occurred during query
  });

// or

const rows = await this.analyticsServer.queryPromise(query, params);
```

#### 插入

##### `ClickHouseClient.insert<T>(table: string, data: T[]): Observable<void>`

这个 `insert` 方法接受两个输入.

-   `table` 是您要插入数据的表格的名称.
    -   表格值可以使用数据库的前缀, 如 `analytics_db.visits`。 。 。 .
-   `data: T[]` 要插入的 JSON 对象数组.

```javascript
analyticsServer
  .insert('visits', [
    {
      timestamp: new Date().getTime(),
      ip: '127.0.0.1',
      os: 'OSX',
      userAgent:
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/95.0.4638.69 Safari/537.36',
      version: '1.0.0'
    }
  ])
  .subscribe({
    error: (err) => {
      // called when an error occurred during insert
    },
    next: () => {
      // currently next does not emits anything for inserts
    },
    complete: () => {
      // called when insert is completed
    }
  });
```

#### `ClickHouseClient.insertPromise<T>(table: string, data: T[]): Promise<void>`

这个 `insertPromise` 方法接受的输入与 `insert` 惟你应当以约言回报,而不是以可观察的.

```javascript
analyticsServer
  .insertPromise('visits', [
    {
      timestamp: new Date().getTime(),
      ip: '127.0.0.1',
      os: 'OSX',
      userAgent:
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/95.0.4638.69 Safari/537.36',
      version: '1.0.0'
    }
  ])
  .then(() => {
    // insert was success
  })
  .catch((err) => {
    // called when an error occurred during insert
  });
```

##### `ClickHouseClient.insertRaw(table: string, data: string | Buffer | Readable, format: ClickHouseDataFormat): Observable<void>`

使用 `insertRaw` 以发送 CSV 或 JSONAsString 等预格式化数据.

```javascript
// insert a raw JSON object into a single String column
await analyticsServer.insertRawPromise(
  'sensor_raw',
  '{"source":"test","uid":"test"}',
  ClickHouseDataFormat.JSONAsString
);

// insert CSV payload
await analyticsServer.insertRawPromise(
  'visits',
  'timestamp,ip,os\n1700000000,127.0.0.1,OSX\n',
  ClickHouseDataFormat.CSV
);
```

#### 其它

##### `ClickHouseClient.ping(timeout: number = 3000): Promise<boolean>`

这个 `ping` 方法接受一个输入.

-   `timeout` 是等待服务器发送 ping 响应的以毫秒计的时间 `Ok.\n`。 。 。 .

```javascript
// if you're using async/await
const ping = await analyticsServer.ping();

// or

analyticsServer
  .then((pingResult) => {
    // ping result is a boolean
    // it will return `true` if we were able to receive `Ok.\n`
    // and `false` if anything but `Ok.\n`
  })
  .catch((reason) => {
    // reason is the full response of the error
    // see more details at https://axios-http.com/docs/handling_errors
  });
```

## 页:1

-   将积极维持和改进这一储存库.
-   计划执行 TCP 协议,如果 ClickHouse 决定 [文档](https://clickhouse.com/docs/en/interfaces/tcp/ "documentate") 这个.
-   计划执行带有流的插入.
-   这个库支持http响应压缩,如brotli,gzip和deflate等.

## 保持联系

-   作者 - 翻译 [阿里·德米尔奇](https://github.com/depyronick)

## 许可证

[麻省理工学院执照](https://npmcn.com/package/%40depyronick/clickhouse-client/LICENSE)。 。 。 .

## 常见问题

### @depyronick/clickhouse-client 是什么？

点击节点JS的家用客户端 \.

### 如何安装 @depyronick/clickhouse-client？

在项目目录运行 npm install @depyronick/clickhouse-client，或使用 pnpm add / yarn add / bun add。

### @depyronick/clickhouse-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @depyronick/clickhouse-client 可以商用吗？

@depyronick/clickhouse-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @depyronick/clickhouse-client 的下载量有多少？

根据 npm 官方下载统计，@depyronick/clickhouse-client 在 2026/10/12 – 2026/11/10 这 30 天内被下载 5,101 次，日均约 170 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @depyronick/clickhouse-client 还在维护吗？

最新版本 2\.1\.0 发布于 2026/01/21（9 个月前）；至今共发布 21 个版本，其中过去 12 个月发布了 1 个；首次发布于 2021/11/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。