Statement Execution API: ウェアハウスで SQL を実行する

重要

Databricks REST API にアクセスするには、認証する必要があります。

このチュートリアルでは、Databricks SQL Statement Execution API 2.0 を使用して Databricks SQL のウェアハウスから SQL ステートメントを実行する方法について説明します。

Databricks SQL ステートメント実行 API 2.0 リファレンスを表示するには、「ステートメントの実行」をご覧ください。

開始する前に

このチュートリアルを開始する前に、次のものが用意されていることを確認します。

• Databricks CLI バージョン 0.205 以上か curl。これらの説明を次に示します。

  • Databricks CLI は、Databricks REST API の要求と応答を送受信するためのコマンドライン ツールです。 Databricks CLI バージョン 0.205 以降を使用する場合は、Azure Databricks ワークスペースでの認証のためにこれを構成する必要があります。 「Databricks CLI のインストールまたは更新」と「Databricks CLI の認証」をご覧ください。

    たとえば、Databricks 個人用アクセス トークン認証を使用して認証するには、ワークスペース ユーザー Azure Databricks 個人用アクセス トークンの手順に従います。

    次に、Databricks CLI を使用して個人用アクセス トークンの Azure Databricks 構成プロファイルを作成するには、次の操作を行います:

    Note

    次の手順では、Databricks CLI を使って、DEFAULT という名前で Azure Databricks 構成プロファイルを作成します。 DEFAULT 構成プロファイルが既にある場合、この手順により既存の DEFAULT 構成プロファイルは上書きされます。

    DEFAULT 構成プロファイルが既にあるか確認するには、また、それが存在する場合にこのプロファイルの設定を表示するには、Databricks CLI を使用してコマンド databricks auth env --profile DEFAULT を実行してください。

    DEFAULT 以外の名前で構成プロファイルを作成するには、次の databricks configure コマンドの --profile DEFAULT の DEFAULT の部分を構成プロファイルの別の名前に置き換えます。

    1. Databricks CLI を使って、Azure Databricks 個人用アクセス トークン認証を使う DEFAULT という名前の Azure Databricks 構成プロファイルを作成します。 そのためには、次のコマンドを実行します。

       databricks configure --profile DEFAULT
       

    2. プロンプト [Databricks Host] には、Azure Databricks のワークスペースごとの URL (例: https://adb-1234567890123456.7.azuredatabricks.net) を入力します。

    3. プロンプト [Personal Access Token] には、お使いのワークスペースの Azure Databricks 個人用アクセス トークンを入力します。

    このチュートリアルの Databricks CLI の例では、次の点にご注意ください。

    • このチュートリアルでは、ローカル開発用マシンに DATABRICKS_SQL_WAREHOUSE_ID という環境変数があることが前提となります。 この環境変数は、Databricks SQL ウェアハウスの ID を表します。 この ID は、ウェアハウスの [HTTP パス] フィールド内の /sql/1.0/warehouses/ が後に続く文字と数字からなる文字列です。 ウェアハウスの HTTP パス値を取得する方法については、「Azure Databricks コンピューティング リソースの接続の詳細を取得する」を参照してください。
    • Unix、Linux、または macOS 用のコマンド シェルの代わりに Windows コマンド シェルを使用する場合は、\ を ^ に置き換え、${...} を %...% に置き換えます。
    • JSON ドキュメントの宣言で UNIX、Linux、または macOS 用のコマンド シェルの代わりに Windows コマンド シェルを使用する場合は、開始と終了の ' を " に置き換え、内側の " を \" に置き換えます。

  • curl は、REST API の要求と応答を送受信するためのコマンドライン ツールです。 「curl をインストールする」も参照してください。 または、HTTPie などの同様のツールで使用するために、このチュートリアルの curl の例を改変することもできます。

    このチュートリアルの curl の例では、次の点にご注意ください。

    • --header "Authorization: Bearer ${DATABRICKS_TOKEN}" の代わりに、.netrc ファイルを使用できます。 .netrc ファイルを使用する場合は、--header "Authorization: Bearer ${DATABRICKS_TOKEN}" を --netrc に置き換えます。
    • Unix、Linux、または macOS 用のコマンド シェルの代わりに Windows コマンド シェルを使用する場合は、\ を ^ に置き換え、${...} を %...% に置き換えます。
    • JSON ドキュメントの宣言で UNIX、Linux、または macOS 用のコマンド シェルの代わりに Windows コマンド シェルを使用する場合は、開始と終了の ' を " に置き換え、内側の " を \" に置き換えます。

    また、このチュートリアルの curl の例では、ローカル開発用マシンに次の環境変数があることが前提となります。

    • DATABRICKS_HOST: Azure Databricks ワークスペースのワークスペース インスタンス名を表します (例: adb-1234567890123456.7.azuredatabricks.net)。
    • DATABRICKS_TOKEN: Azure Databricks ワークスペース ユーザーの Azure Databricks 個人用アクセス トークンを表します。
    • DATABRICKS_SQL_WAREHOUSE_ID: Databricks SQL ウェアハウスの ID を表します。 この ID は、ウェアハウスの [HTTP パス] フィールド内の /sql/1.0/warehouses/ が後に続く文字と数字からなる文字列です。 ウェアハウスの HTTP パス値を取得する方法については、「Azure Databricks コンピューティング リソースの接続の詳細を取得する」を参照してください。

    Note

    セキュリティのベスト プラクティスとして、自動化ツール、システム、スクリプト、アプリを使用して認証する場合、Databricks では、ワークスペース ユーザーではなくサービス プリンシパルに属する個人用アクセス トークンを使用することを推奨しています。 サービス プリンシパルのトークンを作成するには、「サービス プリンシパルのトークンを管理する」をご覧ください。

    Azure Databricks の個人用アクセス トークンを作成するには、ワークスペース ユーザー用の Azure Databricks 個人用アクセス トークンのステープに従います。

    警告

    Databricks では、スクリプトに情報をハードコーディングしないことを強くお勧めします。この機密情報がバージョン コントロール システムを通じてプレーンテキストで公開されるおそれがあるためです。 Databricks では代わりに、開発用マシンに設定した環境変数などの手法を使用することをお勧めしています。 このようなハードコーディングされた情報をスクリプトから削除すると、それらのスクリプトの移植性も高くなります。

• このチュートリアルでは、jq があることも前提となります。これは、JSON 応答ペイロード (Databricks SQL Statement Execution API を呼び出すたびに返される) に対してクエリを実行するためのコマンドライン プロセッサです。 「jq をダウンロードする」をご覧ください。

• SQL ステートメントの実行対象にできるテーブルが 1 つ以上存在する必要があります。 このチュートリアルは、samples カタログ内の tpch スキーマ (データベースとも呼ばれます) の lineitem テーブルに基づいています。 ワークスペースからこのカタログ、スキーマ、テーブルにアクセスできない場合は、このチュートリアル全体を通してそれらを独自のものに置き換えてください。

手順 1: SQL ステートメントを実行してデータ結果を JSON として保存する

次のコマンドを実行します。これにより、以下が行われます。

1. 指定した SQL ウェアハウスと、curl を使用している場合は指定したトークンを使用して、samples カタログ内の tcph スキーマにある lineitem テーブルの最初の 2 行から 3 つの列についてクエリを実行します。
2. 応答ペイロードを JSON 形式で、現在の作業ディレクトリ内の sql-execution-response.json という名前のファイルに保存します。
3. sql-execution-response.json ファイルの内容を出力します。
4. SQL_STATEMENT_ID という名前のローカル環境変数を設定してください。 この変数には、対応する SQL ステートメントの ID が含まれています。 この SQL ステートメント ID は、後で必要に応じてそのステートメントに関する情報を取得するために使用できます。これについては、手順 2 で説明しています。 Databricks SQL コンソールの [クエリの履歴] セクションから、または Query History API を呼び出して、この SQL ステートメントを表示し、そのステートメント ID を取得することもできます。
5. JSON データの次のチャンクを取得するために、API URL フラグメントを含む NEXT_CHUNK_EXTERNAL_LINK という名前の追加のローカル環境変数を設定します。 応答データが大きすぎる場合、Databricks SQL Statement Execution API では応答がチャンクで提供されます。 この API URL フラグメントを使用して、データの次のチャンクを取得できます。これについては、手順 2 で説明しています。 次のチャンクがない場合、この環境変数は null に設定されます。
6. SQL_STATEMENT_ID および NEXT_CHUNK_INTERNAL_LINK 環境変数の値を出力します。

Databricks CLI

databricks api post /api/2.0/sql/statements \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "2", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

上記の要求において:

• パラメーター化されたクエリは、各クエリ パラメーターの名前の前にコロンがあり (たとえば、:extended_price)、parameters 配列内に一致する name および value オブジェクトがあります。 オプションの type を指定することもでき、指定されていない場合の既定値は STRING になります。

  警告

  Databricks では、SQL ステートメントのベスト プラクティスとしてパラメーターを使用することを強くお勧めします。

  SQL を動的に生成するアプリケーションで Databricks SQL ステートメント実行 API を使用すると、SQL インジェクション攻撃が発生する場合があります。 たとえば、ユーザー インターフェイスでユーザーが選択した内容に基づいて SQL コードを生成し、適切な対策を講じなかった場合、攻撃者は悪意のある SQL コードを挿入して初期クエリのロジックを変更し、機密データの読み取り、変更、または削除を行うおそれがあります。

  パラメーター化されたクエリは、SQL コードの残りの部分とは別に入力引数を処理し、これらの引数をリテラル値として解釈することで、SQL インジェクション攻撃からの保護に役立ちます。 パラメーターは、コードの再利用にも役立ちます。

• 既定では、返されるデータはすべて JSON 配列形式であり、SQL ステートメントのデータ結果すべての既定の場所は応答ペイロード内です。 この動作を明示するには、要求ペイロードに "format":"JSON_ARRAY","disposition":"INLINE" を追加します。 応答ペイロードで 25 MiB を超えるデータ結果を返そうとすると、失敗状態が返され、SQL ステートメントが取り消されます。 データ結果が 25 MiB を超える場合は、応答ペイロードにデータ結果を返す代わりに、外部リンクを使用できます。これについては、手順 3 で説明します。

• このコマンドでは、応答ペイロードの内容がローカル ファイルに格納されます。 ローカル データ ストレージは、Databricks SQL Statement Execution API で直接サポートされていません。

• 既定では、10 秒後に、SQL ステートメントがウェアハウス経由での実行をまだ完了していない場合、Databricks SQL Statement Execution API からステートメントの結果ではなく、SQL ステートメント ID とその現在の状態のみが返されます。 この動作を変更するには、要求に "wait_timeout" を追加してこれを "<x>s" に設定してください。ここで、<x> は 5 から 50 秒の間で指定できます (例: "50s")。 SQL ステートメント ID とその現在の状態をすぐに返すには、wait_timeout を 0s に設定 します。

• 既定では、タイムアウト期間に達した場合、SQL ステートメントは引き続き実行されます。 代わりにタイムアウト期間に達した場合に SQL ステートメントを取り消すには、要求ペイロードに "on_wait_timeout":"CANCEL" を追加してください。

• 返されるバイト数を制限するには、要求に "byte_limit" を追加し、1000などのバイト数に設定してください。

• 返される行数を制限するには、statement に LIMIT句を追加する代わりに、要求に "row_limit" を追加し、これを "statement":"SELECT * FROM lineitem","row_limit":2 などの行数に設定してください。

• 結果が指定した byte_limit または row_limitより大きい場合、truncated フィールドは応答ペイロードで true に設定されます。

待機タイムアウトが終了する前にステートメントの結果が使用できる場合、応答は次のようになります。

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 2,
        "row_offset": 0
      }
    ],
    "format": "JSON_ARRAY",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_chunk_count": 1,
    "total_row_count": 2,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      [
        "2",
        "71433.16",
        "1997-01-28"
      ],
      [
        "7",
        "86152.02",
        "1996-01-15"
      ]
    ],
    "row_count": 2,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

