使用 OneLake 的 tableread API 来读取 OneLake 中的 Delta Lake 或 Apache Iceberg 表中的行。
要读取表数据,发送一个请求启动读取会话。 API根据需要返回的数据大小返回一个或多个独立的结果流。 你的应用程序可以并行下载这些数据流,这有助于更快地读取大量表数据。 下载这些流后,处理其 Apache Arrow 记录批次以组装成完整结果。
API从一个一致的时间点读取表,因此每个结果流都包含来自同一快照的数据,即使表在读取过程中发生变化。 它还对认证调用者强制执行OneLake授权、行级安全(RLS)和列级安全(CLS)。 这意味着你的应用程序只接收调用者被授权访问的行和列,无需在其自身代码中重现这些安全控制。
Important
OneLake 表格阅读 API 目前处于 公开预览阶段。 在正式发布之前,功能和行为可能会更改。
先决条件
- 完成 共享表API的前置条件和认证步骤。
- 一个可以处理Apache Arrow IPC流而不缓冲完整响应的HTTP客户端。
1. 发送表格行请求
向表的/read路由发送POST请求以启动读取会话。
通过用你想读取的工作区、项目、模式和表的标识符替换占位符来构建请求URL。
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>在请求中包含应用程序所需的读取选项。 使用
columns选项指定要返回哪些列。保存所有成功响应时的不透明流标识符。 一个大结果可能会分散在多个流中。 你必须读取每个流,才能获取所有行。
该响应会基于满足您的请求所需的表版本一致性快照,发起一个读取会话。 该响应的每个流都使用相同的快照。
2. 下载所有结果流
使用响应中的每个流标识符来获取其对应的表读取结果部分。
读取会话在60分钟后结束。 在会话结束前获取所有流。 如果你在只检索到一部分流后就停止,将无法获得完整结果。
对于分配响应中的每个流标识符,发送一个认证请求
GET。GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>使用 Apache Arrow IPC 流读取器打开响应正文。
在记录批次到达时对其进行处理。 流式批量处理可以避免将完整结果加载到内存中。
对每个流标识符重复请求,并根据你应用的处理模型组合结果。
Important
一个 200 OK 响应表示流响应已开始,而非所有数据均已接收。 继续阅读响应正文,处理HTTP传输错误和Arrow解码错误。 如果连接被重置或 HTTP 客户端报告响应不完整,即使你已经收到有效的记录批次,也应将该流视为失败。
每个 /readStream 响应都是独立的Apache Arrow IPC流。 使用适用于您的应用程序语言的 Apache Arrow 库读取每个响应中的记录批次。 有关流格式的更多信息,请参见序列化与进程间通信(IPC)。
响应体包含原始的Apache Arrow IPC流数据,包括解释记录批次所需的模式信息。 不要依赖行顺序,也不要假设流在响应中的位置决定了它在完整结果中的位置。
了解 OneLake 对表格阅读 API 的安全性
该 API 通过使用你的持有者令牌所代表的身份来实施 OneLake 安全性控制:
- 如果您没有查看表格的权限,服务会返回“未找到”回复。
- 如果行级安全(RLS)过滤掉你能查看的所有行,请求会成功但返回空的Arrow响应。
- 如果使用通配符列投影,响应中只包含列级安全(CLS)允许你查看的列。
- 如果你明确请求无法查看的列,服务会返回“找不到”回复。
由于未授权的表和列会返回未找到的响应,不要用未找到的响应来判断资源是否存在。
注意事项和限制
- tableread API 不支持跨区域快捷方式。
- 系统将就
POST /read操作向你收费。 使用/readStream检索数据不会产生单独的表读取计费事件。 有关详细信息,请参阅 表读取 API 用量。