阅读OneLake表数据(预览)

使用 OneLake 的 tableread API 来读取 OneLake 中的 Delta Lake 或 Apache Iceberg 表中的行。

要读取表数据,发送一个请求启动读取会话。 API根据需要返回的数据大小返回一个或多个独立的结果流。 你的应用程序可以并行下载这些数据流,这有助于更快地读取大量表数据。 下载这些流后,处理其 Apache Arrow 记录批次以组装成完整结果。

API从一个一致的时间点读取表,因此每个结果流都包含来自同一快照的数据,即使表在读取过程中发生变化。 它还对认证调用者强制执行OneLake授权、行级安全(RLS)和列级安全(CLS)。 这意味着你的应用程序只接收调用者被授权访问的行和列,无需在其自身代码中重现这些安全控制。

Important

OneLake 表格阅读 API 目前处于 公开预览阶段。 在正式发布之前,功能和行为可能会更改。

先决条件

1. 发送表格行请求

向表的/read路由发送POST请求以启动读取会话。

  1. 通过用你想读取的工作区、项目、模式和表的标识符替换占位符来构建请求URL。

    POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read
    Authorization: Bearer <BearerToken>
    
  2. 在请求中包含应用程序所需的读取选项。 使用 columns 选项指定要返回哪些列。

  3. 保存所有成功响应时的不透明流标识符。 一个大结果可能会分散在多个流中。 你必须读取每个流,才能获取所有行。

该响应会基于满足您的请求所需的表版本一致性快照,发起一个读取会话。 该响应的每个流都使用相同的快照。

2. 下载所有结果流

使用响应中的每个流标识符来获取其对应的表读取结果部分。

读取会话在60分钟后结束。 在会话结束前获取所有流。 如果你在只检索到一部分流后就停止,将无法获得完整结果。

  1. 对于分配响应中的每个流标识符,发送一个认证请求 GET 。

    GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID>
    Authorization: Bearer <BearerToken>
    
  2. 使用 Apache Arrow IPC 流读取器打开响应正文。

  3. 在记录批次到达时对其进行处理。 流式批量处理可以避免将完整结果加载到内存中。

  4. 对每个流标识符重复请求,并根据你应用的处理模型组合结果。

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 用量。