ステートメントの結果が使用できるようになる前に待機タイムアウトが終了した場合、応答は代わりに次のようになります。

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

ステートメントの結果データが大きすぎる場合 (この場合、SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem LIMIT 300000 を実行するなど)、結果データはチャンクされ、代わりに次のようになります。 ここでは、簡潔にするために、"...": "..." は省略された結果を示していることに注意してください。

{
  "manifest": {
    "chunks": [
      {
        "chunk_index": 0,
        "row_count": 188416,
        "row_offset": 0
      },
      {
        "chunk_index": 1,
        "row_count": 111584,
        "row_offset": 188416
      }
    ],
    "format":"JSON_ARRAY",
    "schema": {
      "column_count":3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_chunk_count": 2,
    "total_row_count": 300000,
    "truncated": false
  },
  "result": {
    "chunk_index": 0,
    "data_array": [
      [
        "2",
        "71433.16",
        "1997-01-28"
      ],
      [
        "..."
      ]
    ],
    "next_chunk_index": 1,
    "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=188416",
    "row_count": 188416,
    "row_offset": 0
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

手順 2: ステートメントの現在の実行状態とデータ結果を JSON として取得する

SQL ステートメントの ID を使用して、そのステートメントの現在の実行状態と、そのステートメントの結果 (実行が成功した場合) を取得できます。 ステートメントの ID を忘れた場合は、Databricks SQL コンソールの [クエリの履歴] セクションから、または Query History API を呼び出してそれを取得できます。 たとえば、このコマンドをポーリングし続けて、実行が成功したかどうかを毎回確認できます。

SQL ステートメントの現在の実行状態と、実行が成功した場合は、そのステートメントの結果、および JSON データの次のチャンク (存在する場合) を取得するための API URL フラグメントを取得するには、次のコマンドを実行します。 このコマンドは、ローカル開発用マシンに SQL_STATEMENT_ID という名前の環境変数が存在し、それが前の手順の SQL ステートメントの ID の値に設定されていることを前提としています。 もちろん、次のコマンド内の ${SQL_STATEMENT_ID} を SQL ステートメントのハードコーディングされた ID に置き換えることができます。

Databricks CLI

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .result.next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

NEXT_CHUNK_INTERNAL_LINK が null 以外の値に設定されている場合は、たとえば次のコマンドでそれを使用してデータの次のチャンクを取得し、以降も同様にできます。

Databricks CLI

databricks api get /${NEXT_CHUNK_INTERNAL_LINK} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request GET \
https://${DATABRICKS_HOST}${NEXT_CHUNK_INTERNAL_LINK} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export NEXT_CHUNK_INTERNAL_LINK=$(jq -r .next_chunk_internal_link 'sql-execution-response.json') \
&& echo NEXT_CHUNK_INTERNAL_LINK=$NEXT_CHUNK_INTERNAL_LINK

上記のコマンドを繰り返し実行して次のチャンクを取得し続けることができます。 最後のチャンクがフェッチされるとすぐに SQL ステートメントは閉じられることに注意してください。 このクローズの後、そのステートメントの ID を使用して現在の状態を取得することも、それ以上のチャンクをフェッチすることもできません。

手順 3: 外部リンクを使用して大きな結果をフェッチする

このセクションでは、EXTERNAL_LINKS 処理を使用して大きなデータ セットを取得するオプションの構成を示します。 SQL ステートメント結果データ用の既定の場所 (処理) は、応答ペイロード内です。ただし、これらの結果は 25 MiB に制限されています。 disposition を EXTERNAL_LINKS に設定すると、標準の HTTP を使用して結果データのチャンクをフェッチするために使用できる URL が応答に含まれます。 この URL は、ワークスペースの内部 DBFS を示しています。結果のチャンクは、ここに一時的に格納されます。

警告

Databricks では、EXTERNAL_LINKS 処理によって返される URL とトークンを保護することを強くお勧めします。

EXTERNAL_LINKS 処理を使用すると、Shared Access Signature (SAS) URL が生成されます。この URL を使用すると、Azure Storage から直接結果をダウンロードできます。 この SAS URL 内には有効期間の短い SAS トークンが埋め込まれるため、SAS URL と SAS トークンの両方を保護する必要があります。

SAS URL は埋め込まれた一時 SAS トークンを使用して既に生成されているため、ダウンロード要求では Authorization ヘッダーを設定しないでください。

サポート ケースを作成することで、要求に応じて EXTERNAL_LINKS 処理を無効にすることができます。

「セキュリティのベスト プラクティス」も参照してください。

Note

応答ペイロードの出力形式と動作は、特定の SQL ステートメント ID に対して一度設定されると、変更できません。

このモードで API を使用すると、JSON 形式 (JSON)、CSV 形式 (CSV)、または HTTP で個別にクエリを実行する必要がある Apache Arrow 形式 (ARROW_STREAM) で結果データを保存できます。 また、このモードを使用する場合、応答ペイロード内で結果データをインライン化することはできません。

次のコマンドは、EXTERNAL_LINKS と Apache Arrow 形式の使用を示しています。 手順 1 で示した同様のクエリの代わりに、このパターンを使用してください。

Databricks CLI

databricks api post /api/2.0/sql/statements/ \
--profile <profile-name> \
--json '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/ \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--header "Content-Type: application/json" \
--data '{
  "warehouse_id": "'"$DATABRICKS_SQL_WAREHOUSE_ID"'",
  "catalog": "samples",
  "schema": "tpch",
  "format": "ARROW_STREAM",
  "disposition": "EXTERNAL_LINKS",
  "statement": "SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem WHERE l_extendedprice > :extended_price AND l_shipdate > :ship_date LIMIT :row_limit",
  "parameters": [
    { "name": "extended_price", "value": "60000", "type": "DECIMAL(18,2)" },
    { "name": "ship_date", "value": "1995-01-01", "type": "DATE" },
    { "name": "row_limit", "value": "100000", "type": "INT" }
  ]
}' \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json' \
&& export SQL_STATEMENT_ID=$(jq -r .statement_id 'sql-execution-response.json') \
&& echo SQL_STATEMENT_ID=$SQL_STATEMENT_ID

応答は次のとおりです。

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "row_count": 100000,
        "row_offset": 0
      }
    ],
    "format": "ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "name": "l_orderkey",
          "position": 0,
          "type_name": "LONG",
          "type_text": "BIGINT"
        },
        {
          "name": "l_extendedprice",
          "position": 1,
          "type_name": "DECIMAL",
          "type_precision": 18,
          "type_scale": 2,
          "type_text": "DECIMAL(18,2)"
        },
        {
          "name": "l_shipdate",
          "position": 2,
          "type_name": "DATE",
          "type_text": "DATE"
        }
      ]
    },
    "total_byte_count": 2843848,
    "total_chunk_count": 1,
    "total_row_count": 100000,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 2843848,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "row_count": 100000,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

