Databricks SQL CLI

아티클
11/16/2024

참고 항목

이 문서에서는 있는 그대로 제공되며, 고객 기술 지원 채널을 통해 Databricks에서 지원하지 않는 Databricks SQL CLI를 설명합니다. 질문 및 기능 요청은 GitHub에 있는 databricks/databricks-sql-cli 리포지토리의 문제 페이지를 통해 전달될 수 있습니다.

Databricks SQL 명령줄 인터페이스(Databricks SQL CLI)를 사용하면 Databricks SQL 편집기 또는 Azure Databricks Notebook과 같은 위치 대신 터미널 또는 Windows 명령 프롬프트에서 기존 Databricks SQL 웨어하우스에 대한 SQL 쿼리를 실행할 수 있습니다. 명령줄에서 제안 및 구문 강조 표시와 같은 생산성 기능을 구현합니다.

요구 사항

하나 이상의 Databricks SQL 웨어하우스. 아직 없는 경우 웨어하우스를 만듭니다.
Python 3.7 이상. Python이 설치되어 있는지 확인하려면 터미널 또는 명령 프롬프트에서 python --version 명령을 실행합니다. (일부 시스템에서는 대신 python3를 입력해야 할 수 있습니다.) 아직 설치되어 있지 않은 경우 Python을 설치합니다.
pip(Python용 패키지 설치 프로그램). 최신 버전의 Python은 기본적으로 pip를 설치합니다. pip가 설치되어 있는지 확인하려면 터미널 또는 명령 프롬프트에서 pip --version 명령을 실행합니다. (일부 시스템에서는 대신 pip3를 입력해야 할 수 있습니다.) 아직 설치되어 있지 않은 경우 pip를 설치합니다.
(선택 사항) venv와 같은 Python 가상 환경을 만들고 관리하기 위한 유틸리티. 가상 환경은 올바른 버전의 Python과 Databricks SQL CLI를 함께 사용하는 데 도움이 됩니다. 가상 환경 설정 및 사용은 이 문서의 범위를 벗어납니다. 자세한 내용은 가상 환경 만들기를 참조하세요.

Databricks SQL CLI 설치

요구 사항을 충족한 후 PyPI(Python 패키징 인덱스)에서 Databricks SQL CLI 패키지를 설치합니다. pip를 사용하여 pip와 함께 다음 명령 중 하나를 실행해서 PyPI에서 Databricks SQL CLI 패키지를 설치할 수 있습니다.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

이전에 설치된 Databricks SQL CLI 버전을 업그레이드하려면 pip와 함께 다음 명령 중 하나를 실행합니다.

pip install databricks-sql-cli --upgrade

# Or...

python -m pip install databricks-sql-cli --upgrade

설치된 Databricks SQL CLI 버전을 확인하려면 pip와 함께 다음 명령 중 하나를 실행합니다.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

인증

인증하려면 Databricks SQL CLI에 웨어하우스의 연결 세부 정보를 제공해야 합니다. 특히 서버 호스트 이름 및 HTTP 경로 값이 필요합니다. 또한 적절한 인증 자격 증명을 사용하여 Databricks SQL CLI를 제품화해야 합니다.

Databricks SQL CLI는 Databricks PAT(개인용 액세스 토큰)를 지원합니다. Azure Databricks PAT 인증을 사용하려면 개인 액세스 토큰을 만들어야 합니다. 이 프로세스에 대한 자세한 내용은 Azure Databricks 개인용 액세스 토큰 인증을 참조하세요.

Microsoft Entra ID 토큰은 지원되지 않습니다.

다음과 같은 여러 가지 방법으로 Databricks SQL CLI에 이 인증 정보를 제공할 수 있습니다.

기본 위치의 dbsqlclirc 설정 파일에서(또는 Databricks SQL CLI로 명령을 실행할 때마다 --clirc 옵션을 통해 대체 설정 파일 지정). 설정 파일을 참조하세요.
DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH 및 DBSQLCLI_ACCESS_TOKEN 환경 변수 설정. 환경 변수를 참조하세요.
Databricks SQL CLI를 사용하여 명령을 실행할 때마다 --hostname, --http-path 및 --access-token 옵션 지정. 명령 옵션을 참조하세요.

참고 항목

이전 환경 변수를 설정하거나 이전 명령 옵션 또는 둘 다를 지정하더라도 dbsqlclirc 설정 파일이 있어야 합니다.

Databricks SQL CLI를 실행할 때마다 다음 순서로 인증 세부 정보를 찾고 첫 번째 세부 정보 세트를 찾으면 중지합니다.

