다음을 통해 공유

문 실행 API: 웨어하우스에서 SQL 실행

  • 아티클

Important

Databricks REST API에 액세스하려면 인증해야 합니다.

이 자습서에서는 Databricks SQL 문 실행 API 2.0을 사용하여 Databricks SQL 웨어하우스에서 SQL 문을 실행하는 방법을 보여 줍니다.

Databricks SQL 문 실행 API 2.0 참조를 보려면 문 실행을 참조하세요.

시작하기 전에

이 자습서를 시작하기 전에 먼저 다음 사항을 확인해야 합니다.

  • 다음과 같이 Databricks CLI 버전 0.205 이상 또는 curl.

    • Databricks CLI는 REST API 요청 및 응답을 보내고 받기 위한 명령줄 도구입니다. Databricks CLI 버전 0.205 이상을 사용하는 경우 Azure Databricks 작업 영역에서 인증하도록 구성해야 합니다. Databricks CLI 설치 및 업데이트 및 Databricks CLI 인증을 참조하세요.

      예를 들어 Databricks 개인용 액세스 토큰 인증으로 인증하려면 작업 영역 사용자를 위한 Azure Databricks 개인용 액세스 토큰의 단계를 따릅니다.

      그런 다음 Databricks CLI를 사용하여 개인용 액세스 토큰에 대한 Azure Databricks 구성 프로필을 만들려면 다음을 수행합니다.

      참고 항목

      다음 절차에서는 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 호스트 프롬프트의 경우 Azure Databricks 작업 영역별 URL(예: https://adb-1234567890123456.7.azuredatabricks.net)을 입력합니다.

      3. 개인용 액세스 토큰의 경우 작업 영역 사용자에 대한 Azure Databricks 개인용 액세스 토큰을 입력합니다.

      이 자습서의 Databricks CLI 예제에서는 다음 사항에 유의하세요.

      • 이 자습서에서는 로컬 개발 컴퓨터에 환경 변수 DATABRICKS_SQL_WAREHOUSE_ID가 있다고 가정합니다. 이 환경 변수는 Databricks SQL 웨어하우스의 ID를 나타냅니다. 이 ID는 웨어하우스의 HTTP 경로 필드의 /sql/1.0/warehouses/를 따르는 문자와 숫자의 문자열입니다. 웨어하우스의 HTTP 경로 값을 가져오는 방법을 알아보려면 Azure Databricks 컴퓨팅 리소스에 대한 연결 세부 정보 가져오기를 참조하세요.
      • Unix, Linux 또는 macOS에 대한 명령 셸 대신 Windows 명령 셸을 사용하는 경우, \를 ^로, ${...}를 %...%로 바꿉니다.
      • Unix, Linux 또는 macOS에 대한 명령 셸 대신 Windows 명령 셸을 사용하는 경우, JSON 문서 선언 목록에서 시작과 종료 '를 "로, 내부 "를 \"로 바꿉니다.

    • curl은 REST API 요청 및 응답을 보내고 받기 위한 명령줄 도구입니다. curl 설치도 참조하세요. 또는 HTTPie와 같은 유사한 도구에서 사용할 수 있는 이 자습서의 curl 예제를 조정합니다.

      이 자습서의 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는 작업 영역 사용자 대신 서비스 주체에 속한 개인용 액세스 토큰을 사용하는 것을 권장합니다. 서비스 주체에 대한 토큰을 만들려면 서비스 주체에 대한 토큰 관리를 참조하세요.

      Azure Databricks 개인용 액세스 토큰을 만들려면 작업 영역 사용자에 대한 Azure Databricks 개인용 액세스 토큰의 스태프에 따릅니다.

      Warning

      Databricks는 버전 제어 시스템을 통해 일반 텍스트로 이 중요한 정보를 노출할 수 있으므로 하드 코딩 정보를 스크립트로 사용하지 않는 것이 좋습니다. Databricks는 개발 컴퓨터에서 설정한 환경 변수와 같은 접근법을 대신 사용하도록 권장합니다. 스크립트에서 이러한 하드 코딩된 정보를 제거하면 해당 스크립트의 이식성도 높일 수 있습니다.

  • 이 자습서에서는 JSON 응답 페이로드를 쿼리하기 위한 명령줄 프로세서인 jq도 있다고 가정하며, 이 프로세서는 Databricks SQL 문 실행 API를 호출할 때마다 Databricks SQL 문 실행 API를 반환합니다. jq 다운로드를 참조하세요.

  • SQL 문을 실행할 수 있는 테이블이 하나 이상 있어야 합니다. 이 자습서는 samples 카탈로그 내의 tpch 스키마(데이터베이스라고도 함)의 lineitem 테이블을 기반으로 합니다. 작업 영역에서 이 카탈로그, 스키마 또는 테이블에 액세스할 수 없는 경우 이 자습서 전체에서 직접 대체합니다.

1단계: SQL 문을 실행하고 데이터 결과를 JSON으로 저장

다음 명령을 실행하여 다음을 수행합니다.

  1. curl을 사용 중인 경우 지정된 토큰과 함께 지정된 SQL 웨어하우스를 사용하여 samples 카탈로그 내 의 tcph 스키마에 있는 lineitem 테이블의 처음 두 행에서 세 개의 열을 쿼리합니다.
  2. 응답 페이로드를 현재 작업 디렉터리 내에 있는 sql-execution-response.json이라는 파일에 JSON 형식으로 저장합니다.
  3. sql-execution-response.json 파일의 콘텐츠를 인쇄합니다.
  4. SQL_STATEMENT_ID라는 로컬 환경 변수를 설정합니다. 이 변수는 해당 SQL 문의 ID를 포함합니다. 이 SQL 문 ID를 사용하여 필요에 따라 나중에 해당 문에 대한 정보를 가져올 수 있으며, 이 정보는 2단계에서 설명합니다. Databricks SQL 콘솔의 쿼리 기록 섹션에서 또는 쿼리 기록 API를 호출하여 이 SQL 문을 보고 해당 문 ID를 가져올 수도 있습니다.
  5. JSON 데이터의 다음 청크를 가져오기 위한 API URL 조각이 포함된 NEXT_CHUNK_EXTERNAL_LINK라는 이름의 추가 로컬 환경 변수를 설정합니다. 응답 데이터가 너무 크면 Databricks SQL 문 실행 API는 청크로 응답을 제공합니다. 2단계에서 설명한 다음 데이터 청크를 가져오기 위해 이 API URL 조각을 사용할 수 있습니다. 다음 청크가 없으면 이 환경 변수는 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

이전 요청에서 다음을 수행합니다.

  • 매개 변수가 있는 쿼리는 parameters 배열에서 일치하는 name 및 value개체와 함께 콜론(예: :extended_price)이 앞에 오는 각 쿼리 매개 변수의 이름으로 구성됩니다. 선택 사항 type도 지정할 수 있으며, 지정하지 않는 경우에는 기본값 STRING입니다.

    Warning

    Databricks에서는 SQL 문에 대한 모범 사례로 매개 변수를 사용할 것을 강력하게 권장합니다.

    SQL을 동적으로 생성하는 응용 프로그램에서 Databricks SQL 문 실행 API를 사용하면 SQL 삽입 공격이 발생할 수 있습니다. 예를 들어 사용자 인터페이스에서 사용자의 선택에 따라 SQL 코드를 생성하고 적절한 조치를 취하지 않는 경우 공격자는 악의적인 SQL 코드를 삽입하여 초기 쿼리의 논리를 변경하여 중요한 데이터를 읽거나 변경하거나 삭제할 수 있습니다.

    매개 변수가 있는 쿼리는 SQL 코드의 나머지 부분과 별도로 입력 인수를 처리하고 이러한 인수를 리터럴 값으로 해석하여 SQL 삽입 공격으로부터 보호하는 데 도움이 됩니다. 매개 변수는 코드 재사용에도 도움이 될 수 있습니다.

  • 기본적으로 반환되는 모든 데이터는 JSON 배열 형식이며 SQL 문의 데이터 결과에 대한 기본 위치는 응답 페이로드 내에 있습니다. 이 동작을 명시적으로 만들려면 요청 페이로드에 "format":"JSON_ARRAY","disposition":"INLINE"을 추가합니다. 응답 페이로드에서 25MiB보다 큰 데이터 결과를 반환하려고 하면 실패 상태가 반환되고 SQL 문이 취소됩니다. 25MiB보다 큰 데이터 결과의 경우 3단계에서 보여지는 응답 페이로드에서 반환하는 대신 외부 링크를 사용할 수 있습니다.

  • 이 명령은 응답 페이로드의 콘텐츠를 로컬 파일에 저장합니다. 로컬 데이터 스토리지는 Databricks SQL 문 실행 API에서 직접 지원되지 않습니다.

  • 기본적으로 10초 후에 SQL 문이 아직 웨어하우스를 통해 실행을 완료하지 않은 경우 Databricks SQL 문 실행 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).

  • 반환되는 행 수를 제한하려면 LIMIT 절을 statement에 추가하는 대신 "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 콘솔의 쿼리 기록 섹션에서 또는 쿼리 기록 API를 호출하여 가져올 수 있습니다. 예를 들어 이 명령을 계속 폴링하여 매번 실행이 성공했는지 확인할 수 있습니다.

