Databricks SQL CLI

项目
09/09/2024

注意

本文介绍 Databricks SQL CLI，它按原样提供，并且 Databricks 不会通过客户技术支持渠道为它提供支持。如需解答问题和提出功能请求，可以通过 GitHub 上 databricks/databricks-sql-cli 存储库的“问题”页沟通。

使用 Databricks SQL 命令行接口 (Databricks SQL CLI)，可从终端或 Windows 命令提示符（而不是从 Databricks SQL 编辑器或 Azure Databricks 笔记本等位置）对现有 Databricks SQL 仓库运行 SQL 查询。在命令行中，可获得建议和语法突出显示等高效功能。

要求

至少一个 Databricks SQL 仓库。如果还没有仓库，请创建一个仓库。
Python 3.7 或更高版本。要检查是否已安装 Python，请从终端或命令提示符运行 python --version 命令。（在某些系统中，可能需要改为输入 python3。）安装 Python（如果尚未安装）。
pip，Python 的包安装程序。新版本的 Python 会默认安装 pip。要检查是否已安装 pip，请从终端或命令提示符运行 pip --version 命令。（在某些系统中，可能需要改为输入 pip3。）安装 pip（如果尚未安装）。
（可选）用于创建和管理 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 用户名，然后从下拉列表中选择“设置”。
单击“开发人员”。
在“访问令牌”旁边，单击“管理”。
单击“生成新令牌”。
（可选）输入有助于将来识别此令牌的注释，并将令牌的默认生存期更改为 90 天。若要创建没有生存期的令牌（不建议），请将“生存期(天)”框留空（保留空白）。
单击“生成” 。
将显示的令牌复制到安全位置，然后单击“完成”。

注意

请务必将复制的令牌保存到安全的位置。请勿与他人共享复制的令牌。如果丢失了复制的令牌，你将无法重新生成完全相同的令牌，而必须重复此过程来创建新令牌。如果丢失了复制的令牌，或者认为令牌已泄露，Databricks 强烈建议通过单击“访问令牌”页上令牌旁边的垃圾桶（撤销）图标立即从工作区中删除该令牌。

如果你无法在工作区中创建或使用令牌，可能是因为工作区管理员已禁用令牌或未授予你创建或使用令牌的权限。请与工作区管理员联系，或参阅以下内容：

你可以通过多种方式向 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 在 ~/.dbsqlcli/dbsqlclirc（Unix、Linux 和 macOS 上）或者在 %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc 或 %USERPROFILE%\.dbsqlcli\dbsqlclirc（Windows 上）为你创建设置文件。要自定义此文件，请执行以下操作：

使用文本编辑器打开并编辑 dbsqlclirc 文件。

滚动到下列部分：

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

删除四个 # 字符，并执行以下操作：
1. 在 host_name 旁边的 "" 字符之间，输入“要求”部分中的仓库的“服务器主机名”值。
2. 在 http_path 旁边的 "" 字符之间，输入“要求”部分中的仓库的“HTTP 路径”值。
3. 在 access_token 旁边的 "" 字符之间，输入“要求”部分中的个人访问令牌值。
例如：
```
[credentials]
host_name = "adb-12345678901234567.8.databricks.azure.cn"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "<36bit_Character_And_Digital_Token_Placeholder>"
```
保存 dbsqlclirc 文件。

或者，可通过添加 --clirc 命令选项和备用文件的路径来指定其他位置中的文件，而不使用其默认位置中的 dbsqlclirc 文件。该备用文件的内容必须符合前面的语法。

环境变量

要使用 DBSQLCLI_HOST_NAME、DBSQLCLI_HTTP_PATH 和 DBSQLCLI_ACCESS_TOKEN 环境变量向 Databricks SQL CLI 提供 Databricks SQL 仓库的身份验证详细信息，请执行以下操作：

Unix、linux 和 macOS

如果只为当前终端会话设置环境变量，请运行以下命令。如果要为所有终端会话设置环境变量，请在 shell 的启动文件中输入以下命令，然后重启终端。在下面的命令中，替换以下值：

将 DBSQLCLI_HOST_NAME 替换为“要求”部分中的仓库的“服务器主机名”值。
将 DBSQLCLI_HTTP_PATH 替换为“要求”部分中的仓库的“HTTP 路径”值。
将 DBSQLCLI_ACCESS_TOKEN 替换为“要求”部分中的个人访问令牌值。

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.databricks.azure.cn"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="<36bit_Character_And_Digital_Token_Placeholder>"

Windows

如果只为当前命令提示符会话设置环境变量，请运行以下命令，替换以下值：

将 DBSQLCLI_HOST_NAME 替换为“要求”部分中的仓库的“服务器主机名”值。
将 DBSQLCLI_HTTP_PATH 替换为“要求”部分中的仓库的“HTTP 路径”值。
将 DBSQLCLI_ACCESS_TOKEN 替换为“要求”部分中的个人访问令牌值。

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.databricks.azure.cn"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="<36bit_Character_And_Digital_Token_Placeholder>"

要为所有命令提示符会话设置环境变量，请运行以下命令，然后重启命令提示符，替换以下值：

将 DBSQLCLI_HOST_NAME 替换为“要求”部分中的仓库的“服务器主机名”值。
将 DBSQLCLI_HTTP_PATH 替换为“要求”部分中的仓库的“HTTP 路径”值。
将 DBSQLCLI_ACCESS_TOKEN 替换为“要求”部分中的个人访问令牌值。

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.databricks.azure.cn"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "<36bit_Character_And_Digital_Token_Placeholder>"

命令选项

要使用 --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.databricks.azure.cn" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "<36bit_Character_And_Digital_Token_Placeholder>"

查询源

使用 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 禁用日志记录。

通过