要求がタイムアウトした場合、応答は代わりに次のようになります。

{
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "PENDING"
  }
}

そのステートメントの現在の実行状態と、そのステートメントの結果 (実行が成功した場合) を取得するには、次のコマンドを実行します。

Databricks CLI

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID} \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

応答が十分な大きさの場合 (この場合、行の制限なしで SELECT l_orderkey, l_extendedprice, l_shipdate FROM lineitem を実行するなど)、以下の例のように、応答には複数のチャンクが含まれます。 ここでは、簡潔にするために、"...": "..." は省略された結果を示していることに注意してください。

{
  "manifest": {
    "chunks": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "row_count": 403354,
        "row_offset": 0
      },
      {
        "byte_count": 6282464,
        "chunk_index": 1,
        "row_count": 220939,
        "row_offset": 403354
      },
      {
        "...": "..."
      },
      {
        "byte_count": 6322880,
        "chunk_index": 10,
        "row_count": 222355,
        "row_offset": 3113156
      }
    ],
    "format":"ARROW_STREAM",
    "schema": {
      "column_count": 3,
      "columns": [
        {
          "...": "..."
        }
      ]
    },
    "total_byte_count": 94845304,
    "total_chunk_count": 11,
    "total_row_count": 3335511,
    "truncated": false
  },
  "result": {
    "external_links": [
      {
        "byte_count": 11469280,
        "chunk_index": 0,
        "expiration": "<url-expiration-timestamp>",
        "external_link": "<url-to-data-stored-externally>",
        "next_chunk_index": 1,
        "next_chunk_internal_link": "/api/2.0/sql/statements/00000000-0000-0000-0000-000000000000/result/chunks/1?row_offset=403354",
        "row_count": 403354,
        "row_offset": 0
      }
    ]
  },
  "statement_id": "00000000-0000-0000-0000-000000000000",
  "status": {
    "state": "SUCCEEDED"
  }
}

