Databricks SQL CLI
Databricks SQLCLIこの記事では、現状のまま提供され、Databricks through customer technical support チャンネルでサポートされていない について説明します。質問や機能に関するリクエストは、 のdatabricks/databricks-sql-CLI リポジトリの[問題]GitHub ページでやり取りできます。
コマンド ライン インターフェイス Databricks SQLDatabricks SQLCLI() を使用すると、既存のSQL Databricks SQLウェアハウス に対して 、WindowsDatabricks SQL エディターやDatabricks ノートブックなどの場所からではなく ターミナルまたは コマンド プロンプトからクエリを実行できます。コマンドラインからは、候補や構文の強調表示などの生産性向上機能を利用できます。
必要条件
- 少なくとも 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 を実行します。
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 個人用アクセス トークン (PAT) がサポートされています。 Databricks PAT 認証を使用するには、個人用アクセス トークンを作成する必要があります。 このプロセスの詳細については、「 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 文字を削除し、次の操作を行います。- [
host_name]の横に、要件のウェアハウスの サーバーホスト名 の値を""文字の間に入力します。 - [
http_path] の横に、要件のウェアハウスの HTTP パス 値を""文字の間に入力します。 access_tokenの横に、要件のパーソナル アクセス トークンの値を""文字の間に入力します。
例えば：
[credentials]
host_name = "12345678901234567.8.gcp.databricks.com"
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, and macOS
- Windows
To set the environment variables for only the current terminal session, run the following commands. To set the environment variables for all terminal sessions, enter the following commands into your shell’s startup file and then restart your terminal. In the following commands, replace the value of:
DBSQLCLI_HOST_NAMEwith your warehouse’s Server hostname value from the requirements.DBSQLCLI_HTTP_PATHwith your warehouse’s HTTP path value from the requirements.DBSQLCLI_ACCESS_TOKENwith your personal access token value from the requirements.
export DBSQLCLI_HOST_NAME="12345678901234567.8.gcp.databricks.com"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
To set the environment variables for only the current Command Prompt session, run the following commands, replacing the value of:
DBSQLCLI_HOST_NAMEwith your warehouse’s Server hostname value from the requirements.DBSQLCLI_HTTP_PATHwith your warehouse’s HTTP path value from the requirements.DBSQLCLI_ACCESS_TOKENwith your personal access token value from the requirements.:
set DBSQLCLI_HOST_NAME="12345678901234567.8.gcp.databricks.com"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
To set the environment variables for all Command Prompt sessions, run the following commands and then restart your Command Prompt, replacing the value of:
DBSQLCLI_HOST_NAMEwith your warehouse’s Server hostname value from the requirements.DBSQLCLI_HTTP_PATHwith your warehouse’s HTTP path value from the requirements.DBSQLCLI_ACCESS_TOKENwith your personal access token value from the requirements.
setx DBSQLCLI_HOST_NAME "12345678901234567.8.gcp.databricks.com"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"
コマンド オプション
--hostname、 --http-path、および --access-token オプションを使用して、Databricks SQL CLI に Databricks SQL ウェアハウスの認証の詳細を提供するには、次の手順を実行します。
Databricks SQL CLI でコマンドを実行するたびに、次の操作を行います。
- 要件から
--hostnameオプションとウェアハウスの サーバーホスト名 の値を指定します。 - 要件から
--http-pathオプションとウェアハウスの HTTPパス 値を指定します。 - 要件から
--access-tokenオプションと個人用アクセス トークンの値を指定します。
例えば：
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "12345678901234567.8.gcp.databricks.com" \
--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
出力形式を切り替えるには、 --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 はログ記録を無効にします。