次の方法で共有

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 個人用アクセス トークン認証がサポートされています。 Microsoft Entra ID トークンはサポートされていません。

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

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

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 を実行するたびに、次の順序で認証の詳細が検索され、最初の詳細セットが見つかると停止します。

  1. --hostname、--http-path、および --access-token の各オプション。
  2. DBSQLCLI_HOST_NAME、DBSQLCLI_HTTP_PATH、および DBSQLCLI_ACCESS_TOKEN の各環境変数。
  3. 既定の場所にある 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 に設定ファイルが自動的に作成されます。 このファイルをカスタマイズするには、次のようにします。

  1. テキスト エディターを使用し、dbsqlclirc ファイルを開いて編集します。

  2. 次のセクションまでスクロールします。

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

  3. 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"

  4. 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 は、ログ機能を無効にします。

その他のリソース