# @graffy/clickhouse 中文文档

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

版本：0\.19\.7
npm 元数据更新时间：2026-09-16T04:47:16.456Z
中文译文更新时间：2026-11-17T04:07:20.098Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：49.1 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@clickhouse/client ^1\.17\.0
- 首次发布：2026-03-27T10:01:27.810Z
- 最新版本发布：2026-09-16T04:47:16.069Z
- 近 30 天下载量：6833（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

ClickHouse的Graffy供应商.

## 安装

```sh
npm install @graffy/clickhouse
```

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

## README

# 点击之家提供者

ClickHouse的Graffy供应商.

目前的规模是故意最小的,重点放在类似追踪器的工作量上:

-   身份证读取和 `$key` 读取
-   范围参数 : `$all`, (中文(简体) ), `$first`, (中文(简体) ), `$last`, (中文(简体) ), `$order`, (中文(简体) ), `$after`, (中文(简体) ), `$before`
-   过滤操作符 : `$eq`, (中文(简体) ), `$not`, (中文(简体) ), `$lt`, (中文(简体) ), `$lte`, (中文(简体) ), `$gt`, (中文(简体) ), `$gte`, (中文(简体) ), `$re`, (中文(简体) ), `$ire`, (中文(简体) ), `$text`, (中文(简体) ), `$cts`,加上列表简写(`prop: [a, b]`(中文(简体) )
-   `$text` 执行对大小写不敏感的子字符串搜索,并为 匹配 `lowerUTF8(column)` `ngrambf_v1` 指数。 为本地人 `Array(...)` 栏, `$cts` 检查所提供的每个值是否存在.
-   JSON 编码字符串列和本地的 Dot- path 过滤器 `Map(...)` 栏(例如 `sources.messageId` 或者说 `recordIds.gmailMessageId`(中文(简体) )
-   投影推倒ID和 `$key` 读取。 仅选择请求的 Graffy 列加上读取元数据所需的ID、版本和排序值 和帕吉纳克。 JSON- 编码字符串使用的嵌入式预测 `JSONExtractRaw`; 本地语 `JSON` 预测读取直接分栏。 两者都是 在解码前重建为请求的嵌入形状.
-   通过子点加入过滤器( 例如 ) `$key: { syncJob: { ... } }`(中文(简体) )
-   合计数 : `$count`, (中文(简体) ), `$sum`, (中文(简体) ), `$avg`, (中文(简体) ), `$max`, (中文(简体) ), `$min`, (中文(简体) ), `$card` 与 `$group: true` 财务报告和审定财务报表 `$group: [..]`
-   写: 单行 ID 写入 `$put`

默认的表格模式仅为附件 `MergeTree`。阅读不添加 `FINAL` 除非您明确选择加入 `final: true` 为了遗产 `ReplacingMergeTree` 页:1.

写入支持仅为附件 . `$put` 强制的,写作必须瞄准一个 scalar id路径,适配器总是进行盲入插入. 过滤器写入, 补丁样式 不支持更新和删除.

默认 `idCol` 实值 `id`默认值 `verCol` 实值 `time`。 。 。 .

`idCol` 财务报告和审定财务报表 `verCol` 必须是 Graffy 兼容的: 装入 ClickHouse客户端应该是字符串或数字. `verCol` 也应该是 由表格支持 `DEFAULT` 表达式。 如果书写为 `verCol`中,插入为-s。 如果没有,则从插入中省去一栏 并单击之家提供默认值.

## E2E测试

点击之家 e2e 覆盖居住在 `src/clickhouse/test/e2e.test.js`。 。 。 .

-   启动服务器 : `npm run ch:up`
-   停止/ 清理服务器 : `npm run ch:clean`
-   运行 ClickHouse 测试(单位 + e2e ): `npm test -- src/clickhouse`

## 常见问题

### @graffy/clickhouse 是什么？

ClickHouse的Graffy供应商\.

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

在项目目录运行 npm install @graffy/clickhouse，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@clickhouse/client（^1\.17\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

@graffy/clickhouse 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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

