@gscdump/engine

中文文档
7.15.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 1万

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

中文使用文档
文档目录5 节
  1. 安装
  2. 子路径导出
  3. 稳定
  4. 相关
  5. 许可证

@gscdump/发动机

npm version npm downloads license

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

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

安装

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 政策:

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

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

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

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

子路径导出

子路径目的
@gscdump/engine存储运行时间 : createStorageEngine、编码/执行工厂、储存合同.
@gscdump/engine/contractsStorageEngine, (中文(简体) ), Row, (中文(简体) ), TableName, (中文(简体) ), WriteCtx, (中文(简体) ), ManifestEntry,, , , , , , , , .
@gscdump/engine/schemaSCHEMAS, (中文(简体) ), allTables, (中文(简体) ), inferTable,栏元数据.
@gscdump/engine/plannerresolveToSQL, (中文(简体) ), enumeratePartitions,分区规划.
@gscdump/engine/ingestGSC行 – 存储行助手(createRowAccumulator, (中文(简体) ), transformGscRow) (中文(简体) ).
@gscdump/engine/ingest-accumulator喷入的存储和回收钩后面的 国产入水冲.
@gscdump/engine/sqlSQL 字面绑定帮助者(bindLiterals, (中文(简体) ), formatLiteral) (中文(简体) ).
@gscdump/engine/sql-fragments可重复使用的 SQL 碎片在分析器之间共享 .
@gscdump/engine/rollups预集出卷合同与助行.
@gscdump/engine/entitiesParquet支持的实体商店及其记录合同.
@gscdump/engine/entity-keys纯实体对象键和 URL- hash 帮助器, 没有 Parquet 运行时间 .
@gscdump/engine/resolver发光中性 SQL 成分 : ResolverAdapter, (中文(简体) ), pgResolverAdapter, (中文(简体) ), resolveToSQL。 。 。 .
@gscdump/engine/scope多租界范围上游.
@gscdump/engine/arrowApache箭头用于引擎结果转换的公用设备.
@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/engine 共发布 268 个版本,首次发布于 2026/04/27;过去 12 个月发布了 268 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
7.15.0latest2026/11/16今天
7.14.02026/11/16今天
7.13.22026/11/151 天前
7.13.12026/11/152 天前
7.13.02026/11/124 天前
7.12.12026/11/116 天前

关于 @gscdump/engine 的常见问题

@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 和提交记录判断。