Databricks SQL CLI

發行項
10/01/2024

注意

本文涵蓋 Databricks SQL CLI，此 CLI 依現況提供，且 Databricks 不透過客戶技術支援管道提供支援。您可以透過 GitHub 上 databricks/databricks-sql-cli 存放庫的問題頁面來傳達問題和功能要求。

Databricks SQL 命令列介面 (Databricks SQL CLI) 可讓您從終端機或 Windows 命令提示字元在現有 Databricks SQL 倉儲上執行 SQL 查詢，而不是從 Databricks SQL 編輯器或 Azure Databricks 筆記本等位置執行。您可以從命令列取得生產力功能，例如建議和語法醒目提示。

需求

至少有一個 Databricks SQL 倉儲。如果您還沒有倉儲，則建立倉儲。
Python 3.7 或更新版本。若要檢查您是否已安裝 Python，請從終端機或命令提示字元執行命令 python --version。 (在某些系統上，您可能需要改為輸入 python3。) 如果您尚未安裝 Python，請安裝 Python。
適用於 Python 的 pip 套件安裝程式。較新版本的 Python 預設會安裝 pip。若要檢查您是否已安裝 pip，請從終端機或命令提示字元執行命令 pip --version。 (在某些系統上，您可能需要改為輸入 pip3。) 如果您尚未安裝 pip，請安裝 Python。
(選擇性) 用來建立和管理 Python 虛擬環境的公用程式，例如 venv。虛擬環境可協助您確保同時使用正確的 Python 版本和 Databricks SQL CLI。設定和使用虛擬環境不屬於本文的討論範圍。如需詳細資訊，請參閱建立虛擬環境。

安裝 Databricks SQL CLI

符合需求之後，請從 Python 封裝索引 (PyPI) 安裝 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 個人存取權杖驗證。不支援 Microsoft Entra ID 權杖。

若要使用 Azure Databricks 個人存取權杖驗證，請建立 Azure Databricks 個人存取權杖，如下所示：

在 Azure Databricks 工作區中，按一下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定]。
按一下 [開發人員]。
在 [存取權杖] 旁，按一下 [管理]。
按一下 產生新權杖。
(選擇性) 輸入可協助您之後識別此權杖的註解，並變更權杖的預設存留期 90 天。若要建立沒有存留期的權杖 (不建議)，請將 [存留期 (天)] 方塊留空 (空白)。
按一下產生。
將顯示的權杖複製到安全位置，然後選取 [完成]。

注意

請務必將複製的權杖儲存在安全位置。請勿與其他人共用複製的權杖。如果您遺失複製的權杖，就無法重新產生完全相同的權杖。相反地，您必須重複此程序來建立新的權杖。如果您遺失複製的權杖，或您認為權杖已遭入侵，Databricks 強烈建議您按一下 [存取權杖] 頁面上權杖旁邊的垃圾桶 (撤銷) 圖示，立即從工作區中刪除該權杖。

注意：如果您無法在工作區中建立或使用 PAT，這可能是因為您的工作區系統管理員已停用權杖，或未授與您建立或使用權杖的權限。請諮詢您的工作區系統管理員或參閱下列主題：

您可透過數種方式，將此驗證資訊提供給 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 CLI 提供 Databricks SQL 倉儲的驗證詳細資料，請首次執行 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 = ""

移除四個 # 字元，並：
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檔案。

或者，您可以藉由將 --clirc 命令選項和路徑新增至替代檔案，來指定位於不同位置的檔案，而不是在其預設位置使用 dbsqlclirc 檔案。該替代檔案的內容必須符合上述語法。

環境變數

若要使用 DBSQLCLI_HOST_NAME、 DBSQLCLI_HTTP_PATH和 DBSQLCLI_ACCESS_TOKEN 環境變數，為 Databricks SQL CLI 提供 Databricks SQL 倉儲的驗證詳細資料，請執行下列動作：

Unix、Linux 和 macOS

若要只設定目前終端機工作階段的環境變數，請執行下列命令。若要設定所有終端機工作階段的環境變數，請在殼層的啟動檔案中輸入下列命令，然後重新啟動終端機。在下列命令中，取代下列值：

使用來自需求的倉儲 [伺服器主機名稱] 值取代 DBSQLCLI_HOST_NAME 值。
使用來自需求的倉儲 [HTTP 路徑] 值取代 DBSQLCLI_HTTP_PATH 值。
使用來自需求的個人存取權杖值取代 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 值。
使用來自需求的倉儲 [HTTP 路徑] 值取代 DBSQLCLI_HTTP_PATH 值。
使用來自需求的個人存取權杖值取代 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 值。
使用來自需求的倉儲 [HTTP 路徑] 值取代 DBSQLCLI_HTTP_PATH 值。
使用來自需求的個人存取權杖值取代 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 CLI 提供 Databricks SQL 倉儲的驗證詳細資料，請執行下列動作：

每次使用 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) 方法中。此方法會在您鍵入時提供建議。

查詢字串

若要以字串的形式執行查詢，請使用 -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

若要切換輸出格式，請使用 --table-format 選項以及一個值，如 ASCII 資料表格式的 ascii，例如：

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

若要切換輸出格式，請使用 --table-format 選項以及一個值，如 ASCII 資料表格式的 ascii，例如：

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) 模式，請執行下列命令：

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 停用記錄。

共用方式為