Databricks SQL CLI
注意
この記事で説明する Databricks SQL CLI は、現状のまま提供されており、カスタマー テクニカル サポート チャネルを通じて Databricks によってサポートされているわけではありません。 ご質問や機能のリクエストは、GitHub の databricks/databricks-sql-cli リポジトリの Issue ページを通じてご連絡いただけます。
Databricks SQL コマンド ライン インターフェイス (Databricks SQL CLI) を使用すると、Databricks SQL エディターや Azure Databricks ノートブックなどの場所からではなく、ターミナルまたは Windows コマンド プロンプトから既存の Databricks SQL ウェアハウス で SQL クエリを実行できます。 コマンド ラインから、候補や構文の強調表示などの生産性向上機能を取得します。
必要条件
- 少なくとも 1 つの Databricks SQL ウェアハウス。 まだない場合は、ウェアハウスを作成します。
- Python 3.7 以上。 Python がインストールされているかどうかを確認するには、ターミナルまたはコマンド プロンプトからコマンド
python --versionを実行します。 (一部のシステムでは、代わりにpython3を入力することが必要な場合があります)。まだインストールしていない場合は、Python をインストールします。 - Python 用のパッケージ インストーラーである pip。 新しいバージョンの Python には、
pipが既定でインストールされます。pipがインストールされているかどうかを確認するには、ターミナルまたはコマンド プロンプトからコマンドpip --versionを実行します。 (一部のシステムでは、代わりにpip3を入力することが必要な場合があります)。まだインストールしていない場合は、pip をインストールします。 - (省略可能) Python 仮想環境を作成および管理するための venv などのユーティリティ。 仮想環境は、正しいバージョンの Python と Databricks SQL CLI を一緒に使用していることを確認するのに役立ちます。 仮想環境のセットアップと使用は、この記事の範囲外です。 詳細については、「Creating Virtual Environments (仮想環境を作成する)」を参照してください。
Databricks SQL CLI をインストールする
要件を満たしたら、Python Packaging Index (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 個人用アクセス トークン (AT) がサポートされています。 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 つの
#文字を削除し、host_nameの横で、要件で入手したウェアハウスの [サーバー ホスト名] の値を""文字の間に入力します。http_pathの横で、要件で入手したウェアハウスの [HTTP パス] の値を""文字の間に入力します。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 を使用すると、次の方法でクエリを実行できます。
クエリ文字列
クエリを文字列として実行するには、-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
既定のデータベースを対象にした Read-Eval-Print Loop (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 は、ログ機能を無効にします。