# @gscdump/engine 中文文档

规范地址：https://npmcn.com/package/%40gscdump/engine/

版本：7\.15\.0
npm 元数据更新时间：2026-11-16T15:36:59.595Z
中文译文更新时间：2026-11-17T01:53:27.051Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gscdump/engine
原文对照：https://npmcn.com/package/%40gscdump/engine/?lang=original
项目主页：https://github.com/harlan-zw/gscdump/tree/main/packages/engine#readme
源码仓库：https://github.com/harlan-zw/gscdump

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

- 包体积（解压后）：1.1 MB，389 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：6 个
- peer 依赖：@duckdb/node-api ^1\.5\.5-r\.4
- 首次发布：2026-04-27T04:55:31.224Z
- 最新版本发布：2026-11-16T15:36:59.153Z
- 近 30 天下载量：10417（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：268（近 12 个月 268 个）

## 中文简介

只为gscdump输油管追加了 Parquet/DuckDB存储引擎+规划器+适配器. 节点+边缘运行时间;可选入重同位素.

## 安装

```sh
npm install @gscdump/engine
```

也可以使用：`pnpm add @gscdump/engine`、`yarn add @gscdump/engine`、`bun add @gscdump/engine`

## README

# @gscdump/发动机

[![npm version](https://img.shields.io/npm/v/@gscdump/engine?color=yellow)](https://npmjs.com/package/@gscdump/engine) [![npm downloads](https://img.shields.io/npm/dm/@gscdump/engine?color=yellow)](https://npm.chart.dev/@gscdump/engine) [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)

在 Parquet 文件中存储搜索控制台数据并用 DuckDB 查询. 这个软件包还提供了源合同,SQL分辨率,以及运行时间适配器.

选择运行时间的导出 . 节点文件系统和 DuckDB 帮助者生活在专用子路径上.

## 安装

```bash
npm install @gscdump/engine
```

`@duckdb/node-api` 是节点运行时间的可选对等点. CLI 安装此对等点 。 浏览器消费者使用 `@gscdump/engine-duckdb-wasm`。 。 。 . 软件包包括 `hyparquet` 财务报告和审定财务报表 `hyparquet-writer` 用于JavaScript Parquet编码和解码.

这个 `/hyparquet` 编码器接受可选 `fileMetadata: Record<string, string>`数字 : 使用情况 `encodeRowsToParquet(table, rows, { fileMetadata })`,或将其纳入 选项 `encodeRowsToParquetFlex`。元数据存储在文件页脚中,而不是作为事实 列,包括空文件。 用于确定编码的钥匙; 省去元数据或通过一个空对象会保存已存在的字节. 出版物协调员可以提供一个独特的标识符,从 不同的出版物产生不同的字节. 它必须保留并重放 用于重试的精确编码字节; 此选项不提供发布或 恢复协调本身.

对于一个有界限,已经订购的来源, `/hyparquet` 还出口 `encodeParquetRowBatches(batches, options, write)`它消耗同步或同步 批次,强制宣布 `columns` 物理类型与 数组编码器,并通过一个等待的字节回调发送一个 Parquet 文件 . 它不排序、复制、重试或发布对象。 借回电话 其字节直到其承诺实现;如果保留,则复制块。 打电话的人 在任何错误,包括出错时,必须中止/丢弃整个目的地 写脚印的时候 重新打开相同的不可变源 选项生成相同的字节,而不论生产者批量边界. 这支持计数/分数通行证,然后是单独协调的 固定长上传,不由解码器拥有传输或执行语义.

流媒体编码器通常在保留页脚/索引描述符时拒绝 超过 `limits.maxRetainedMetadataBytes` (8 MiB默认). 对于广泛的价值, 呼叫者可以明确选择 `metadataOverflow: 'omit-statistics'`。在 首个溢出时省略了分栏统计和分栏索引 包括早期的组合 折叠索引 编码描述符, 计划、行数、数据/词典页和明确 `fileMetadata` 保留 不变。 要求的说明必须仍然符合同样的预算,而且 组/脚输出-缓冲限制仍然适用。 统计缺失意味着未知 边框,因此读者可以扫描更多的页面或组;它们并不意味着空数据. 如果没有溢出,此选项保留了正常的字节. 它的界限 保留了可选的描述符,而不是其瞬间构造或总堆积. 数组编码器和所有省略选项行为保持不变.

`decodeParquetRowGroups({ byteLength, slice }, options)` 读取精确的字节范围 并默认一次产生一个物理行组。 呼叫者必须把每个范围都钉上 改为同一不可变物体或ETag。 保留现有日期, 栏 投影、行窗口和过滤行为。 缺席、腐败、过大或 不完全读取文件抛出; 只有有效的空 Parquet 输出无行 .

区域阅读器单独接受可选 `indexedRowWindow` 政策:

```ts
decodeParquetRowGroups(pinnedObject, {
  indexedRowWindow: {
    targetRows: 1000,
    requiredIndexedColumns: ['query', 'url'],
    rangeCacheBytes: 2 * 1024 * 1024,
  },
})
```

每个组仅在所有指定列出现、选中时使用窗口, 拥有可用的相抵索引描述符,没有词典编码。 这个 schema只必须包含平平的scalar/UTF8/date字段; 二进制, 嵌入式等 不支持的策略保留原组已读 。 不符合资格的群体使用 原始的未标记路径,所以 `targetRows` 是一个目标,而不是一个硬批 限制。 将每个潜在的大列包含在 `requiredIndexedColumns`。 。 。 . 所有现有的物理组接纳限制仍然有效.

在发布合格组的第一个窗口前,读者检查索引 用于预测列的结构,或用于过滤器可能需要时的所有索引列 未预测字段: 第0行, 增加行位置, 命令不重叠 页面范围和物理列界限。 失败投出而不退 部分输出后。 假设元数据行抵消与物理一致 页面内容; 它不独立验证页面标题行数或 检测每一个故意一致但虚假的索引.

可选范围缓存默认为零,最多允许2个米B有效载荷和 128个条目,仅通过一个合格组群生活. 已经清理完毕 补全、出错或执行器返回;另一通路重读被绑定的对象. 它不缓存解码行或提供出版物/ETag协调. 窗口 否则可以重读相重叠的页面并大幅度地增加I/O范围. 它们仍然解码整个边界页,其他列中的词典可以 仍然全额分配。 这些选项不绑定已解压缩的页面大小或 总堆积; 不变的倒数还保留了它现有的内存成本. 缓冲解码器,编码器和所有省略选项行为保持不变.

范围阅读器也可以选择使用 `limits.maxReadAndDecompressBytes`。这是 **每个物理组累计缓冲工作预算**,并共享所有 索引窗口和并列读取。 它指控请求的来源范围 发送前的字节和 SNAPPY 输出字节后再分配固定大小 输出缓冲器。 缓存命中不分配另一个区域, 而重复 减压仍然消耗预算。 包含分组索引 foller有其单独的元数据限制. 原始/未压缩页面和V2级 被范围电荷覆盖,所以压缩数据被刻意计数 两次 先前的收费从未退还,包括在读取失败后。 失败 或执行人返回 关闭预算, 防止新工作 和拒绝迟到 范围结果。 无法物理取消已发送的 : 范围 源接口没有取消钩头 .

ZSTD 解压在此选项下拒绝: 当前分配的解码器 可以在检查 Parquet 输出大小之前从其帧标题中分配. 没有选项,ZSTD和所有已存在的解码行为保持不变. 预算不测量 JavaScript 字符串,扩展值,行容器, 内部预选或字典/页缝合副本、编码工作状态或 调用保留批次。 没错 并非总的堆积捆绑或防止所有不整齐的 Parquet 内容. 它可以拒绝先前已解码的有效文件,特别是其旧文件 写入器未压缩页脚大小。 呼叫者必须保存这些文件 并选择自己的明确重试/修复政策;拒绝绝不是空数据.

`decodeParquetRowGroups(source, { boundedValues: {} })` 选择单独的严格 值-曲线路径。 它支持平整的REQUIRED/OPIAL平板柱,明确 附加说明的UTF8/STRING、PLAIN和字典数据页(V1/V2)和SNAPY或 数据不详。 投影、物理行距、无数据、日期正常化和 排行顺序保留下来 。 巢穴/二进制/其他逻辑类型、其他解码器或值 编码、BOOLEAN词典、过滤器和 `indexedRowWindow` 组合 拒绝; 这种模式从不默默地回归到渴望的读者. 全部选中 在第一个输出前检查页头以检测后期不支持 页面。 腐败的值体或超限的单个值在 更早批次; 消费者必须先完成全部输入的验证 发布替换. 这种严格模式中的明确行界限必须是非负式安全整数 也接受了无限期的无穷无尽 `rowEnd`。允许的界限使用 全部输入,且倒转或零长区域为空.

光标最多保留一个当前数据页和一个编码词典 选定列。 UTF8 字符串、 定义级别和字典ID 被消耗 递增。 字典保留了编码字节和一个四字节相抵 条目,而不是一组已解码的字符串。 最后的位包垫是 已验证但未扩展。 这些选项有独立的含义:

| `boundedValues` 选项 | 默认 | 接纳规则 |
| --- | --- | --- |
| `targetRows` | 1 000个 | 硬排放批次行限制 |
| `maxBatchBytes` | 1个小米B | 实现前:每行128个,每细胞槽16个,每细胞64个外加2个UTF8字节长度或32个固定平板 |
| `maxValueBytes` | 256基贝 | 在解码前编码一个字符串的字节 |
| `maxActiveBytes` | 24个小米B | 每组:每列最大压缩+未压缩数据页之和,字典压缩+未压缩字节,字典相抵表,外加一个最大页眉探测器 |
| `maxPages` | 16384 (英语) | 在所选输入中保留页面描述符 |
| `maxHeaderBytes` | 64 基贝 | 页眉探针盖; 起于 512 字节并仅生长于切换上 |
| `maxDictionaryEntries` | 10万个 | 每个编码词典的条目数 |

活动缓冲录入使用真实的页头,而不是经常被低估的页头 遗产作家页脚中的未压缩大小. 页面转换释放旧的 光标在读取/解压缩其后继者之前;列按顺序加载. 批量字节是一种保守的价值-物质化电荷, **非计量 v8物体的间接费用或孤立堆积担保**。页脚( 单独) 边框),分页对象,固定光标/schema状态,调用器保留 分批、编码/运行时间间接费用和同时进行的应用工作仍然分开. 设定较大的限制,故意允许更大的工作组合。 单页 仍然完全解压,一个保留所有排放批量的消费者 取去利益. 此模式不会使任意的恶意文件安全.

现有 `maxReadAndDecompressBytes` 选项也适用:组头 探测器、物理读物和SNAPY产出共享一个累积预算。 页眉 扫描一次; 需要永久/固定对象字节进行扫描 而后读取. 显示器返回/ 错误释放光标引用; 已经 发送源读取不能被物理中止 。 默认, 缓冲 解码器和有索引的窗口资格/回落没有变化.

两种API都有可配置的入场限制. 编码器绑定生产商 批次行/ 值字节, 输出组行/ 值字节, 保留描述符计数 和 scalar 字节(包括统计),以及当前编码的组/脚 缓冲。 解码器检查脚印大小, 描述符计数,声明组行/未压缩字节,以及每个范围请求. 默认解码器接受已存在的编码器的25,000行组. 这些 限制不建立工人堆积担保:呼叫者保留行,代码c 临时分配、页脚描述和同时提出的请求仍在使用 记忆。 元数据限制不是防止恶意的 Parquet 内容. 现有的数组 API 及其默认字节不变.

## 子路径导出

| 子路径 | 目的 |
| --- | --- |
| `@gscdump/engine` | 存储运行时间 : `createStorageEngine`、编码/执行工厂、储存合同. |
| `@gscdump/engine/contracts` | `StorageEngine`, (中文(简体) ), `Row`, (中文(简体) ), `TableName`, (中文(简体) ), `WriteCtx`, (中文(简体) ), `ManifestEntry`,, , , , , , , , . |
| `@gscdump/engine/schema` | `SCHEMAS`, (中文(简体) ), `allTables`, (中文(简体) ), `inferTable`,栏元数据. |
| `@gscdump/engine/planner` | `resolveToSQL`, (中文(简体) ), `enumeratePartitions`,分区规划. |
| `@gscdump/engine/ingest` | GSC行 – 存储行助手(`createRowAccumulator`, (中文(简体) ), `transformGscRow`) (中文(简体) ). |
| `@gscdump/engine/ingest-accumulator` | 喷入的存储和回收钩后面的 国产入水冲. |
| `@gscdump/engine/sql` | SQL 字面绑定帮助者(`bindLiterals`, (中文(简体) ), `formatLiteral`) (中文(简体) ). |
| `@gscdump/engine/sql-fragments` | 可重复使用的 SQL 碎片在分析器之间共享 . |
| `@gscdump/engine/rollups` | 预集出卷合同与助行. |
| `@gscdump/engine/entities` | Parquet支持的实体商店及其记录合同. |
| `@gscdump/engine/entity-keys` | 纯实体对象键和 URL- hash 帮助器, 没有 Parquet 运行时间 . |
| `@gscdump/engine/resolver` | 发光中性 SQL 成分 : `ResolverAdapter`, (中文(简体) ), `pgResolverAdapter`, (中文(简体) ), `resolveToSQL`。 。 。 . |
| `@gscdump/engine/scope` | 多租界范围上游. |
| `@gscdump/engine/arrow` | Apache箭头用于引擎结果转换的公用设备. |
| `@gscdump/engine/node` | 仅节点 DuckDB 手柄 . |
| `@gscdump/engine/filesystem` | 只节点 `DataSource` 财务报告和审定财务报表 `ManifestStore` 适应器. |
| `@gscdump/engine/hyparquet` | 纯JS `ParquetCodec`。 。 。 . |
| `@gscdump/engine/r2` | 云纹R2 `DataSource` 财务报告和审定财务报表 `createR2ManifestStore` (结构式打出,与 `R2Bucket`) (中文(简体) ). |
| `@gscdump/engine/iceberg` | 边缘安全GSC数据集计划,目录包装和附件槽. 普通 Iceberg API 居住区 `@gscdump/lakehouse`。 。 。 . |
| `@gscdump/engine/sink-node` | 只有节点的 Iceberg 覆盖/删除了恢复写入器 . |
| `@gscdump/engine/source` | 原始合同和工厂. |
| `@gscdump/engine/analyzer` | 分析员合同、登记册建造和发送. |
| `@gscdump/engine/report` | 报告定义和合同. |
| `@gscdump/engine/period` | 日期窗口和比较范围. |
| `@gscdump/engine/analysis-types` | 分析参数和结果. |
| `@gscdump/engine/analysis-range` | 分析日期分辨率. |
| `@gscdump/engine/errors` | 标记引擎失败 . |
| `@gscdump/engine/profile` | 查询时间和特征分析帮助者. |
| `@gscdump/engine/sync-config` | 同步限制和表格/搜索类型配置 . |
| `@gscdump/engine/vendor/hysnappy` | 工人相容压缩别名. |

## 稳定

| 表面 | 稳定 |
| --- | --- |
| `createStorageEngine` 和储存合同`StorageEngine`, (中文(简体) ), `Row`, (中文(简体) ), `WriteCtx`, (...) (中文(简体) ) | 公开 |
| 适应器`/node`, (中文(简体) ), `/filesystem`, (中文(简体) ), `/hyparquet`, (中文(简体) ), `/r2`(中文(简体) ) | 公开 |
| 规划员(`resolveToSQL`, (中文(简体) ), `enumeratePartitions`(中文(简体) ) | 公开 |
| 司马 (`SCHEMAS`, (中文(简体) ), `allTables`, (...) (中文(简体) ) | 公开 |
| 声明包导出以外的文件 | 私营 |

## 相关

-   [`gscdump`](https://npmcn.com/package/%40gscdump/gscdump) : REST客户端和查询构建器(edge-seafe perer dep).
-   [`@gscdump/analysis`](https://npmcn.com/package/%40gscdump/analysis) :分析器;通过 `AnalysisQuerySource` 适应器.
-   [`@gscdump/engine-duckdb-wasm`](https://npmcn.com/package/%40gscdump/engine-duckdb-wasm) : DuckDB-WASM浏览器适配器.
-   [`@gscdump/engine-sqlite`](https://npmcn.com/package/%40gscdump/engine-sqlite) : SQLite / D1 适配器.
-   [`@gscdump/lakehouse`](https://npmcn.com/package/%40gscdump/lakehouse) : 数据集-不可知性 Iceberg 目录和 数据集注册 API.
-   [`@gscdump/cli`](https://npmcn.com/package/%40gscdump/cli) : CLI包装引擎与分析.

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @gscdump/engine 是什么？

只为gscdump输油管追加了 Parquet/DuckDB存储引擎\+规划器\+适配器\. 节点\+边缘运行时间;可选入重同位素\.

### 如何安装 @gscdump/engine？

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

### @gscdump/engine 支持 TypeScript 吗？

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

### @gscdump/engine 支持 ESM 还是 CommonJS？

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

### @gscdump/engine 需要什么版本的 Node\.js？

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

### @gscdump/engine 可以商用吗？

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

### @gscdump/engine 的下载量有多少？

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

### @gscdump/engine 还在维护吗？

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