SQL 문의 현재 실행 상태를 가져오고 실행이 성공하면 해당 문의 결과와 JSON 데이터의 다음 청크를 가져오기 위한 API URL 조각을 가져오려면 다음 명령을 실행합니다. 이 명령은 이전 단계의 SQL 문의 ID 값으로 설정된 로컬 개발 컴퓨터 SQL_STATEMENT_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를 사용하여 현재 상태를 가져오거나 더 이상 청크를 페치할 수 없습니다.

이 섹션에서는 EXTERNAL_LINKS 처리를 사용하여 큰 데이터 집합을 검색하는 선택적 구성을 보여 줍니다. SQL 문 결과 데이터의 기본 위치(처리)는 응답 페이로드 내에 있지만 이러한 결과는 25MiB로 제한됩니다. disposition을 EXTERNAL_LINKS로 설정하면 응답에 표준 HTTP를 사용하여 결과 데이터의 청크를 가져오는 데 사용할 수 있는 URL이 포함됩니다. URL은 결과 청크가 일시적으로 저장되는 작업 영역의 내부 DBFS를 가리킵니다.

Warning

Databricks에서는 EXTERNAL_LINKS 처리에서 반환되는 URL 및 토큰을 보호하는 것이 좋습니다.

EXTERNAL_LINKS 처리를 사용하면 SAS(공유 액세스 서명) URL이 생성되며, 이 URL은 Azure Storage에서 직접 결과를 다운로드하는 데 사용할 수 있습니다. 이 SAS URL 내에 단기 SAS 토큰이 포함되므로 SAS URL과 SAS 토큰을 모두 보호해야 합니다.

