# @gscdump/lakehouse 中文文档

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

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

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

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

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

- 包体积（解压后）：841 kB，284 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：0 个
- 首次发布：2026-07-03T07:11:12.611Z
- 最新版本发布：2026-11-16T15:38:18.470Z
- 近 30 天下载量：10232（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：139（近 12 个月 139 个）

## 中文简介

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

## 安装

```sh
npm install @gscdump/lakehouse
```

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

## README

# @gscdump/ 莱克豪斯

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

## 安装

```bash
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`: 包适配器的明确逃生舱口 和原始元数据诊断。 应用程序维护属于马厩 维护子路径.

```ts
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`. 排除保留现有的读者 呼叫者拥有的显示缓存行为。 没有自动文件解析器或主机 允许这些限制.

```ts
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 })`。 。 。 . 默认请求清除 。 使用明确的表格名称进行恢复操作.

## 许可证

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

## 常见问题

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

