# @apla/clickhouse 中文文档

规范地址：https://npmcn.com/package/%40apla/clickhouse/

版本：1\.6\.4
npm 元数据更新时间：2022-06-12T14:43:53.845Z
中文译文更新时间：2026-11-06T10:35:16.759Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：80 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=0\.10
- 运行依赖：0 个
- 首次发布：2016-07-25T09:27:50.336Z
- 最新版本发布：2020-09-13T12:55:48.434Z
- 近 30 天下载量：22664（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 0 个）

## 中文简介

Yandex ClickHouse 数据库接口

## 安装

```sh
npm install @apla/clickhouse
```

也可以使用：`pnpm add @apla/clickhouse`、`yarn add @apla/clickhouse`、`bun add @apla/clickhouse`

## README

# 简单而强大的接口 [点击之家](https://clickhouse.yandex/) [![travis](https://travis-ci.org/apla/node-clickhouse.svg)](https://travis-ci.org/apla/node-clickhouse) [![codecov](https://codecov.io/gh/apla/node-clickhouse/branch/master/graph/badge.svg)](https://codecov.io/gh/apla/node-clickhouse)

```sh
npm install @apla/clickhouse
```

## 概要

```javascript
const ClickHouse = require('@apla/clickhouse')
const ch = new ClickHouse({ host, port, user, password })

const stream = ch.query("SELECT 1", (err, data) => {})
stream.pipe(process.stdout)

// promise interface, not recommended for selects
// (requires 'util.promisify' for node < 8, Promise shim for node < 4)
await ch.querying("CREATE DATABASE test")
```

实例:

-   [选择大数据集](https://npmcn.com/package/%40apla/clickhouse/README.md#selecting-large-dataset)
-   [插入大数据集](https://npmcn.com/package/%40apla/clickhouse/README.md#inserting-large-dataset)
-   [插入单行](https://npmcn.com/package/%40apla/clickhouse/README.md#insert-single-row-of-data)

## API 密码

### `new ClickHouse(options: Options)`

#### `Options`

|  | 所需经费 | 默认 | 说明 |
| --- | --- | :-- | :-- |
| `host` | ✓ |  | 主机要连接 . |
| `user` |  |  | 认证用户 . |
| `password` |  |  | 认证密码 . |
| `path` (单位:千美元)`pathname`(中文(简体) ) |  | `/` | ClickHouse 服务器的路径名 . |
| `port` |  | `8123` | 服务器端口号. |
| `protocol` |  | `'http:'` | `'https:'` 或者说 `'http:'`。 。 。 . |
| `dataObjects` |  | `false` | 默认( E)`false`),你会得到每行的数值阵列.  
如果你准备好了 `dataObjects: true`,每行将变成格式为: `{ fieldName: fieldValue, … }`。 。 。 .  
免职 `format: 'JSON'`。 。 。 . |
| `format` |  | `JSONCompact` | 添加 `FORMAT` 如果没有用于查询的语句.  
指定格式 [选中](https://clickhouse.yandex/docs/en/query_language/select/#format-clause) 或者说 [插入时](https://clickhouse.yandex/docs/en/query_language/insert_into/#insert) 数据.  
见 [“输入和输出数据格式”](https://clickhouse.yandex/docs/en/interfaces/formats/#formats) 查找可能的值. |
| `queryOptions` |  |  | 对象,可以包含任何来自 [设置](https://clickhouse.yandex/docs/en/operations/settings/index.html), (中文(简体) ), [限制](https://clickhouse.yandex/docs/en/operations/settings/query_complexity/) 财务报告和审定财务报表 [权限](https://clickhouse.yandex/docs/en/operations/settings/permissions_for_queries/)。 。 。 .  
见 [实例](https://npmcn.com/package/%40apla/clickhouse/README.md#settings-for-connection)。 。 。 . |
| `readonly` |  | `false` | 告诉驱动程序用 HTTP Get 方法发送查询 。 与 [`readonly=1` 设置](https://clickhouse.yandex/docs/en/operations/settings/permissions_for_queries/#settings_readonly)。 。 。 . [更多细节](https://clickhouse.yandex/docs/en/interfaces/http/)。 。 。 . |
| `timeout`, (中文(简体) ),  
`headers`, (中文(简体) ),  
`agent`, (中文(简体) ),  
`localAddress`, (中文(简体) ),  
`servername`, (中文(简体) ),  
还有.. |  |  | 任意 [http.request 请求](https://nodejs.org/api/http.html#http_http_request_options_callback) 或者说 [网页请求](https://nodejs.org/api/https.html#https_https_request_options_callback) 也可以选择. |

##### 选项示例 :

```javascript
const ch = new ClickHouse({
  host: "clickhouse.msk",
  dataObjects: true,
  readonly: true,
  queryOptions: {
    profile: "web",
    database: "test",
  },
})
```

### `clickHouse.query(query, [options], [callback])`

向服务器发送查询语句.

##### `query: string`

SQL 查询语句.

##### `options: Options`

一样 [`Options`](https://npmcn.com/package/%40apla/clickhouse/README.md#options),不包括连接选项.

##### `callback: (error, result) => void`

总是需要完成.

##### 回返情况: [`DuplexStream`](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams)

它支持 [`.pipe`](https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options) 用于处理记录.  
您至少应该有一个错误处理器在听 。 通过查询调用或通过流 `error` 活动.

| 串流事件 | 说明 |
| --- | --- |
| `'error'` | 查询执行完成时出错 .  
如果您有这两个查询 `callback` 和流 `error` 听着,你会得到错误通知 两个听众. |
| `'metadata'` | 当一列信息被解析时 . |
| `'data'` | 当一行可出. |
| `'end'` | 当处理整个响应时.
> 无论是否有 `'end'` 听者, 查询 `callback` 总是被调用.

> 你应该总是听 `'data'` 活动与 `'end'` 活动.  
> ["除非数据被完全耗尽,否则"末"事件将不会被排放"](https://nodejs.org/api/stream.html#stream_event_end)  
> 如果你不需要处理 `'data'` 事件偏好只使用 `callback` 或者说 [承诺接口](https://npmcn.com/package/%40apla/clickhouse/#readme-promise-interface)。 。 。 .

 |

##### `stream.supplemental`

处理响应后,可以从中读取补充响应数据,如行数.

实例:

-   [随流选择](https://npmcn.com/package/%40apla/clickhouse/README.md#selecting-with-stream)
-   [正在随流插入](https://npmcn.com/package/%40apla/clickhouse/README.md#inserting-with-stream)

### `clickHouse.ping(callback)`

发送空查询. 不需要授权.

##### `callback: (error, result) => void`

将呼吁完成.

  

## 承诺接口

承诺接口 **不建议** 页:1 `INSERT` 财务报告和审定财务报表 `SELECT` 查询.

-   `INSERT` 无法使用承诺接口进行批量加载数据.
-   `SELECT` 将收集内存中的全部查询结果。 见 [内存大小](https://npmcn.com/package/%40apla/clickhouse/README.md#memory-size) 节.

带有承诺界面查询结果的解析同步. 这意味着大查询导致承诺界面:

-   将同步屏蔽JS线/事件循环.
-   可能导致您的应用程序内存泄漏 最高GC负载.

仅用于已知和极小数据大小的查询.  
使用它的良好案例是 `DESCRIBE TABLE` 或者说 `EXISTS TABLE`

### `clickHouse.querying(query, [options])`

类似 `ch.query(query)` 但在内存中收集整个响应并用完整的查询结果解析.  
见 [内存大小](https://npmcn.com/package/%40apla/clickhouse/README.md#memory-size) 节.

##### `options: Options`

一样 [`Options`](https://npmcn.com/package/%40apla/clickhouse/README.md#options),不包括连接选项.

##### 回返情况: `Promise`

将用整个查询结果解决 .

实例 [承诺接口](https://npmcn.com/package/%40apla/clickhouse/README.md#promise-interface)。 。 。 .

### `clickHouse.pinging()`

承诺接口 [`.ping`](https://npmcn.com/package/%40apla/clickhouse/README.md#clickhousepingcallback)。 。 。 .

##### 回返情况: `Promise`

  

## 如何运作

### 装入大量数据 `INSERT` 声明

`INSERT` 可用于散装数据加载。 有两种易于执行的格式 带有javascript:CSV和TabSeparated/TSV.

CSV 用于从文件装入, 因此您可以读取 `.pipe` 输入点击器 文件内容.  
要激活 CSV 解析, 您应该设置 `format` 驱动程序选项或查询 `FORMAT` 声明到 `CSV`数字 :

```javascript

var csvStream = fs.createReadStream('data.csv')
var clickhouseStream = ch.query(statement, { format: CSV })

csvStream.pipe(clickhouseStream)

```

TSV对于从文件上加载和从外部来源如其他数据库上批量加载是有用的. 仅 `\\`, (中文(简体) ), `\t` 财务报告和审定财务报表 `\n` 需要用绳子来逃出; 数字, 虚数, 布尔斯和日期对象需要一些小的处理. 您可以发送已准备好的 TSV 数据字符串 (行尾会自动被附加),缓冲(总是像现在这样通过)或有字段的矩阵.

内部,每个字段都会被转换为ClickHouse可以接受的格式. 之后逃出并加入了特定格式的分隔符. 如果您需要存储行( 在数组中)并发送预格式数据, 您可以这样做 .

点击之家也支持 [约瑟纳克罗](https://clickhouse.yandex/docs/en/formats/jsoneachrow.html) 格式 用于插入 javascript 对象,如果您有这样的记录.

```js
const stream = ch.query(statement, { format: 'JSONEachRow' })

stream.write(object) // Do write as many times as possible
stream.end() // And don't forget to finish insert query
```

### 内存大小

您可以在这样的单调中将所有记录读入内存:

```javascript

var ch = new ClickHouse({ host: host, port: port })
ch.querying("SELECT number FROM system.numbers LIMIT 10", (err, result) => {
  // result will contain all the data you need
})

```

在这种情况下 服务器的JSON反应会被读入记忆中, 然后解析成记忆 占用你的CPU。 默认解析器将解析服务器响应 线条并释放出事件。 速度较慢,但内存和CPU效率要高得多 用于更大的数据集.

  

## 实例

#### 使用流选择 :

```javascript
const readableStream = ch.query(
  'SELECT * FROM system.contributors FORMAT JSONEachRow',
  (err, result) => {},
)
const writableStream = fs.createWriteStream('./contributors.json')
readableStream.pipe(writableStream)
```

#### 以流插入 :

```javascript
const readableStream = fs.createReadStream('./x.csv')
const writableStream = ch.query('INSERT INTO table FORMAT CSV', (err, result) => {})
readableStream.pipe(writableStream)
```

#### 插入单行数据 :

```javascript
const ch = new ClickHouse(options)
const writableStream = ch.query(`INSERT INTO table FORMAT TSV`, (err) => {
  if (err) {
    console.error(err)
  }
  console.log('Insert complete!')
})

// data will be formatted for you
writableStream.write([1, 2.22, "erbgwerg", new Date()])

// prepare data yourself
writableStream.write("1\t2.22\terbgwerg\t2017-07-17 17:17:17")

writableStream.end()

```

#### 选择大数据集 :

```javascript
const ch = new ClickHouse(options)
// it is better to use stream interface to fetch select results
const stream = ch.query("SELECT * FROM system.numbers LIMIT 10000000")

stream.on('metadata', (columns) => { /* do something with column list */ })

let rows = []
stream.on('data', (row) => rows.push(row))

stream.on('error', (err) => { /* handler error */ })

stream.on('end', () => {
  console.log(
    rows.length,
    stream.supplemental.rows,
    stream.supplemental.rows_before_limit_at_least, // how many rows in result are set without windowing
  )
})
```

#### 插入大数据集 :

```javascript
const ch = new ClickHouse(options)
// insert from file
const tsvStream = fs.createReadStream('data.tsv')
const clickhouseStream = ch.query('INSERT INTO table FORMAT TSV')

tsvStream.pipe(clickhouseStream)
```

#### 连接设置 :

```javascript
const ch = new ClickHouse({
  host: 'clickhouse.msk',
  queryOptions: {
    database: "test",
    profile: "web",
    readonly: 2,
    force_index_by_date: 1,
    max_rows_to_read: 10 * 1e6,
  },
})
```

#### 查询设置 :

```javascript
const ch = new ClickHouse({ host: 'clickhouse.msk' })
const stream = ch.query('INSERT INTO table FORMAT TSV', {
  queryOptions: {
    database: "test",
    insert_quorum: 2,
  },
})
```

#### 承诺接口 :

```js
const ch = new ClickHouse(options)
// Check connection to server. Doesn't requires authorization.
await ch.pinging()
```

```js
const { data } = await ch.querying("SELECT 1")
// [ [ 1 ] ]
const { data } = await ch.querying("DESCRIBE TABLE system.numbers", { dataObjects: true })
// [ { name: 'number', type: 'UInt64', default_type: '', default_expression: '' } ]
```

## 常见问题

### @apla/clickhouse 是什么？

Yandex ClickHouse 数据库接口

### 如何安装 @apla/clickhouse？

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

### @apla/clickhouse 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/apla\_\_clickhouse 是否存在。

### @apla/clickhouse 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @apla/clickhouse 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=0\.10。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @apla/clickhouse 可以商用吗？

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

### @apla/clickhouse 的下载量有多少？

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

### @apla/clickhouse 还在维护吗？

最新版本 1\.6\.4 发布于 2020/09/13（6 年前）；至今共发布 16 个版本，其中过去 12 个月发布了 0 个；首次发布于 2016/07/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。