@gscdump/lakehouse

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

数据集-不可知性冰山湖地层+R2数据目录制作方数据集登记(ADR-0021).

中文使用文档
文档目录7 节
  1. 安装
  2. 公众表面
  3. 立面显示读取限制
  4. 附加重试
  5. 明显合并
  6. 恢复表格
  7. 许可证

@gscdump/ 莱克豪斯

数据集-不可知性 Iceberg 目录、 计划、 和数据集- 原始记录 R2 数据目录制作者.

安装

npm install @gscdump/lakehouse

需要22号节点或更新.

公众表面

  • @gscdump/lakehouse: 连接到目录,定义数据集,生成表格 规格,解析数据文件,并使用bigint-security序列化.
  • @gscdump/lakehouse/bigint:无目录的 JSON 安全助手 节相依.
  • @gscdump/lakehouse/schema:轻量级共享计数常数.
  • @gscdump/lakehouse/maintenance: 稳定的承付分类,显示 合并和孤儿清理工作流程.
  • @gscdump/lakehouse/provisioning:通过、分配或提供 R2 数据 编目资源.
  • @gscdump/lakehouse/unsafe-raw: 包适配器的明确逃生舱口 和原始元数据诊断。 应用程序维护属于马厩 维护子路径.
import { connectIcebergCatalog, listIcebergTables } from '@gscdump/lakehouse'

// Supply your catalog connection configuration.
const connection = await connectIcebergCatalog(config)
const tables = await listIcebergTables(connection)
console.log(tables)

重试决定,导入 isCommitRateLimited, (中文(简体) ), isCommitServerError,或 isCommitTransient 从 @gscdump/lakehouse/maintenance。 。 。 .

isCommitRateLimited 匹配 HTTP 429. isCommitServerError 匹配瞬态 R2 5xx 响应. isCommitTransient 匹配任一类,并驱动软件包的附加重试循环.

使用数据集登记册定义数据集. 原始 Icebird 表格创建和附加函数运行于 unsafe-raw 用于包适配器和诊断.

立面显示读取限制

icebergManifests 打开 @gscdump/lakehouse/unsafe-raw 接受可选选项 readLimits: ManifestReadLimits. 排除保留现有的读者 呼叫者拥有的显示缓存行为。 没有自动文件解析器或主机 允许这些限制.

import { icebergManifests } from '@gscdump/lakehouse/unsafe-raw'

const manifests = await icebergManifests({
  metadata,
  resolver,
  readLimits: {
    maxObjectBytes: 2 * 1024 * 1024,
    maxTotalObjectBytes: 8 * 1024 * 1024,
    maxManifests: 8,
    maxEntries: 128,
    maxInflatedBlockBytes: 2 * 1024 * 1024,
    maxTotalInflatedBytes: 8 * 1024 * 1024,
    maxValueBytes: 1024 * 1024,
    maxDecodedValues: 100_000,
    maxHeaderBytes: 64 * 1024,
    maxSchemaDepth: 32,
  },
})

这些是实例录入值,而非默认值或全部 JavaScript 堆积 保证。 每个字段都需要,必须是一个正的安全整数; maxSchemaDepth 也必须是最多128个。 读者复制并验证 在它的第一个同步读取之前, 未知字段被拒绝 .

每个对象和累计源字节检查发生在 resolver.reader 报告 byteLength, (中文(简体) ), 在此之前 读者请求 slice(0, byteLength)。 。 。 . 申报的明显长度和返回的切片长度必须相符。 注入的 解析器可以在内部分配或获取 reader 行动本身 在这个边界之外,需要自己的运输限制和不可改变的目标 身份检查 没有头,目录JSON, 网络请求, 或新鲜绑定是 由本备选案文暗示.

(一) 在记录具体化和核对之前,接受清单清单的清点; 输入数累积到所有获取的列表和块。 V1 内置 在读取前接受清单的计数,每个文件在 a 中解码一次 私人每个呼叫缓存。 供应 manifestCache 与 readLimits 拒绝 : 先前已解码的缓存条目没有可核查的预算出处。 默认 保留现有的缓存行为.

