Databricks SQL CLI

注

この記事では、現状のまま提供され、顧客テクニカル サポート チャンネルを通じて Databricks でサポートされていない Databricks SQL CLI について説明します。 質問と機能要求は、GitHub のデータブリック /データブリック-sql-cli リポジトリの [問題 ] ページを通じて伝達できます。

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

要件

  • 少なくとも 1 つの 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 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 個人用アクセストークン認証と、Databricks SQL CLI バージョン 0.2.0 以降の場合は OAuth ユーザー対マシン (U2M) 認証の 2 種類の Databricks 認証 がサポートされています。

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

  1. Databricks ワークスペースで、上部のバーにある Databricks ユーザー名をクリックし、ドロップダウンから[設定]を選択します。

  2. [ 開発者] をクリックします。

  3. [アクセストークン] の横にある [管理] をクリックします。

  4. [ 新しいトークンの生成] をクリックします。

  5. （任意）今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには（非推奨）、[有効期間 (日) ] ボックスを空白のままにしてください。

  6. [生成] をクリックします。

  7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

注

コピーしたトークンは、必ず安全な場所に保存してください。 コピーしたトークンを他のユーザーと共有しないでください。 コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。 代わりに、この手順を繰り返して新しいトークンを作成する必要があります。 コピーしたトークンを紛失した場合、またはトークンが侵害されたと思われる場合は、アクセストークン ページでトークンの横にあるごみ箱 (取り消し) アイコンをクリックして、ワークスペースからそのトークンをすぐに削除することを強くお勧めします。

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。

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 認証の場合、Databricks SQL CLI でコマンドを実行するたびに、--hostname と --http-path のコマンドライン オプションを指定し、dbsqlclirc設定ファイルで --oauth コマンドライン オプションを指定するか、auth_type = "databricks-oauth"を設定します。コマンド・オプションを参照してください。

注

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 SQLCLI に提供するには、次のように 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] の横に、 "" 文字の間の要件から個人用アクセストークンの値を入力します。

      注

      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 CLI に Databricks SQL ウェアハウスの認証の詳細を提供するには、次の操作を行います。

注

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

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

  • DBSQLCLI_HOST_NAME 要件のウェアハウスの サーバーホスト名 の値を使用します。

  • DBSQLCLI_HTTP_PATH を要件のウェアハウスの HTTP パス 値に置き換えます。

  • DBSQLCLI_ACCESS_TOKEN 要件からの個人用アクセストークン値を使用します。

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

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

  • DBSQLCLI_HOST_NAME 要件のウェアハウスの サーバーホスト名 の値を使用します。

  • DBSQLCLI_HTTP_PATH を要件のウェアハウスの HTTP パス 値に置き換えます。

  • DBSQLCLI_ACCESS_TOKEN 要件の個人用アクセストークン値を使用します。

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 要件からの個人用アクセストークン値を使用します。

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 個人用アクセストークン認証の場合:

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 認証の場合:

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

クエリー sources

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

出力形式を切り替えるには、 --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) モードに入るには、次のコマンドを実行します。

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