SAS URL은 포함된 임시 SAS 토큰을 사용하여 이미 생성되었으므로 다운로드 요청에 Authorization 헤더를 설정해서는 안 됩니다.

지원 사례를 만들어 요청 시 EXTERNAL_LINKS 처리를 사용하지 않도록 할 수 있습니다.

보안 모범 사례도 참조하세요.

참고 항목

특정 SQL 문 ID에 대해 설정되면 응답 페이로드 출력 형식 및 동작을 변경할 수 없습니다.

이 모드에서 API를 사용하면 결과 데이터를 HTTP와 별도로 쿼리해야 하는 JSON 형식(JSON), CSV 형식(CSV) 또는 Apache 화살표 형식(ARROW_STREAM)으로 저장할 수 있습니다. 또한 이 모드를 사용하는 경우 응답 페이로드 내에서 결과 데이터를 인라인할 수 없습니다.

다음 명령은 EXTERNAL_LINKS 사용 및 Apache 화살표 형식을 보여 줍니다. 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"
  }
}

저장된 콘텐츠의 결과를 다운로드하려면 개체의 URL external_link 을 사용하고 파일을 다운로드할 위치를 지정하여 다음 curl 명령을 실행할 수 있습니다. 다음 명령에 Azure Databricks 토큰을 포함하지 마세요.

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