为阿芙罗 null 和生的 deflate 块、 解码块字节及其累积 总计被限制。 现有的纯JavaScript充气器检查输出增长 在分配或写入该限制之前。 边界DEFLATE 返回精确大小 支持缓冲器,因此字节视图不会保留多余的充气器容量; 增长和 最终复制缓冲器可以暂时重叠. 页眉框架为字节 在 JSON 解析前; 在递归编译前检查计划深度/ 工作. 在视图或UTF-8解码前检查可变值和固定值,以及 maxDecodedValues 横跨信头/schema节点并解码的解码工作 值访问,包括零字节无值的数组。 严格读取也拒绝 无效的计数, varints, 索引, 切换值和不一致的块大小 .

这些限制不测量 JavaScript 对象/字符串的上方, JSON 剖析器 内部分配、充气器表、调用器保留输出、注入解析器 缓存或全过程内存。 输出仍然是所选择的急切阵列 计数/字节/工作政策。 拒绝是完全拒绝的;没有迫切的 倒退或部分成功。 已分发的解析器读取不能 asyncBuffer 接口已实际取消, 但第一次失败会停止新的 发送并防止延迟回复被解码。 选择兼容性 限制并验证完整的消费者路径,然后才允许它们.

同样的选择 readLimits 可以传递给 resolveIcebergDataFiles, (中文(简体) ), dataset.resolveDataFiles(..., { readLimits }),发动机的 listIcebergDataFiles。这些包头捕捉和验证所有十个值之前 编目读取或懒惰地导入,然后进行一个有界限的明快行走. 每个对象 和总限额仍然是独立的上限;总限额较小 不扩大每个对象的津贴。 无效、 缺失或未知值为 拒绝,即使表格没有当前快照.

在此选入模式中, 解码的表单、 解析的文件和月份缓存既不是 读取或覆盖:旧的缓存条目无法建立对新条目的遵守 政策。 现有的目录配置、快照指针和表格元数据 缓存仍在使用,并有其现有的身份/新鲜度规则。 列表 JSON 而那些元数据缓存 是在Avro分配约束之外。 现有 分区、网站、搜索类型、日期检查和输出命令不变.

这有明显的热读成本。 默认精确距离缓存命中可以避免 所有Avro读取;默认月命中只需列表即可. 边框 调用会读取列表和每个选中的列表( 需要输入) 解析器自己的字节缓存).

一个连接从 connectIcebergCatalog 保留它读取的物体 每个连接字节缓存。 缓存最多能保存16个取取的字节. 如果一个读取它超过16个 MiB, 它会驱逐最近读取的最小对象 先说 它不保留大于16个米B的物体,也不保留一个 读取失败 。 同时读取一个路径共享一个S3请求. 一个成功的 写入或删除路径将驱动该路径。 一个有界限的电话读取了没有标记的 S3 解析器被取代, 因此连接没有保留其显示的字节 电话。 它也不重复使用先前未绑定的调用缓存的字节. 若为 替换 connection.resolver,有限度的呼叫使用 您的解析器,和您的 解决者拥有它的保留。 每个同时发出的呼吁有自己的限度; 选项不强制规定全网或全流程预算。 有一个 拒绝后不会自动回落到缓存或无约束的结果。 校验 在启用主机策略之前保留文件和请求费用; 这样做 不绑定远程 SQL 提供者的内部显示规划器 .

附加重试

提供耐用 commitRetry.appendId 当一个数据集附件属于某项工作或收据时. 任务重试时重用该ID,包括在软件包升级后重试.

没有明确的ID,行附件从被设定,打出的记录内容中获取一个版本的ID. 行顺序和对象密钥顺序不改变ID.

如果只匹配遗留内容 ID, 则附件会丢出 LegacyAppendIdentityUnverifiable。 。 。 . 错误包含 legacyAppendId。 。 。 . 遗留的ID无法证明承诺行是否匹配重试 . 在提供遗留的ID作为明确身份之前,核查承诺行 appendId。 。 。 . 如果行不同,则对新附件使用新的持久ID. 不检查行则不要重试错误遗留的ID .

在升级获得ID的制作人之前,要排出他们现有的写作任务. 不要在同一表格中同时运行旧的和新的衍生的ID作者. 老年作家无法识别新内容ID格式.