保存されたコンテンツの結果をダウンロードするには、external_link オブジェクトの URL を使用し、ファイルをダウンロードする場所を指定して、次の curl コマンドを実行します。 このコマンドには、Azure Databricks トークンを含めないでください。

curl "<url-to-result-stored-externally>" \
--output "<path/to/download/the/file/locally>"

ストリーミングされたコンテンツの結果の特定のチャンクをダウンロードするには、次のいずれかを使用してください。

• 次のチャンクの応答ペイロードからの next_chunk_index 値 (次のチャンクがある場合)。
• 複数のチャンクがある場合は、使用可能なチャンクの応答ペイロードのマニフェストのチャンク インデックスのうちの 1 つ。

たとえば、前の応答の chunk_index が 10 であるチャンクを取得するには、次のコマンドを実行してください。

Databricks CLI

databricks api get /api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--profile <profile-name> \
> 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request GET \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/result/chunks/10 \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--output 'sql-execution-response.json' \
&& jq . 'sql-execution-response.json'

Note

上記のコマンドを実行すると、新しい SAS URL が返されます。

保存されているチャンクをダウンロードするには、external_link オブジェクト内の URL を使用します。

Apache Arrow 形式の詳細については、以下を参照してください。

• IPC ストリーミング形式
• ストリーミング形式の書き込みと読み取り
• ストリームの使用

