ステートメント実行 API: ウェアハウスで SQL を実行する

important

Databricks REST APIsにアクセスするには、認証が必要です。

このチュートリアルでは、Databricks SQL ステートメント実行 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 以降を使用する場合は、Databricks ワークスペースで認証するように構成する必要があります。「Databricks CLI のインストールまたは更新」および「Databricks CLI の認証」を参照してください。
  
  たとえば、Databricks 個人用アクセストークン認証で認証するには、「ワークスペースユーザー用の個人用アクセストークンDatabricks」の手順に従います。
  
  次に、Databricks CLI を使用して個人用アクセストークンの Databricks 構成プロファイルを作成するには、次の操作を行います。

注記

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

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

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

Databricks CLI を使用して、Databricks パーソナルアクセストークン認証を使用する DEFAULT という名前の Databricks 構成プロファイルを作成します。これを行うには、次のコマンドを実行します。

Bash
databricks configure --profile DEFAULT

プロンプト Databricks Host には、Databricks ワークスペースインスタンスの URL を入力します (例: https://dbc-a1b2345c-d6e7.cloud.databricks.com)。
プロンプトの Personal Access Token に、ワークスペースのDatabricks個人用アクセストークンを入力します。

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

このチュートリアルでは、ローカル開発マシンに環境変数 DATABRICKS_SQL_WAREHOUSE_ID があることを前提としています。この環境変数は、Databricks SQL ウェアハウスの ID を表します。この ID は、ウェアハウスの HTTP パス フィールドの /sql/1.0/warehouses/ に続く文字と数字の文字列です。ウェアハウスの HTTP パス 値を取得する方法については、「Databricks コンピュートリソースの接続の詳細を取得する」を参照してください。
Unix、Linux、または macOS でコマンドシェルの代わりに Windows コマンドシェルを使用する場合は、\ を ^ に置き換え、${...} を %...% に置き換えます。
Unix、Linux、または macOS のコマンドシェルではなく Windows コマンドシェルを使用する場合は、 JSON ドキュメント宣言で、開始'と終了を " に置き換え、内側の"を \" に置き換えます。
curl は、REST API の要求と応答を送受信するためのコマンドラインツールです。「curl のインストール」も参照してください。または、このチュートリアルの curl の例を HTTPie などの同様のツールで使用できるように適応させます。

このチュートリアルの curl つの例では、次の点に注意してください。
- --header "Authorization: Bearer ${DATABRICKS_TOKEN}"の代わりに .netrc を使用できますファイル。 .netrcファイルを使用する場合は、--header "Authorization: Bearer ${DATABRICKS_TOKEN}" を --netrcに置き換えます。
- Unix、Linux、または macOS でコマンドシェルの代わりに Windows コマンドシェルを使用する場合は、\ を ^ に置き換え、${...} を %...% に置き換えます。
- Unix、Linux、または macOS のコマンドシェルではなく Windows コマンドシェルを使用する場合は、 JSON ドキュメント宣言で、開始'と終了を " に置き換え、内側の"を \" に置き換えます。
また、このチュートリアルの curl 例では、ローカル開発マシンに次の環境変数があることを前提としています。
- DATABRICKS_HOSTは、Databricks ワークスペースのワークスペースインスタンス名 (例: dbc-a1b2345c-d6e7.cloud.databricks.com) を表します。
- DATABRICKS_TOKENは、Databricks ワークスペースユーザーの Databricks 個人用アクセストークンを表します。
- DATABRICKS_SQL_WAREHOUSE_IDは、Databricks SQL ウェアハウスの ID を表します。この ID は、ウェアハウスの HTTP パス フィールドの /sql/1.0/warehouses/ に続く文字と数字の文字列です。ウェアハウスの HTTP パス 値を取得する方法については、「Databricks コンピュートリソースの接続の詳細を取得する」を参照してください。

注記

自動化されたツール、システム、スクリプト、アプリで認証する際のセキュリティのベストプラクティスとして、Databricks では OAuth トークンを使用することをお勧めします。

personal access token authentication を使用する場合、 Databricks では、ワークスペースユーザーではなく、サービスプリンシパルに属する personal access token を使用することをお勧めします。サービスプリンシパルのトークンを作成するには、「サービスプリンシパルのトークンの管理」を参照してください。

Databricks個人用アクセストークンを作成するには、ワークスペースユーザー向けの個人用アクセストークンDatabricks の手順に沿って操作します。

警告

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

このチュートリアルでは、JSON 応答ペイロードをクエリするためのコマンドラインプロセッサである jq も存在し、Databricks SQL ステートメント実行 API に対して行う各呼び出しの後に Databricks SQL ステートメント実行 API から返されることを前提としています。「jq のダウンロード」を参照してください。
SQL 文を実行できるテーブルが少なくとも 1 つ必要です。このチュートリアルは、samplesカタログ内のtpchスキーマ (データベースとも呼ばれる) のlineitemテーブルに基づいています。ワークスペースからこのカタログ、スキーマ、またはテーブルにアクセスできない場合は、このチュートリアル全体でそれらを独自のものに置き換えてください。

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

次のコマンドを実行して、次の操作を行います。

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

Databricks CLI
curl

Bash
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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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 ステートメント実行 API で直接サポートされていません。
デフォルトでは、10秒後、 SQL ステートメントがまだウェアハウスを通じて実行を完了していない場合、 Databricks SQL ステートメント実行 API ステートメントの結果ではなく、 SQL ステートメントIDとその現在のステータスのみを返します。この動作を変更するには、リクエストに "wait_timeout" を追加し、 "<x>s"に設定します。ここで、 <x> は 5 秒から 50 秒 (例: 1 "50s"2 秒) です。 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 に設定されます。

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

JSON
{
  "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"
  }
}

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

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

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