--hostname, --http-path 및 --access-token 옵션.
DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH 및 DBSQLCLI_ACCESS_TOKEN 환경 변수.
기본 위치의 dbsqlclirc 설정 파일(또는 --clirc 옵션으로 지정된 대체 설정 파일).

설정 파일

dbsqlclirc 설정 파일을 사용하여 Databricks SQL 웨어하우스에 대한 인증 세부 정보를 Databricks SQL CLI에 제공하려면 다음과 같이 Databricks SQL CLI를 처음으로 실행합니다.

dbsqlcli

Databricks SQL CLI는 Unix, Linux 및 macOS의 경우 ~/.dbsqlcli/dbsqlclirc, Windows의 경우 %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc 또는 %USERPROFILE%\.dbsqlcli\dbsqlclirc에 자동으로 설정 파일을 만듭니다. 이 파일을 사용자 지정하려면 다음을 수행합니다.

텍스트 편집기를 사용하여 dbsqlclirc 파일을 열고 편집합니다.

다음 섹션으로 스크롤합니다.

# [credentials]
# host_name = ""
# http_path = ""
# access_token = ""

# 문자 4개를 제거하고 다음을 수행합니다.
1. host_name 옆에 요구 사항에 있는 웨어하우스의 서버 호스트 이름 값을 ""자 사이로 입력합니다.
2. http_path 옆에 요구 사항에 있는 웨어하우스의 HTTP 경로 값을 ""자 사이로 입력합니다.
3. access_token 옆에 요구 사항에 있는 개인용 액세스 토큰 값을 ""자 사이로 입력합니다.
예시:
```
[credentials]
host_name = "adb-12345678901234567.8.azuredatabricks.net"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"
```
dbsqlclirc 파일을 저장합니다.

또는 기본 위치에서 dbsqlclirc 파일을 사용하는 대신 --clirc 명령 옵션과 대체 파일 경로를 추가하여 다른 위치에 파일을 지정할 수 있습니다. 대체 파일의 내용은 이전 구문을 준수해야 합니다.

환경 변수

DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH 및 DBSQLCLI_ACCESS_TOKEN 환경 변수를 사용하여 Databricks SQL 웨어하우스에 대한 인증 세부 정보를 Databricks SQL CLI에 제공하려면 다음을 수행합니다.

Unix, Linux 및 macOs

현재 터미널 세션에 대해서만 환경 변수를 설정하려면 다음 명령을 실행합니다. 모든 터미널 세션에 대한 환경 변수를 설정하려면 셸의 시작 파일에 다음 명령을 입력한 다음, 터미널을 다시 시작합니다. 다음 명령에서 다음 항목의 값을 바꿉니다.

DBSQLCLI_HOST_NAME을 요구 사항에 있는 웨어하우스의 서버 호스트 이름 값으로 바꿉니다.
DBSQLCLI_HTTP_PATH를 요구 사항에 있는 웨어하우스의 HTTP 경로 값으로 바꿉니다.
DBSQLCLI_ACCESS_TOKEN을 요구 사항에 있는 개인용 액세스 토큰 값으로.

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

현재 명령 프롬프트 세션에 대해서만 환경 변수를 설정하려면 값을 다음과 같이 바꾸고 다음 명령을 실행합니다.

DBSQLCLI_HOST_NAME을 요구 사항에 있는 웨어하우스의 서버 호스트 이름 값으로 바꿉니다.
DBSQLCLI_HTTP_PATH를 요구 사항에 있는 웨어하우스의 HTTP 경로 값으로 바꿉니다.
DBSQLCLI_ACCESS_TOKEN을 요구 사항에 있는 개인용 액세스 토큰 값으로.

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

모든 명령 프롬프트 세션에 대한 환경 변수를 설정하려면 값을 다음과 같이 바꾸고 다음 명령을 실행한 다음, 명령 프롬프트를 다시 시작합니다.

DBSQLCLI_HOST_NAME을 요구 사항에 있는 웨어하우스의 서버 호스트 이름 값으로 바꿉니다.
DBSQLCLI_HTTP_PATH를 요구 사항에 있는 웨어하우스의 HTTP 경로 값으로 바꿉니다.
DBSQLCLI_ACCESS_TOKEN을 요구 사항에 있는 개인용 액세스 토큰 값으로.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

명령 옵션

--hostname, --http-path 및 --access-token 옵션을 사용하여 Databricks SQL 웨어하우스에 대한 인증 세부 정보를 Databricks SQL CLI에 제공하려면 다음을 수행합니다.