手順 4: SQL ステートメントの実行を取り消す

まだ成功していない SQL ステートメントを取り消す必要がある場合は、次のコマンドを実行します。

Databricks CLI

databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'

<profile-name> を、認証用の Azure Databricks 構成プロファイルの名前に置き換えてください。

curl

curl --request POST \
https://${DATABRICKS_HOST}/api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--header "Authorization: Bearer ${DATABRICKS_TOKEN}"

セキュリティのベスト プラクティス

Databricks SQL Statement Execution API では、エンド ツー エンドのトランスポート層セキュリティ (TLS) 暗号化と有効期間の短い資格情報 (SAS トークンなど) を使用することで、データ転送のセキュリティが強化されます。

このセキュリティ モデルには、複数のレイヤーがあります。 トランスポート層では、TLS 1.2 以降を使用して Databricks SQL Statement Execution API を呼び出すことのみが可能です。 また、Databricks SQL ステートメント実行 API の呼び出し元は、Databricks SQL を使用する権限を持つユーザーにマップされる有効な Azure Databricks 個人アクセス トークン、OAuth アクセス トークン、または Microsoft Entra ID (旧 Azure Active Directory) トークンを使用して認証される必要があります。 このユーザーは、使用する特定の SQL ウェアハウスに対して CAN USE アクセス権を持っている必要があります。アクセス権は、IP アクセス リストを使用して制限できます。 これは、Databricks SQL Statement Execution API へのすべての要求に適用されます。 さらに、ステートメントを実行するには、認証されたユーザーが各ステートメントで使用されるデータ オブジェクト (テーブル、ビュー、関数など) に対するアクセス許可を持っている必要があります。 これは、Unity Catalog の既存のアクセス制御メカニズムまたはテーブル ACL を使用すると適用されます (「Unity Catalog を使用したデータ ガバナンス」を参照)。つまり、ステートメントを実行するユーザーのみがステートメントの結果に対するフェッチ要求を行うことができます。

