Databricks SQL CLI

important

Databricks SQL CLI は活発に開発されていません。

注記

この記事では、現状のまま提供され、カスタマーテクニカルサポートチャンネルを通じてDatabricksでサポートされていない Databricks SQL CLIについて説明します。質問や機能に関するリクエストは、GitHub のdatabricks/databricks-sql-CLI リポジトリのIssuesページでやり取りできます。

Databricks SQLコマンド ライン インターフェイス(Databricks SQLCLI)を使用すると、Databricks SQL エディターやDatabricks ノートブックなどの場所からではなく、ターミナルまたはWindows コマンド プロンプトから既存のDatabricks SQLのウェアハウスに対してクエリを実行できます。コマンドラインからは、候補や構文の強調表示などの生産性向上機能を利用できます。

必要条件

• 少なくとも 1 つの Databricks SQL ウェアハウス。 ウェアハウスを作成します (まだお持ちでない場合)。
• Python 3.7 以降。 Pythonがインストールされているかどうかを確認するには、ターミナルまたはコマンド プロンプトからコマンド python --versionを実行します。(一部のシステムでは、代わりに python3 を入力する必要がある場合があります。 Pythonをまだインストールしていない場合は、インストールします。
• pip は Python のパッケージインストーラです。 新しいバージョンの Python では、デフォルトで pip がインストールされます。 pipがインストールされているかどうかを確認するには、ターミナルまたはコマンド プロンプトからコマンド pip --versionを実行します。(一部のシステムでは、代わりに pip3 を入力する必要がある場合があります。 pip をまだインストールしていない場合は、インストールします。
• (オプション)venv などの Python 仮想環境 を作成および管理するためのユーティリティ。仮想環境は、正しいバージョンの Python と Databricks SQL CLI を一緒に使用していることを確認するのに役立ちます。 仮想環境の設定と使用については、この記事の範囲外です。 詳細については、「 仮想環境の作成」を参照してください。

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

要件を満たしたら、Python Packaging Index (PyPI) から Databricks SQL CLI パッケージをインストールします。pip を使用して PyPI から Databricks SQL CLI パッケージをインストールするには、次のいずれかのコマンドで pip を実行します。

Bash

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

以前にインストールしたバージョンの Databricks SQL CLI をアップグレードするには、次のいずれかのコマンドで pip を実行します。

Bash

pip install databricks-sql-cli --upgrade

# Or...

python -m pip install databricks-sql-cli --upgrade

インストールされている Databricks SQL CLI のバージョンを確認するには、次のいずれかのコマンドで pip を実行します。

Bash

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

認証

認証するには、Databricks SQL CLI にウェアハウスの 接続の詳細を提供する必要があります。具体的には、 サーバーのホスト名 と HTTP パス の値が必要です。また、Databricks SQL CLI を適切な認証資格情報で製品化する必要があります。

Databricks SQL CLI では、 Databricks 個人用アクセス トークン認証 と、Databricks SQL CLI バージョン 0.2.0 以降の OAuth ユーザー間 (U2M) 認証の 2 種類の Databricks 認証がサポートされています。 Databricks では、セキュリティと使いやすさを改善するために OAuth を使用することをお勧めします。

Databricks 個人用アクセス トークン認証を使用するには、個人用アクセス トークンを作成する必要があります。 このプロセスの詳細については、「 Databricks 個人用アクセス トークン認証」を参照してください。

OAuth U2M 認証を使用するための設定要件はありません。

この認証情報は、いくつかの方法で Databricks SQL CLI に提供できます。

• デフォルトの場所にあるdbsqlclirc設定ファイルで (または、 Databricks SQL CLIでコマンドを実行するたびに --clirc オプションを使用して代替設定ファイルを指定します)。 設定ファイルを参照してください。
• Databricks 個人用アクセス トークン認証の場合は、 DBSQLCLI_HOST_NAME、 DBSQLCLI_HTTP_PATH 、 DBSQLCLI_ACCESS_TOKEN 環境変数を設定します。 環境変数を参照してください。
• Databricks OAuth U2M 認証の場合は、DBSQLCLI_HOST_NAME 環境変数と DBSQLCLI_HTTP_PATH 環境変数を設定し、--oauth コマンド ライン オプションを指定するか、dbsqlclirc設定ファイルで auth_type = "databricks-oauth"を設定します。環境変数を参照してください。
• Databricks 個人用アクセス トークン認証の場合、Databricks SQL CLI でコマンドを実行するたびに、 --hostname、 --http-path、 --access-token の各オプションを指定します。 コマンド オプションを参照してください。
• Databricks OAuth U2M 認証の場合、--hostname と --http-path のコマンドライン オプションを指定し、dbsqlclirc設定ファイルで --oauth コマンドライン オプションまたは設定auth_type = "databricks-oauth"を指定することで、Databricks SQL CLI でコマンドを実行するたびにします。コマンド オプションを参照してください。

注記

dbsqlclirc設定ファイルは、前述の環境変数を設定するか、先行するコマンドオプションを指定するか、またはその両方を指定する場合でも、存在する必要があります。

Databricks SQL CLI を実行するたびに、次の順序で認証の詳細が検索され、最初の詳細セットが見つかったときに停止します。

1. --hostname、--http-path、--access-token または --oauth のオプション。
2. DBSQLCLI_HOST_NAME 環境変数と DBSQLCLI_HTTP_PATH 環境変数 (および Databricksパーソナルアクセストークン認証の場合は DBSQLCLI_ACCESS_TOKEN 環境変数)。
3. デフォルトの場所にある dbsqlclirc 設定ファイル (または --clirc オプションで指定される代替設定ファイル)。

設定ファイル

dbsqlclirc設定ファイルを使用して、Databricks SQL ウェアハウスの認証の詳細を Databricks SQL CLI に提供するには、次のように Databricks SQL CLI を初めて実行します。

Bash

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の横に、要件のパーソナル アクセス トークンの値を""文字の間に入力します。

注記

Databricks OAuth U2M 認証の場合は、 access_token を auth_type = "databricks-oauth"に置き換えるか、Databricks SQL CLI を呼び出すたびに --oauth コマンドライン オプションを指定する必要があります。

例えば：

[credentials]
host_name = "dbc-a1b2345c-d6e78.cloud.databricks.com"
http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
access_token = "dapi12345678901234567890123456789012"

4. dbsqlclircファイルを保存します。

または、デフォルトのロケーションで dbsqlclirc ファイルを使用する代わりに、 --clirc コマンド・オプションと代替ファイルへのパスを追加して、別のロケーションにファイルを指定することもできます。その代替ファイルの内容は、前の構文に準拠している必要があります。

環境変数

DBSQLCLI_HOST_NAME``DBSQLCLI_HTTP_PATHおよび 環境変数 (およびDatabricksパーソナルアクセストークン認証の場合はDBSQLCLI_ACCESS_TOKEN 環境変数) を使用して、Databricks SQLウェアハウスの認証詳細をDatabricks SQLCLIに提供するには、次の手順を実行します。

注記

Databricks OAuth U2M 認証の場合は、dbsqlclirc 設定ファイルで auth_type = "databricks-oauth" を設定するか、Databricks SQL CLI を呼び出すたびに --oauth コマンド オプションを指定する必要があります。

Unix, Linux, and macOS

現在のターミナル・セッションのみの環境変数を設定するには、次のコマンドを実行します。すべてのターミナル セッションの環境変数を設定するには、シェルのスタートアップ ファイルに次のコマンドを入力してから、ターミナルを再起動します。次のコマンドで、次の値を置き換えます。

• DBSQLCLI_HOST_NAME を、要件のウェアハウスの サーバーホスト名 の値に置き換えます。
• DBSQLCLI_HTTP_PATH を要件のウェアハウスの HTTPパス 値に置き換えます。
• DBSQLCLI_ACCESS_TOKEN 要件からのあなたの個人的なアクセストークンの値で。

Bash

export DBSQLCLI_HOST_NAME="dbc-a1b2345c-d6e78.cloud.databricks.com"
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 を要件の個人用アクセストークンの値に置き換えます。

Bash

set DBSQLCLI_HOST_NAME="dbc-a1b2345c-d6e78.cloud.databricks.com"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

すべてのコマンド プロンプト セッションの環境変数を設定するには、次のコマンドを実行してから、コマンド プロンプトを再起動し、次の値を置き換えます。

• DBSQLCLI_HOST_NAME を、要件のウェアハウスの サーバーホスト名 の値に置き換えます。
• DBSQLCLI_HTTP_PATH を要件のウェアハウスの HTTPパス 値に置き換えます。
• DBSQLCLI_ACCESS_TOKEN 要件からのあなたの個人的なアクセストークンの値で。

Bash

setx DBSQLCLI_HOST_NAME "dbc-a1b2345c-d6e78.cloud.databricks.com"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

コマンド オプション

--hostname、--http-path、および --access-token または --oauth オプションを使用して、Databricks SQL CLI に Databricks SQL ウェアハウスの認証の詳細を提供するには、次の手順を実行します。

Databricks SQL CLI でコマンドを実行するたびに、次の操作を行います。

• 要件から --hostname オプションとウェアハウスの サーバーホスト名 の値を指定します。

• 要件から --http-path オプションとウェアハウスの HTTPパス 値を指定します。

• Databricks 個人用アクセス トークン認証の場合は、要件から --access-token オプションと個人用アクセス トークンの値を指定します。

• Databricks OAuth U2M 認証の場合は、 --oauthを指定します。

注記

Databricks OAuth U2M 認証の場合は、dbsqlclirc 設定ファイルでauth_type = "databricks-oauth"を指定するか、Databricks SQL CLI を呼び出すたびに --oauth コマンド オプションを指定する必要があります。

例えば：

Databricks 個人用アクセス トークン認証の場合:

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Databricks OAuth U2M 認証の場合:

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "dbc-a1b2345c-d6e78.cloud.databricks.com" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--oauth

クエリソース

Databricks SQL CLI を使用すると、次の方法でクエリを実行できます。

• クエリ文字列から。
• ファイルから。
• 入力-評価-出力ループ (REPL) アプローチ。 この方法では、入力時に候補が表示されます。

クエリ文字列

クエリを文字列として実行するには、 -e オプションを使用し、その後に文字列として表されるクエリを使用します。 例えば：

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"

出力:

Bash

_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 などの値と共に使用します。たとえば、次のようにします。

Bash

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii

出力:

Bash

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 ファイルへのパスを指定します。 例えば：

Bash

dbsqlcli -e my-query.sql

サンプル my-query.sql ファイルの内容:

SQL

SELECT * FROM default.diamonds LIMIT 2;

出力:

Bash

_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 などの値と共に使用します。たとえば、次のようにします。

Bash

dbsqlcli -e my-query.sql --table-format ascii

出力:

Bash

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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) モードに入るには、次のコマンドを実行します。

Bash

dbsqlcli

また、次のコマンドを実行して、特定のデータベースをスコープとする REPL モードに入ることもできます。

Bash

dbsqlcli <database-name>

例えば：

Bash

dbsqlcli default

REPL モードを終了するには、次のコマンドを実行します。

Bash

exit

REPLモードでは、次の文字とキーを使用できます。

• 行末にはセミコロン (;) を使ってください。
• F3 を使用して、複数行モードを切り替えます。
• スペースバーを使用して、挿入ポイントに候補を表示します (候補が表示されていない場合)。
• 上矢印と下矢印を使って候補をナビゲートしてください。
• 右矢印を使って、強調表示された提案を完成させてください。

例えば：

Bash

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 はログ記録を無効にします。

追加のリソース

• Databricks SQL CLI README
• Databricks SQL ステートメント実行 API チュートリアル