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