JSON
{
  "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 を使用して、その文の現在の実行ステータスを取得し、実行が成功した場合はその文の結果を取得できます。ステートメントのAPI IDDatabricks SQLを忘れた場合は、コンソールのクエリ履歴セクションから、またはクエリー履歴を呼び出すことで取得できます。たとえば、このコマンドをポーリングし続け、実行が成功したかどうかを毎回チェックできます。

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

Databricks CLI
curl

Bash
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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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
curl

Bash
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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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 処理を使用すると、有効期間の短い署名付き URL が生成され、これを使用して Amazon S3 から直接結果をダウンロードできます。この署名付き URL には有効期間の短いアクセス資格情報が埋め込まれているため、URL を保護する必要があります。

事前署名付き URL は、一時アクセス資格情報が埋め込まれた状態で既に生成されているため、ダウンロード要求に Authorization ヘッダーを設定しないでください。

EXTERNAL_LINKSの廃棄は、サポートケースを作成することで、要求に応じて無効にすることができます。サポートを参照してください。

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

注記

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

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

次のコマンドは、 EXTERNAL_LINKS と Apache Arrow 形式の使用方法を示しています。ステップ 1 で示した同様のクエリの代わりに、次のパターンを使用します。

Databricks CLI
curl

Bash
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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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

応答は次のとおりです。

JSON
{
  "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"
  }
}

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

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

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

Databricks CLI
curl

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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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 を実行すると）、次の例のように、応答には複数のチャンクが含まれます。簡潔にするために、ここでは "...": "..." 省略された結果を示していることに注意してください。