스트리밍된 콘텐츠 결과의 특정 청크를 다운로드하려면 다음 중 하나를 사용할 수 있습니다.

  • 다음 청크에 대한 응답 페이로드의 next_chunk_index 값입니다(다음 청크가 있는 경우).
  • 여러 청크가 있는 경우 사용 가능한 청크에 대한 응답 페이로드 매니페스트의 청크 인덱스 중 하나입니다.

예를 들어 이전 응답에서 10의 chunk_index를 사용하여 청크를 가져오려면 다음 명령을 실행합니다.

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'

참고 항목

이전 명령을 실행하면 새 SAS URL이 반환됩니다.

저장된 청크를 다운로드하려면 external_link 개체의 URL을 사용합니다.

Apache 화살표 형식에 대한 자세한 내용은 다음을 참조하세요.

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 문 실행 API는 TLS(엔드투엔드 전송 계층 보안) 암호화 및 SAS 토큰과 같은 단기 자격 증명을 사용하여 데이터 전송의 보안을 강화합니다.

이 보안 모델에는 여러 계층이 있습니다. 전송 계층에서는 TLS 1.2 이상을 사용하여 Databricks SQL 문 실행 API를 호출할 수 있습니다. 또한 Databricks SQL 문 실행 API의 호출자는 Databricks SQL을 사용할 권한이 있는 사용자에게 매핑되는 유효한 Azure Databricks 개인용 액세스 토큰, OAuth 액세스 토큰 또는 Microsoft Entra ID(이전의 Azure Active Directory) 토큰으로 인증되어야 합니다. 이 사용자는 사용 중인 특정 SQL 웨어하우스에 대해 CAN USE 액세스 권한이 있어야 하며 IP 액세스 목록으로 액세스를 제한할 수 있습니다. 이는 Databricks SQL 문 실행 API에 대한 모든 요청에 적용됩니다. 또한 문을 실행하려면 인증된 사용자에게 각 문에 사용되는 데이터 개체(예: 테이블, 보기기 및 함수)에 대한 권한이 있어야 합니다. 이는 Unity 카탈로그의 기존 액세스 제어 메커니즘 또는 테이블 ACL을 사용하여 적용됩니다. (자세한 내용은 Unity 카탈로그 를 사용한 데이터 거버넌스 참조.) 이는 또한 문을 실행하는 사용자만 문의 결과에 대한 페치 요청을 수행할 수 있음을 의미합니다.

Databricks는 EXTERNAL_LINKS 처리와 함께 Databricks SQL 문 실행 API를 사용하여 큰 데이터 집합을 검색할 때마다 다음 보안 모범 사례를 권장합니다.

  • Azure Storage 요청에 대한 Databricks 인증 헤더 제거
  • SAS URL 및 SAS 토큰 보호

지원 사례를 만들어 요청 시 EXTERNAL_LINKS 처리를 사용하지 않도록 할 수 있습니다. 이 요청을 하려면 Azure Databricks 계정 팀에 문의하세요.

Azure Storage 요청에 대한 Databricks 인증 헤더 제거

curl를 사용하는 Databricks SQL 문 실행 API에 대한 모든 호출에는 Azure Databricks 액세스 자격 증명이 포함된 Authorization 헤더가 포함되어야 합니다. Azure Storage에서 데이터를 다운로드할 때마다 이 Authorization 헤더를 포함하지 마세요. 이 헤더는 필요하지 않으며 의도치 않게 Azure Databricks 액세스 자격 증명을 노출할 수 있습니다.

SAS URL 및 SAS 토큰 보호

EXTERNAL_LINKS 처리를 사용할 때마다 단기 SAS URL이 생성되며, 호출자는 TLS를 사용하여 Azure Storage에서 직접 결과를 다운로드하는 데 사용할 수 있습니다. 이 SAS URL 내에 단기 SAS 토큰이 포함되므로 SAS URL과 SAS 토큰을 모두 보호해야 합니다.