批次附件已经需要明确 appendId 并保持这个行为.

明显合并

使用 mergeIcebergManifests(connection, table, options) 从 @gscdump/lakehouse/maintenance 来减少当前元数据只读取附件 v2 表格. 连接提供了精确的目录和命名空间. 操作保存了DATA文件,它们的元数据和序列号,以及历史附件快照和显示. 它按照分区规格对条目进行分组,并写出编码显示最多为4个米B. 它将总输入和相接输出分别限制为8个米B,有一万个活条目. 选项可以降低这些限制.

Merged 报告快照 ID 、 清单 、 文件 . Unchanged 当合并无法减少表数时,可避免写入. Conflict 使同时发生的UUID或主弹弓变化保持不变. 在以后尝试前重新装入当前头部 . Err 报告不支持的格式、删除、无效的库存、超出限度或更改外部权限. 基础设施出错. V2 写入器不支持的非null DATA 元数据字段, 包括加密元数据, 生成 invalid-inventory。 。 。 .

供应 confirmAuthority 重新检查外部权威 就在目录承诺之前. 退回错误地阻止了这种犯罪;回召例外被宣传. 这种回调不创建带有外部数据库的原子交易. 供应 cache 以取消在成功后抓取的命名空间和表格缓存快取指针.

失败或不确定承付保留分阶段元数据. 在成功承诺之后可能会出现不确定的反应,因此删除已分阶段的文件可能会打破表格. 操作从不过期历史快照或删除历史显示. 保留这些物品,同时验证收据或附件的复试仍需要它们.

恢复表格

使用 restoreIcebergTable(connection, table, options) 从 @gscdump/lakehouse/maintenance 用于空目录目标. 在登记表格之前恢复每个引用的元数据、清单和数据对象. 保留他们的S3位置,表UUID,快照ID,以及不可变的字节. 打电话者拥有目标,并通过和解将同时撰写者排除在外.

提供已保存的元数据位置, SHA-256, 表 UUID, 头像标识, 和完整的快照标识目录 . 操作检查目标,保存元数据字节,以及注册前的身份. 元数据可以使用plain JSON或gzip. 字节限制适用于存储和扩展字节. SHA-256总是在解压前验证所储存的对象字节. 它登记在 overwrite: false 并核实返回的身份. 现有表格 target-exists,包括匹配已保存身份的表格. 错误的字节或不匹配的身份生成 backup-invalid 登记前.

供应 confirmAuthority 在访问、登记和确认之前重新检查所有权. 这种回调不会与外部状态产生原子交易. Restored 确认确认的表格身份。 它不核查每个引用的数据对象. 恢复后,通过新读会话运行应用程序的收件,对象散列和查询检查. 供应 cache 以在成功后使其保存的快照指针无效.

Unknown 意味着可能已经登记. 在决定下一个动作之前,保留恢复的对象并检查新的Catalog元数据. 操作不会在不确定的响应后重试,覆盖,或者删除对象. 其他基础设施的故障也在蔓延.

在保留登记对象的同时拆分登记对象,使用 dropIcebergTables(connection, tables, { purge: false })。 。 。 . 默认请求清除 。 使用明确的表格名称进行恢复操作.

许可证

麻省理工学院

版本与发布记录

@gscdump/lakehouse 共发布 139 个版本,首次发布于 2026/07/03;过去 12 个月发布了 139 个版本。最新版本附带 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/lakehouse 的常见问题

@gscdump/lakehouse 是什么?

数据集-不可知性冰山湖地层+R2数据目录制作方数据集登记(ADR-0021).

如何安装 @gscdump/lakehouse?

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

@gscdump/lakehouse 支持 TypeScript 吗?

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

@gscdump/lakehouse 支持 ESM 还是 CommonJS?

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

@gscdump/lakehouse 需要什么版本的 Node.js?

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

@gscdump/lakehouse 可以商用吗?

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

@gscdump/lakehouse 的下载量有多少?

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

@gscdump/lakehouse 还在维护吗?

最新版本 7.15.0 发布于 2026/11/16(今天);至今共发布 139 个版本,其中过去 12 个月发布了 139 个;首次发布于 2026/07/03。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。