@gscdump/发动机
在 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 选项 | 默认 | 接纳规则 |
|---|---|---|
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: REST客户端和查询构建器(edge-seafe perer dep).@gscdump/analysis:分析器;通过AnalysisQuerySource适应器.@gscdump/engine-duckdb-wasm: DuckDB-WASM浏览器适配器.@gscdump/engine-sqlite: SQLite / D1 适配器.@gscdump/lakehouse: 数据集-不可知性 Iceberg 目录和 数据集注册 API.@gscdump/cli: CLI包装引擎与分析.