Databricks SQL CLI를 사용하여 명령을 실행할 때마다 다음을 수행합니다.

요구 사항에 있는 --hostname 옵션 및 웨어하우스의 서버 호스트 이름 값을 지정합니다.
요구 사항에 있는 --http-path 옵션 및 웨어하우스의 HTTP 경로 값을 지정합니다.
요구 사항에 있는 --access-token 옵션 및 개인 액세스 토큰 값을 지정합니다.

예시:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

쿼리 원본

Databricks SQL CLI를 사용하면 다음과 같은 방법으로 쿼리를 실행할 수 있습니다.

쿼리 문자열에서.
파일에서.
REPL(read-evaluate-print loop) 방법으로. 이 방법은 입력할 때 제안을 제공합니다.

쿼리 문자열

쿼리를 문자열로 실행하려면 -e 옵션 뒤에 문자열로 표시된 쿼리를 사용합니다. 예시:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"

출력:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

출력 형식을 전환하려면 ASCII 테이블 형식에 해당하는 ascii 같은 값과 함께 --table-format 옵션을 사용합니다. 예를 들면 다음과 같습니다.

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii

출력:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

사용 가능한 출력 형식 값 목록은 dbsqlclirc 파일의 table_format 설정에 대한 설명을 참조하세요.

파일

SQL이 포함된 파일을 실행하려면 -e 옵션 뒤에 .sql 파일 경로를 사용합니다. 예시:

dbsqlcli -e my-query.sql

예제 my-query.sql 파일의 내용:

SELECT * FROM default.diamonds LIMIT 2;

출력:

_c0,carat,cut,color,clarity,depth,table,price,x,y,z
1,0.23,Ideal,E,SI2,61.5,55,326,3.95,3.98,2.43
2,0.21,Premium,E,SI1,59.8,61,326,3.89,3.84,2.31

출력 형식을 전환하려면 ASCII 테이블 형식에 해당하는 ascii 같은 값과 함께 --table-format 옵션을 사용합니다. 예를 들면 다음과 같습니다.

dbsqlcli -e my-query.sql --table-format ascii

출력:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

사용 가능한 출력 형식 값 목록은 dbsqlclirc 파일의 table_format 설정에 대한 설명을 참조하세요.

REPL

기본 데이터베이스로 범위가 지정된 REPL(read-evaluate-print loop) 모드를 입력하려면 다음 명령을 실행합니다.

dbsqlcli

다음 명령을 실행하여 특정 데이터베이스로 범위가 지정된 REPL 모드를 입력할 수도 있습니다.

dbsqlcli <database-name>

예시:

dbsqlcli default

REPL 모드를 종료하려면 다음 명령을 실행합니다.

exit

REPL 모드에서는 다음 문자와 키를 사용할 수 있습니다.

세미콜론(;)을 사용하여 줄을 종료합니다.
F3 키를 사용하여 여러 줄 모드를 전환합니다.
제안이 아직 표시되지 않는 경우 스페이스바를 사용하여 삽입 지점에 제안을 표시합니다.
위쪽 및 아래쪽 화살표를 사용하여 제안을 탐색합니다.
오른쪽 화살표를 사용하여 강조 표시된 제안을 완료합니다.

예시:

dbsqlcli default

hostname:default> SELECT * FROM diamonds LIMIT 2;

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _c0 | carat | cut     | color | clarity | depth | table | price | x    | y    | z    |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| 1   | 0.23  | Ideal   | E     | SI2     | 61.5  | 55    | 326   | 3.95 | 3.98 | 2.43 |
| 2   | 0.21  | Premium | E     | SI1     | 59.8  | 61    | 326   | 3.89 | 3.84 | 2.31 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

2 rows in set
Time: 0.703s

hostname:default> exit

로깅

Databricks SQL CLI는 기본적으로 해당 메시지를 파일 ~/.dbsqlcli/app.log에 기록합니다. 이 파일 이름 또는 위치를 변경하려면 dbsqlclirc 설정 파일에서 log_file 설정의 값을 변경합니다.

기본적으로 메시지는 INFO 로그 수준 및 아래에 기록됩니다. 이 로그 수준을 변경하려면 dbsqlclirc 설정 파일에서 log_level 설정 값을 변경합니다. 사용 가능한 로그 수준 값은 CRITICAL, ERROR, WARNING, INFO 및 DEBUG를 포함하며 해당 순서로 평가됩니다. NONE은 로깅을 사용 안 합니다.

다음을 통해 공유