OneLakeのテーブルデータを読む(プレビュー)

OneLakeのDelta LakeやApache Icebergテーブルから行を読み取るには、OneLakeのテーブルリードAPIを使います。

テーブルデータを読み取るには、読み取りセッションを開始するための1つのリクエストを送信します。 APIは、返すべきデータのサイズに基づいて1つ以上の独立した結果ストリームを返します。 アプリケーションはこれらのストリームを並列にダウンロードできるため、大量のテーブルデータをより速く読み取ることができます。 ストリームをダウンロードした後、Apache Arrowレコードバッチを処理して完全な結果を組み立てます。

APIはテーブルを一貫した時点から読み取りますので、読み取り中にテーブルが変更されても、すべての結果ストリームには同じスナップショットからのデータが含まれます。 また、認証済み発信者に対してOneLake認証、行レベルのセキュリティ(RLS)、カラムレベルのセキュリティ(CLS)も強制します。 つまり、アプリケーションは呼び出し元がアクセス権限を持つ行と列のみを受け取り、これらのセキュリティ制御を自社のコードで再現する必要がなくなります。

Important

OneLakeのテーブルリードAPIは現在 パブリックプレビュー中です。 機能と動作は、一般公開前に変更される可能性があります。

前提条件

  • 共有テーブルAPIの 前提条件と認証ステップを完了してください。
  • Apache ArrowのIPCストリームを完全なレスポンスをバッファリングせずに処理できるHTTPクライアント。

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. すべてのストリーム識別子に対してリクエストを繰り返し、アプリケーションの処理モデルに応じて結果を組み合わせます。

各 /readStream 応答は独立したApache Arrow IPCストリームです。 アプリケーション言語のApache Arrowライブラリを使って、各レスポンスからレコードバッチを読み取ってください。 ストリーム形式の詳細については、「 シリアライズおよびプロセス間通信(IPC)」を参照してください。

レスポンス本体には、レコードバッチを解釈するために必要なスキーマ情報を含む生のApache Arrow IPCストリームデータが含まれています。 行の順序に頼ったり、レスポンス内のストリームの位置が全体の結果におけるその位置を決定すると考えないでください。

テーブルリードAPIのOneLakeセキュリティを理解する

APIは、ベアラートークンが表すアイデンティティを用いてOneLakeのセキュリティを強制します:

  • テーブルの閲覧権限がなければ、サービスは「見つけられませんでした」という応答を返します。
  • 行レベルのセキュリティ(RLS)が閲覧可能なすべての行をフィルタリングした場合、リクエストは成功しますが空のArrow応答を返します。
  • ワイルドカードカラム投影を使用する場合、応答にはカラムレベルセキュリティ(CLS)で閲覧可能な列のみが含まれます。
  • 明示的に表示できない列をリクエストすると、サービスは「見つけられません」という返答を返します。

不正なテーブルや列は「見つからない応答」を返すため、リソースの存在を判断するために「見つけられませんでした」応答を使わないでください。

考慮事項と制限事項

  • テーブルリードAPIは地域横断ショートカットをサポートしていません。
  • POST /read 操作に対して課金されます。 /readStreamを使ってデータを取得しても、別のテーブルリード請求イベントは発生しません。 詳細は「 テーブルリードAPIの消費」をご覧ください。
  • 最終更新: