Rozhraní příkazového řádku SQL Databricks

Rozhraní příkazového řádku SQL Databricks (Databricks SQL CLI) umožňuje spouštět dotazy SQL ve stávajících skladech Sql Databricks z terminálu nebo příkazového řádku Windows místo z umístění, jako je editor SQL Databricks nebo poznámkový blok Azure Databricks. Z příkazového řádku získáte funkce produktivity, jako jsou návrhy a zvýraznění syntaxe.

Požadavky

• Alespoň jeden Databricks SQL Warehouse. Vytvořte sklad, pokud ho ještě nemáte.
• Python 3.7 nebo vyšší Pokud chcete zkontrolovat, jestli máte nainstalovaný Python, spusťte příkaz python --version z terminálu nebo příkazového řádku. (V některých systémech možná budete muset místo toho zadat python3 .) Nainstalujte Python, pokud ho ještě nemáte nainstalovaný.
• pip, instalační program balíčku pro Python. Ve výchozím nastavení se nainstalují pip novější verze Pythonu. Pokud chcete zkontrolovat, jestli jste nainstalovali pip , spusťte příkaz pip --version z terminálu nebo příkazového řádku. (V některých systémech možná budete muset místo toho zadat pip3 .) Nainstalujte pip, pokud ho ještě nemáte nainstalovaný.
• (Volitelné) Nástroj pro vytváření a správu virtuálních prostředí Pythonu, jako je například venv. Virtuální prostředí pomáhají zajistit, abyste společně používali správné verze Pythonu a rozhraní příkazového řádku SQL Databricks. Nastavení a používání virtuálních prostředí je mimo rozsah tohoto článku. Další informace naleznete v tématu Vytváření virtuálních prostředí.

Instalace rozhraní příkazového řádku SQL Databricks

Po splnění požadavků nainstalujte balíček Rozhraní příkazového řádku SQL Databricks z indexu balíčků Pythonu (PyPI). Balíček Rozhraní příkazového řádku SQL Databricks můžete pip nainstalovat z PyPI spuštěním pip jednoho z následujících příkazů.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Pokud chcete upgradovat dříve nainstalovanou verzi rozhraní příkazového řádku SQL Databricks, spusťte pip jeden z následujících příkazů.

pip install databricks-sql-cli --upgrade

# Or...

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

Pokud chcete zkontrolovat nainstalovanou verzi rozhraní příkazového řádku SQL Databricks, spusťte pip jedním z následujících příkazů.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Ověřování

Pokud chcete provést ověření, musíte zadat rozhraní příkazového řádku SQL Databricks s podrobnostmi o připojení vašeho skladu. Konkrétně potřebujete hodnoty názvu hostitele serveru a cesty HTTP. Musíte také produktovat Rozhraní příkazového řádku SQL Databricks se správnými přihlašovacími údaji pro ověření.

Rozhraní příkazového řádku SQL Databricks podporuje tokeny PAT (Databricks). Pokud chcete použít ověřování PAT v Azure Databricks, musíte vytvořit osobní přístupový token. Podrobnosti o tomto procesu najdete v tématu Ověřování tokenů pat v Azure Databricks.

Tokeny ID Microsoft Entra se nepodporují.

Tyto ověřovací informace můžete zadat do Rozhraní příkazového řádku SQL Databricks několika způsoby:

• dbsqlclirc V souboru nastavení ve výchozím umístění (nebo zadáním alternativního souboru nastavení prostřednictvím --clirc možnosti pokaždé, když spustíte příkaz pomocí Rozhraní příkazového řádku SQL Databricks). Viz Soubor Nastavení.
• Nastavením proměnných DBSQLCLI_HOST_NAMEDBSQLCLI_HTTP_PATH prostředí a DBSQLCLI_ACCESS_TOKEN a Viz proměnné prostředí.
• --hostnameZadáním parametrů a --http-path--access-token možností při každém spuštění příkazu pomocí Rozhraní příkazového řádku SQL Databricks. Viz možnosti příkazu.

