문 실행 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는 Databricks REST API 요청 및 응답을 보내고 받기 위한 명령줄 도구입니다. Databricks CLI 버전 0.205 이상을 사용하도록 선택하는 경우 Azure Databricks 작업 영역에서 인증하도록 구성해야 합니다. Databricks CLI에 대한 Databricks CLI 및 인증 설치 또는 업데이트를 참조하세요.
예를 들어 Databricks 개인용 액세스 토큰 인증으로 인증하려면 다음과 같이 개인 액세스 토큰을 만듭니다.
- Azure Databricks 작업 영역의 위쪽 표시줄에서 Azure Databricks 사용자 이름을 클릭한 다음 드롭다운에서 설정을 선택합니다.
- 개발자를 클릭합니다.
- 액세스 토큰 옆에 있는 관리를 클릭합니다.
- 새 토큰 생성을 클릭합니다.
- (선택 사항) 나중에 이 토큰을 식별할 수 있도록 하는 설명을 입력하고 토큰의 기본 수명을 90일로 변경합니다. 수명이 없는 토큰을 만들려면(권장하지 않음) 수명(일) 상자를 비워 둡니다(공백).
- 생성을 클릭합니다.
- 표시된 토큰을 안전한 위치에 복사한 다음 완료를 클릭합니다.
참고 항목
복사한 토큰을 안전한 위치에 저장합니다. 복사한 토큰을 다른 사용자와 공유하지 마세요. 복사한 토큰을 분실하면 정확히 동일한 토큰을 다시 생성할 수 없습니다. 대신 이 프로시저를 반복하여 새 토큰을 만들어야 합니다. 복사한 토큰이 손실되었거나 토큰이 손상되었다고 생각되는 경우 Databricks는 액세스 토큰 페이지의 토큰 옆에 있는 휴지통(해지) 아이콘을 클릭하여 작업 영역에서 해당 토큰 을 즉시 삭제하는 것이 좋습니다.
작업 영역에서 토큰을 만들거나 사용할 수 없는 경우 작업 영역 관리자가 토큰을 사용하지 않도록 설정했거나 토큰을 만들거나 사용할 수 있는 권한을 부여하지 않았기 때문일 수 있습니다. 작업 영역 관리자 또는 다음을 참조하세요.
그런 다음 Databricks CLI를 사용하여 개인 액세스 토큰에 대한 Azure Databricks 구성 프로필을 만들려면 다음을 수행합니다.
참고 항목
다음 절차에서는 Databricks CLI를 사용하여 이름으로
DEFAULTAzure Databricks 구성 프로필을 만듭니다. 구성 프로필이 이미 있는DEFAULT경우 이 절차는 기존DEFAULT구성 프로필을 덮어씁니다.구성 프로필이
DEFAULT이미 있는지 확인하고 이 프로필의 설정이 있는지 확인하려면 Databricks CLI를 사용하여 명령을databricks auth env --profile DEFAULT실행합니다.이름이 아닌
DEFAULT다른 이름으로 구성 프로필을 만들려면 다음databricks configure명령의--profile DEFAULT일부를 구성 프로필의 다른 이름으로 바꿉DEFAULT있습니다.Databricks CLI를 사용하여 Azure Databricks 개인용 액세스 토큰 인증을 사용하는 Azure
DEFAULTDatabricks 구성 프로필을 만듭니다. 이렇게 하려면 다음 명령을 실행합니다.databricks configure --profile DEFAULT프롬프트 Databricks 호스트의 경우 작업 영역별 Azure Databricks URL을 입력합니다. 예를 들면 다음과 같습니다
https://adb-1234567890123456.7.azuredatabricks.net.프롬프트 개인 액세스 토큰의 경우 작업 영역에 대한 Azure Databricks 개인용 액세스 토큰을 입력합니다.
이 자습서의 Databricks CLI 예제에서는 다음 사항에 유의하세요.
- 이 자습서에서는 로컬 개발 머신에 환경 변수
DATABRICKS_SQL_WAREHOUSE_ID가 있다고 가정합니다. 이 환경 변수는 Databricks SQL Warehouse의 ID를 나타냅니다. 이 ID는 웨어하우스의 HTTP 경로 필드에서 다음/sql/1.0/warehouses/문자와 숫자의 문자열입니다. 웨어하우스의 HTTP 경로 값을 가져오는 방법을 알아보려면 Azure Databricks 컴퓨팅 리소스에 대한 연결 세부 정보 가져오기를 참조하세요. - Unix, Linux 또는 macOS에 대한 명령 셸 대신 Windows 명령 셸을 사용하는 경우 ,
${...}으로^바꾸고\.%...% - Unix, Linux 또는 macOS용 명령 셸 대신 Windows 명령 셸을 사용하는 경우 JSON 문서 선언에서 여는 항목과 닫기를
'바꾸고"내부"를 으로\"바꿉니다.
curl 은 REST API 요청 및 응답을 보내고 받기 위한 명령줄 도구입니다. curl 설치도 참조하세요. 또는 Postman 또는 HTTPie와 같은 유사한 도구에서 사용하기 위해 이 자습서의
curl예제를 조정할 수 있습니다.이 자습서의 예제에서는 다음 사항에 유의
curl하세요.- 대신
--header "Authorization: Bearer ${DATABRICKS_TOKEN}".netrc 파일을 사용할 수 있습니다. 파일을--header "Authorization: Bearer ${DATABRICKS_TOKEN}"--netrc사용하는 경우 ..netrc - Unix, Linux 또는 macOS에 대한 명령 셸 대신 Windows 명령 셸을 사용하는 경우 ,
${...}으로^바꾸고\.%...% - Unix, Linux 또는 macOS용 명령 셸 대신 Windows 명령 셸을 사용하는 경우 JSON 문서 선언에서 여는 항목과 닫기를
'바꾸고"내부"를 으로\"바꿉니다.
또한 이 자습서의
curl예제에서는 로컬 개발 머신에 다음과 같은 환경 변수가 있다고 가정합니다.DATABRICKS_HOSTAzure Databricks 작업 영역에 대한 작업 영역 인스턴스 이름(예:DATABRICKS_TOKEN- Azure Databricks 작업 영역 사용자에 대한 Azure Databricks 개인용 액세스 토큰 을 나타냅니다.DATABRICKS_SQL_WAREHOUSE_IDDatabricks SQL Warehouse의 ID를 나타내는 입니다. 이 ID는 웨어하우스의 HTTP 경로 필드에서 다음/sql/1.0/warehouses/문자와 숫자의 문자열입니다. 웨어하우스의 HTTP 경로 값을 가져오는 방법을 알아보려면 Azure Databricks 컴퓨팅 리소스에 대한 연결 세부 정보 가져오기를 참조하세요.
참고 항목
보안 모범 사례로, 자동화된 도구, 시스템, 스크립트 및 앱을 사용하여 인증하는 경우 Databricks는 작업 영역 사용자 대신 서비스 주체에 속한 개인용 액세스 토큰을 사용하는 것이 좋습니다. 서비스 주체에 대한 토큰을 만들려면 서비스 주체에 대한 토큰 관리를 참조하세요.
Azure Databricks 개인용 액세스 토큰을 만들려면 다음을 수행합니다.
- Azure Databricks 작업 영역의 위쪽 표시줄에서 Azure Databricks 사용자 이름을 클릭한 다음 드롭다운에서 설정을 선택합니다.
- 개발자를 클릭합니다.
- 액세스 토큰 옆에 있는 관리를 클릭합니다.
- 새 토큰 생성을 클릭합니다.
- (선택 사항) 나중에 이 토큰을 식별할 수 있도록 하는 설명을 입력하고 토큰의 기본 수명을 90일로 변경합니다. 수명이 없는 토큰을 만들려면(권장하지 않음) 수명(일) 상자를 비워 둡니다(공백).
- 생성을 클릭합니다.
- 표시된 토큰을 안전한 위치에 복사한 다음 완료를 클릭합니다.
참고 항목
복사한 토큰을 안전한 위치에 저장합니다. 복사한 토큰을 다른 사용자와 공유하지 마세요. 복사한 토큰을 분실하면 정확히 동일한 토큰을 다시 생성할 수 없습니다. 대신 이 프로시저를 반복하여 새 토큰을 만들어야 합니다. 복사한 토큰이 손실되었거나 토큰이 손상되었다고 생각되는 경우 Databricks는 액세스 토큰 페이지의 토큰 옆에 있는 휴지통(해지) 아이콘을 클릭하여 작업 영역에서 해당 토큰 을 즉시 삭제하는 것이 좋습니다.
작업 영역에서 토큰을 만들거나 사용할 수 없는 경우 작업 영역 관리자가 토큰을 사용하지 않도록 설정했거나 토큰을 만들거나 사용할 수 있는 권한을 부여하지 않았기 때문일 수 있습니다. 작업 영역 관리자 또는 다음을 참조하세요.
Warning
Databricks는 이 중요한 정보가 버전 제어 시스템을 통해 일반 텍스트로 노출될 수 있으므로 스크립트에 대한 하드 코딩 정보를 강력하게 권장하지 않습니다. Databricks는 개발 머신에서 설정한 환경 변수와 같은 접근 방식을 대신 사용하는 것이 좋습니다. 스크립트에서 이러한 하드 코딩된 정보를 제거하면 해당 스크립트의 이식성도 높일 수 있습니다.
- 대신
이 자습서에서는 JSON 응답 페이로드를 쿼리하기 위한 명령줄 프로세서인 jq도 있다고 가정합니다. 이 프로세서는 Databricks SQL 문 실행 API를 호출할 때마다 Databricks SQL 문 실행 API가 반환합니다. 다운로드 jq를 참조하세요.
SQL 문을 실행할 수 있는 테이블이 하나 이상 있어야 합니다. 이 자습서는 카탈로그 내의
tpch스키마(데이터베이스라고도 함)의 테이블을 기반으로lineitem합니다samples. 작업 영역에서 이 카탈로그, 스키마 또는 테이블에 액세스할 수 없는 경우 이 자습서 전체에서 직접 대체합니다.
1단계: SQL 문을 실행하고 데이터 결과를 JSON으로 저장
다음 명령을 실행합니다.
- 사용 중인 경우 지정된 토큰과 함께 지정된 SQL 웨어하우스를 사용하여
curl카탈로그 내samples의 스키마에 있는tcph테이블의lineitem처음 두 행에서 세 개의 열을 쿼리합니다. - 응답 페이로드를 현재 작업 디렉터리 내에 있는
sql-execution-response.json파일에 JSON 형식으로 저장합니다. - 파일의
sql-execution-response.json내용을 인쇄합니다. - 라는
SQL_STATEMENT_ID로컬 환경 변수를 설정합니다. 이 변수는 해당 SQL 문의 ID를 포함합니다. 이 SQL 문 ID를 사용하여 필요에 따라 나중에 해당 문에 대한 정보를 가져올 수 있습니다. 이 정보는 2단계에서 설명합니다. Databricks SQL 콘솔의 쿼리 기록 섹션에서 또는 쿼리 기록 API를 호출하여 이 SQL 문을 보고 해당 문 ID를 가져올 수도 있습니다. - JSON 데이터의 다음 청크를 가져오기 위한 API URL 조각이 포함된 명명된
NEXT_CHUNK_EXTERNAL_LINK추가 로컬 환경 변수를 설정합니다. 응답 데이터가 너무 크면 Databricks SQL 문 실행 API는 청크로 응답을 제공합니다. 2단계에서 설명한 다음 데이터 청크를 가져오기 위해 이 API URL 조각을 사용할 수 있습니다. 다음 청크가 없으면 이 환경 변수가 .로null설정됩니다. - 환경 변수 및
NEXT_CHUNK_INTERNAL_LINK환경 변수의SQL_STATEMENT_ID값을 인쇄합니다.
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
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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
이전 요청에서 다음을 수행합니다.
매개 변수가 있는 쿼리는 배열에서 일치하는 개체와
value함께name콜론(예::extended_price)이 앞에 오는 각 쿼리 매개 변수의parameters이름으로 구성됩니다. 선택 사항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", 예를 들어"50s"포함 시간(초)을50포함5할 수 있는 위치<x>로 설정합니다"<x>s". SQL 문 ID 및 현재 상태를 즉시 반환하려면 .로0s설정합니다wait_timeout.기본적으로 시간 제한 기간에 도달하면 SQL 문이 계속 실행됩니다. 대신 시간 제한 기간에 도달한 경우 SQL 문을 취소하려면 요청 페이로드에 추가
"on_wait_timeout":"CANCEL"합니다.반환되는 바이트 수를 제한하려면 요청에 추가하고
"byte_limit"바이트 수(예1000: 바이트)로 설정합니다.반환되는 행 수를 제한하려면 절을 추가하는
LIMIT대신 요청에 추가하고"row_limit"행 수로 설정할 수 있습니다. 예를 들면 다음과 같습니다"statement":"SELECT * FROM lineitem","row_limit":2.statement결과가 지정된
byte_limit것보다 크거나row_limittruncated응답 페이로드에서 필드가 설정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 문의 하드 코딩된 ID로 대체할 ${SQL_STATEMENT_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
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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 문 결과 데이터의 기본 위치(처리)는 응답 페이로드 내에 있지만 이러한 결과는 25MiB로 제한됩니다. 이 값을 EXTERNAL_LINKS설정 disposition 하면 응답에 표준 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
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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'
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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다음 청크에 대한 응답 페이로드의 값입니다(다음 청크가 있는 경우).- 여러 청크가 있는 경우 사용 가능한 청크에 대한 응답 페이로드 매니페스트의 청크 인덱스 중 하나입니다.
예를 들어 이전 응답의 청크를 chunk_index10 가져오려면 다음 명령을 실행합니다.
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'
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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이 반환됩니다.
저장된 청크를 다운로드하려면 개체의 URL을 external_link 사용합니다.
Apache 화살표 형식에 대한 자세한 내용은 다음을 참조하세요.
4단계: SQL 문의 실행 취소
아직 성공하지 못한 SQL 문을 취소해야 하는 경우 다음 명령을 실행합니다.
Databricks CLI
databricks api post /api/2.0/sql/statements/${SQL_STATEMENT_ID}/cancel \
--profile <profile-name> \
--json '{}'
인증을 위해 Azure Databricks 구성 프로필의 이름으로 바꿉 <profile-name> 니다.
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 개인용 액세스 토큰 또는 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 토큰을 모두 보호해야 합니다.
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기