Databricks では、Databricks SQL Statement Execution API を EXTERNAL_LINKS 処理と共に使用して大きなデータ セットを取得する場合は、常に次のセキュリティのベスト プラクティスに従うことをお勧めします。

• Azure ストレージ要求の Databricks Authorization ヘッダーを削除する
• SAS URL と SAS トークンを保護する

サポート ケースを作成することで、要求に応じて EXTERNAL_LINKS 処理を無効にすることができます。 この要求を行うには、Azure Databricks アカウント チームにお問い合わせください。

Azure ストレージ要求の Databricks Authorization ヘッダーを削除する

curl を使用する Databricks SQL Statement Execution API の呼び出しにはすべて、Azure Databricks アクセス資格情報を含む Authorization ヘッダーが含まれている必要があります。 Azure Storage からデータをダウンロードする場合は、常に、この Authorization ヘッダーを含めないでください。 このヘッダーは必須ではなく、Azure Databricks のアクセス資格情報が誤って公開される可能性があります。

SAS URL と SAS トークンを保護する

EXTERNAL_LINKS 処理を使用するたびに、有効期間の短い SAS URL が生成されます。この SAS URL は、呼び出し元が TLS を使用して Azure Storage から直接結果をダウンロードするために使用できます。 この SAS URL 内には有効期間の短い SAS トークンが埋め込まれるため、SAS URL と SAS トークンの両方を保護する必要があります。