JSON
{
  "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 コマンドを実行します。このコマンドには Databricks トークンを含めないでください。

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

ストリームコンテンツの結果の特定のチャンクをダウンロードするには、次のいずれかを使用できます。

次のチャンクの応答ペイロードからの next_chunk_index 値 (次のチャンクがある場合)。
使用可能な任意のチャンクのレスポンスペイロードのマニフェストにあるチャンクインデックスの1つです（複数のチャンクがある場合）。

たとえば、前の応答からchunk_index``10のチャンクを取得するには、次のコマンドを実行します。

Databricks CLI
curl

Bash
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'

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

Bash
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'

注記

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

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

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

ステップ 4: SQL 文の実行をキャンセルする

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

Databricks CLI
curl

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

Replace <profile-name> with the name of your Databricks configuration profile for authentication.

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

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

Databricks SQL ステートメント実行 API は、エンドツーエンドのトランスポート層セキュリティ (TLS) 暗号化と、署名付き URL などの有効期間の短い資格情報を使用して、データ転送のセキュリティを強化します。

このセキュリティモデルには、いくつかのレイヤーがあります。トランスポート層では、TLS 1.2 以上を使用してのみ Databricks SQL ステートメント実行 API を呼び出すことができます。また、Databricks SQL ステートメント実行 API の呼び出し元は、Databricks SQL を使用する権利を持つユーザーにマップされる有効な Databricks 個人用アクセストークンを使用して認証される必要があります。このユーザーは、使用されている特定のSQLウェアハウスに対する CAN USEアクセス権を持っている必要があり、 IPアクセスリストを使用してアクセスを制限できます。これは、Databricks SQL ステートメント実行 API に対するすべての要求に適用されます。さらに、ステートメントを実行するには、認証されたユーザーが、各ステートメントで使用されるデータ・オブジェクト (テーブル、ビュー、関数など) に対するパーミッションを持っている必要があります。これは、Unity Catalog の既存のアクセス制御メカニズムまたはテーブル ACL を使用して適用されます。 (詳細については、Unity Catalogを使用したデータガバナンスを参照してください。これは、ステートメントを実行するユーザーのみがステートメントの結果に対してフェッチ要求を行うことができることも意味します。

Databricks では、Databricks SQL ステートメント実行 API と EXTERNAL_LINKS の性質を使用して大規模なデータセットを取得する場合は常に、次のセキュリティのベストプラクティスをお勧めします。

Amazon S3 リクエストの Databricks 認証ヘッダーを削除する
署名済みURLを保護してください
ストレージアカウントでネットワーク制限を構成する
ストレージアカウントでのログ記録を構成する

EXTERNAL_LINKSの廃棄は、サポートケースを作成することで、要求に応じて無効にすることができます。サポートを参照してください。

Amazon S3 リクエストの Databricks 認証ヘッダーを削除する

curl を使用する Databricks SQL ステートメント実行 API へのすべての呼び出しには、Databricks アクセス資格情報を含む Authorization ヘッダーを含める必要があります。Amazon S3 からデータをダウンロードするときは、この Authorization ヘッダーを含めないでください。このヘッダーは必須ではなく、意図せずに Databricks のアクセス資格情報を公開する可能性があります。

署名付き URL の保護

EXTERNAL_LINKS 対話結果を使用するたびに、有効期間の短い署名付き URL が生成され、呼び出し元はこれを使用して TLS を使用して Amazon S3 から直接結果をダウンロードできます。この署名付きURLには有効期間の短い認証情報が埋め込まれているため、URLを保護する必要があります。

ストレージアカウントでネットワーク制限を構成する

EXTERNAL_LINKS 処理を使用するたびに、クライアントは署名付き URL を取得して、クエリ結果を直接 Amazon S3 からダウンロードします。

Databricks では、S3 バケットポリシーを使用して、 S3 バケットへのアクセスを信頼できる IP アドレスと VPC に制限することをお勧めします。ワークスペースのルートバケットストレージ設定Databricksが正しいことを確認し、顧客管理VPC に関する推奨事項を確認します。

ストレージアカウントでのログ記録を構成する

基盤となるストレージアカウントにネットワークレベルの制限を適用するだけでなく、 S3 サーバーアクセスログや AWS CloudTrail データイベント、およびそれらに関する適切なモニタリングとアラートを設定することで、誰かがこれらの制限を回避しようとするかどうかをモニタリングできます。

始める前に​

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

ステップ 2: ステートメントの現在の実行ステータスとデータ結果を JSON として取得する​

ステップ3：外部リンクを使用して大量の結果を取得する​

ステップ 4: SQL 文の実行をキャンセルする​

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

Amazon S3 リクエストの Databricks 認証ヘッダーを削除する​

署名付き URL の保護​

ストレージ アカウントでネットワーク制限を構成する​

ストレージ アカウントでのログ記録を構成する​

始める前に

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

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

ステップ3：外部リンクを使用して大量の結果を取得する

ステップ 4: SQL 文の実行をキャンセルする

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

Amazon S3 リクエストの Databricks 認証ヘッダーを削除する

署名付き URL の保護

ストレージアカウントでネットワーク制限を構成する

ストレージアカウントでのログ記録を構成する