Pokaždé, když spustíte Rozhraní příkazového řádku SQL Databricks, vyhledá podrobnosti o ověřování v následujícím pořadí a zastaví se, když najde první sadu podrobností:

1. The --hostname, --http-pathand --access-token options.
2. DBSQLCLI_HOST_NAME Proměnné DBSQLCLI_HTTP_PATHa DBSQLCLI_ACCESS_TOKEN proměnné prostředí.
3. Soubor dbsqlclirc nastavení ve výchozím umístění (nebo alternativní soubor nastavení určený možností --clirc ).

Soubor nastavení

Pokud chcete použít dbsqlclirc soubor nastavení k poskytnutí rozhraní příkazového řádku SQL Databricks s podrobnostmi o ověřování pro databricks SQL Warehouse, spusťte nejprve rozhraní příkazového řádku SQL Databricks následujícím způsobem:

dbsqlcli

Rozhraní příkazového řádku SQL Databricks pro vás vytvoří soubor nastavení v ~/.dbsqlcli/dbsqlclirc systémech Unix, Linux a macOS a ve %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc Windows.%USERPROFILE%\.dbsqlcli\dbsqlclirc Přizpůsobení tohoto souboru:

1. K otevření a úpravě dbsqlclirc souboru použijte textový editor.

2. Posuňte se k následující části:

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

3. Odeberte čtyři # znaky a:

   1. Vedle položky host_namezadejte hodnotu názvu hostitele serveru vašeho skladu z požadavků mezi "" znaky.
   2. Vedle položky http_pathzadejte hodnotu cesty HTTP vašeho skladu z požadavků mezi "" znaky.
   3. Vedle položky access_tokenzadejte hodnotu osobního přístupového tokenu z požadavků mezi "" znaky.

   Příklad:

   [credentials]
   host_name = "adb-12345678901234567.8.azuredatabricks.net"
   http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a"
   access_token = "dapi12345678901234567890123456789012"
   

4. Uložte soubor dbsqlclirc.

Případně můžete místo použití dbsqlclirc souboru ve výchozím umístění zadat soubor v jiném umístění přidáním --clirc možnosti příkazu a cesty k alternativnímu souboru. Obsah alternativního souboru musí odpovídat předchozí syntaxi.

Proměnné prostředí

Pokud chcete použít DBSQLCLI_HOST_NAMEproměnné prostředí a < DBSQLCLI_HTTP_PATHa0/> DBSQLCLI_ACCESS_TOKEN , které poskytují rozhraní příkazového řádku SQL Databricks s podrobnostmi o ověřování pro službu Databricks SQL Warehouse, postupujte takto:

Unix, Linux a macOS

Pokud chcete nastavit proměnné prostředí pouze pro aktuální relaci terminálu, spusťte následující příkazy. Pokud chcete nastavit proměnné prostředí pro všechny relace terminálu, zadejte do spouštěcího souboru prostředí následující příkazy a restartujte terminál. V následujících příkazech nahraďte hodnotu:

• DBSQLCLI_HOST_NAMEs hodnotou názvu hostitele serveru vašeho skladu z požadavků.
• DBSQLCLI_HTTP_PATHs hodnotou cesty HTTP vašeho skladu z požadavků.
• DBSQLCLI_ACCESS_TOKEN s hodnotou vašeho osobního přístupového tokenu z požadavků.

export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Pokud chcete nastavit proměnné prostředí pouze pro aktuální relaci příkazového řádku, spusťte následující příkazy a nahraďte hodnotu:

• DBSQLCLI_HOST_NAMEs hodnotou názvu hostitele serveru vašeho skladu z požadavků.
• DBSQLCLI_HTTP_PATHs hodnotou cesty HTTP vašeho skladu z požadavků.
• DBSQLCLI_ACCESS_TOKEN s hodnotou vašeho osobního přístupového tokenu z požadavků:

set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Pokud chcete nastavit proměnné prostředí pro všechny relace příkazového řádku, spusťte následující příkazy a restartujte příkazový řádek a nahraďte hodnotu:

• DBSQLCLI_HOST_NAMEs hodnotou názvu hostitele serveru vašeho skladu z požadavků.
• DBSQLCLI_HTTP_PATHs hodnotou cesty HTTP vašeho skladu z požadavků.
• DBSQLCLI_ACCESS_TOKEN s hodnotou vašeho osobního přístupového tokenu z požadavků.

setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Možnosti příkazů

Pokud chcete použít --hostname, --http-patha --access-token možnosti poskytnout Databricks SQL CLI s podrobnostmi o ověřování pro Databricks SQL Warehouse, postupujte takto:

Při každém spuštění příkazu pomocí rozhraní příkazového řádku SQL Databricks postupujte následovně:

• --hostname Zadejte možnost a hodnotu názvu hostitele serveru vašeho skladu z požadavků.
• --http-path Zadejte možnost a hodnotu cesty HTTP vašeho skladu z požadavků.
• --access-token Zadejte možnost a hodnotu vašeho osobního přístupového tokenu z požadavků.

Příklad:

dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"

Zdroje dotazů

Rozhraní příkazového řádku SQL Databricks umožňuje spouštět dotazy následujícími způsoby:

• Z řetězce dotazu.
• Ze souboru.
• V přístupu repl (read-evaluate-print loop). Tento přístup nabízí návrhy při psaní.

Řetězec dotazu

Pokud chcete spustit dotaz jako řetězec, použijte -e možnost následovanou dotazem reprezentovanou jako řetězec. Příklad:

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

Výstup:

_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

Pokud chcete přepnout výstupní formáty, použijte --table-format možnost spolu s hodnotou, například ascii pro formát tabulky ASCII, například:

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

Výstup:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Seznam dostupných hodnot výstupního formátu najdete v komentářích k table_format nastavení v dbsqlclirc souboru.

Soubor

Pokud chcete spustit soubor, který obsahuje SQL, použijte -e možnost následovanou cestou k .sql souboru. Příklad:

dbsqlcli -e my-query.sql

Obsah ukázkového my-query.sql souboru:

SELECT * FROM default.diamonds LIMIT 2;

Výstup:

_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

Pokud chcete přepnout výstupní formáty, použijte --table-format možnost spolu s hodnotou, například ascii pro formát tabulky ASCII, například:

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

Výstup:

+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+

Seznam dostupných hodnot výstupního formátu najdete v komentářích k table_format nastavení v dbsqlclirc souboru.

REPL

Pokud chcete zadat režim repl (read-evaluate-print), který je vymezený na výchozí databázi, spusťte následující příkaz:

dbsqlcli

Můžete také zadat režim REPL vymezený na konkrétní databázi spuštěním následujícího příkazu:

dbsqlcli <database-name>

Příklad:

dbsqlcli default

Pokud chcete ukončit režim REPL, spusťte následující příkaz:

exit

V režimu REPL můžete použít následující znaky a klíče:

• Pomocí středníku (;) ukončete čáru.
• K přepnutí víceřádkového režimu použijte klávesu F3 .
• Pokud se návrhy nezobrazují, použijte mezerník k zobrazení návrhů na pozici kurzoru.
• Pomocí šipek nahoru a dolů můžete procházet návrhy.
• Pomocí šipky doprava dokončete zvýrazněný návrh.

Příklad:

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

Protokolování

Rozhraní příkazového řádku SQL Databricks protokoluje zprávy do souboru ~/.dbsqlcli/app.log ve výchozím nastavení. Chcete-li změnit název nebo umístění tohoto souboru, změňte hodnotu log_file nastavení v dbsqlclircsouboru nastavení.

Ve výchozím nastavení se zprávy protokolují na INFO úrovni protokolu a níže. Pokud chcete změnit tuto úroveň protokolu, změňte hodnotu log_level nastavení v dbsqlclirc souboru nastavení. Mezi dostupné hodnoty úrovně protokolu patří CRITICAL, , ERRORWARNING, INFOa DEBUG jsou vyhodnoceny v daném pořadí. NONE zakáže protokolování.

Další materiály

• ReadME rozhraní příkazového řádku SQL Databricks
• Kurz rozhraní API pro spouštění příkazů SQL pro Databricks