Databricks SQL CLI

[アーティクル]
05/14/2024

注意

この記事で説明する 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 個人用アクセストークン認証がサポートされています。 Microsoft Entra ID (旧称 Azure Active Directory) トークンはサポートされていません。

Azure Databricks 個人用アクセストークン認証を使用するには、次にようにして個人用アクセストークンを作成します。

Azure Databricks ワークスペースの上部バーで、目的の Azure Databricks ユーザー名をクリックし、次にドロップダウンから [設定] を選択します。
[開発者] をクリックします。
[アクセストークン] の横にある [管理] をクリックします。
[新しいトークンの生成] をクリックします。
(省略可能) 将来このトークンを識別するのに役立つコメントを入力し、トークンの既定の有効期間 90 日を変更します。有効期間のないトークンを作成するには (推奨されません)、[有効期間 (日)] ボックスを空のままにします。
[Generate](生成) をクリックします。
表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

Note

コピーしたトークンは必ず安全な場所に保存してください。コピーしたトークンは他人に見せないでください。コピーしたトークンを失った場合、それとまったく同じトークンは再生成できません。代わりに、この手順を繰り返して新しいトークンを作成する必要があります。コピーしたトークンを紛失した場合や、トークンが侵害されていると思われる場合、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 ウェアハウスの認証の詳細を 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 を使用すると、次の方法でクエリを実行できます。

クエリ文字列から。
ファイルから。
Read-Eval-Print Loop (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

出力形式を切り替えるには、値 (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 は、ログ機能を無効にします。

Share via

Databricks SQL CLI

必要条件

Databricks SQL CLI をインストールする

認証

設定ファイル

環境変数

Unix、Linux、macOS

Windows

コマンドオプション

クエリの実行元

クエリ文字列

ファイル

REPL

ログ機能

その他のリソース

フィードバック

フィードバック

その他のリソース

Share via

Databricks SQL CLI

必要条件

Databricks SQL CLI をインストールする

認証

設定ファイル

環境変数

Unix、Linux、macOS

Windows

コマンド オプション

クエリの実行元

クエリ文字列

ファイル

REPL

ログ機能

その他のリソース

フィードバック

フィードバック

その他のリソース

コマンドオプション