Interfaccia della riga di comando sql di Databricks

  • Articolo

Nota

Questo articolo illustra l'interfaccia della riga di comando sql di Databricks, fornita così come è e non è supportata da Databricks tramite i canali di supporto tecnico del cliente. Le domande e le richieste di funzionalità possono essere comunicate tramite la pagina Problemi del repository databricks/databricks-sql-cli su GitHub.

L'interfaccia della riga di comando sql di Databricks (interfaccia della riga di comando sql di Databricks) consente di eseguire query SQL sui databricks sql warehouse esistenti dal terminale o dal prompt dei comandi di Windows anziché da posizioni come l'editor SQL di Databricks o un notebook di Azure Databricks. Dalla riga di comando si ottengono funzionalità di produttività, ad esempio suggerimenti ed evidenziazione della sintassi.

Requisiti

  • Almeno un databricks SQL warehouse. Creare un magazzino, se non ne è già disponibile uno.
  • Python 3.7 o versione successiva. Per verificare se Python è installato, eseguire il comando python --version dal terminale o dal prompt dei comandi. In alcuni sistemi potrebbe essere necessario immettere python3 invece. Installare Python, se non è già installato.
  • pip, il programma di installazione del pacchetto per Python. Le versioni più recenti di Python vengono installate pip per impostazione predefinita. Per verificare se è pip stato installato, eseguire il comando pip --version dal terminale o dal prompt dei comandi. In alcuni sistemi potrebbe essere necessario immettere pip3 invece. Installare pip, se non è già installato.
  • (Facoltativo) Utilità per la creazione e la gestione di ambienti virtuali Python, ad esempio venv. Gli ambienti virtuali consentono di assicurarsi di usare insieme le versioni corrette di Python e l'interfaccia della riga di comando SQL di Databricks. La configurazione e l'uso di ambienti virtuali non rientra nell'ambito di questo articolo. Per altre informazioni, vedere Creazione di ambienti virtuali.

Installare l'interfaccia della riga di comando sql di Databricks

Dopo aver soddisfatto i requisiti, installare il pacchetto dell'interfaccia della riga di comando sql di Databricks da Python Packaging Index (PyPI). È possibile usare pip per installare il pacchetto dell'interfaccia della riga di comando sql di Databricks da PyPI eseguendo pip con uno dei comandi seguenti.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Per aggiornare una versione installata in precedenza dell'interfaccia della riga di comando sql di Databricks, eseguire pip con uno dei comandi seguenti.

pip install databricks-sql-cli --upgrade

# Or...

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

Per controllare la versione installata dell'interfaccia della riga di comando sql di Databricks, eseguire pip con uno dei comandi seguenti.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autenticazione

Per eseguire l'autenticazione, è necessario fornire all'interfaccia della riga di comando sql di Databricks i dettagli di connessione del warehouse. In particolare, sono necessari i valori nome host server e percorso HTTP. È anche necessario usare l'interfaccia della riga di comando sql di Databricks con le credenziali di autenticazione appropriate.

L'interfaccia della riga di comando di Databricks SQL supporta l'autenticazione del token di accesso personale di Databricks. I token di Microsoft Entra ID (in precedenza Azure Active Directory) non sono supportati.

Per usare l'autenticazione del token di accesso personale di Azure Databricks, creare un token di accesso personale come indicato di seguito:

  1. Nell'area di lavoro di Azure Databricks fare clic sul nome utente di Azure Databricks nella barra superiore e quindi selezionare Impostazioni dall'elenco a discesa.
  2. Fare clic su Sviluppatore.
  3. Accanto a Token di accesso fare clic su Gestisci.
  4. Fare clic su Genera nuovo token.
  5. (Facoltativo) Immettere un commento che consente di identificare questo token in futuro e modificare la durata predefinita del token di 90 giorni. Per creare un token senza durata (scelta non consigliata), lasciare vuota la casella Durata (giorni) (vuota).
  6. Fare clic su Genera.
  7. Copiare il token visualizzato in un percorso sicuro e quindi fare clic su Fine.

Nota

Assicurarsi di salvare il token copiato in un percorso sicuro. Non condividere il token copiato con altri utenti. Se si perde il token copiato, non è possibile rigenerare lo stesso token esatto. È invece necessario ripetere questa procedura per creare un nuovo token. Se si perde il token copiato o si ritiene che il token sia stato compromesso, Databricks consiglia vivamente di eliminare immediatamente il token dall'area di lavoro facendo clic sull'icona del cestino (Revoca) accanto al token nella pagina Token di accesso.

Se non è possibile creare o usare token nell'area di lavoro, questo potrebbe essere dovuto al fatto che l'amministratore dell'area di lavoro ha disabilitato i token o non ha concesso l'autorizzazione per creare o usare token. Vedere l'amministratore dell'area di lavoro o quanto segue:

È possibile fornire queste informazioni di autenticazione all'interfaccia della riga di comando sql di Databricks in diversi modi:

  • dbsqlclirc Nel file delle impostazioni nel percorso predefinito (o specificando un file di impostazioni alternativo tramite l'opzione --clirc ogni volta che si esegue un comando con l'interfaccia della riga di comando sql di Databricks). Vedere Impostazioni file.
  • Impostando le DBSQLCLI_HOST_NAMEvariabili di DBSQLCLI_HTTP_PATH ambiente e DBSQLCLI_ACCESS_TOKEN . Vedere Variabili di ambiente.
  • Specificando le --hostnameopzioni , --http-pathe --access-token ogni volta che si esegue un comando con l'interfaccia della riga di comando sql di Databricks. Vedere Opzioni di comando.

Nota

Il dbsqlclirc file di impostazioni deve essere presente, anche se si impostano le variabili di ambiente precedenti o si specificano le opzioni di comando precedenti o entrambe.

Ogni volta che si esegue l'interfaccia della riga di comando di Databricks SQL, cerca i dettagli di autenticazione nell'ordine seguente e si arresta quando trova il primo set di dettagli:

  1. Opzioni --hostname, --http-pathe --access-token .
  2. Variabili DBSQLCLI_HOST_NAMEdi ambiente e DBSQLCLI_HTTP_PATHDBSQLCLI_ACCESS_TOKEN .
  3. Il dbsqlclirc file delle impostazioni nel percorso predefinito (o un file di impostazioni alternativo specificato dall'opzione --clirc ).

File di impostazioni

Per usare il dbsqlclirc file di impostazioni per fornire all'interfaccia della riga di comando sql di Databricks i dettagli di autenticazione per databricks SQL Warehouse, eseguire l'interfaccia della riga di comando sql di Databricks per la prima volta, come indicato di seguito:

dbsqlcli

L'interfaccia della riga di comando sql di Databricks crea automaticamente un file di impostazioni in ~/.dbsqlcli/dbsqlclirc Unix, Linux e macOS e in %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc o %USERPROFILE%\.dbsqlcli\dbsqlclirc in Windows. Per personalizzare questo file:

  1. Usare un editor di testo per aprire e modificare il dbsqlclirc file.

  2. Scorrere fino alla sezione seguente:

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

  3. Rimuovere i quattro # caratteri e:

    1. Accanto a host_nameimmettere il valore nome host del server del warehouse in base ai requisiti tra i "" caratteri.
    2. Accanto a http_pathimmettere il valore del percorso HTTP del warehouse dai requisiti tra i "" caratteri.
    3. Accanto a access_tokenimmettere il valore del token di accesso personale dai requisiti tra i "" caratteri.

    Ad esempio:

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

  4. Salvare il file dbsqlclirc.

In alternativa, anziché usare il dbsqlclirc file nel percorso predefinito, è possibile specificare un file in un percorso diverso aggiungendo l'opzione --clirc di comando e il percorso al file alternativo. Il contenuto del file alternativo deve essere conforme alla sintassi precedente.

Variabili di ambiente

Per usare le DBSQLCLI_HOST_NAMEvariabili di ambiente , DBSQLCLI_HTTP_PATHe DBSQLCLI_ACCESS_TOKEN per fornire all'interfaccia della riga di comando sql di Databricks i dettagli di autenticazione per Databricks SQL Warehouse, eseguire le operazioni seguenti:

Unix, linux e macos

Per impostare le variabili di ambiente solo per la sessione del terminale corrente, eseguire i comandi seguenti. Per impostare le variabili di ambiente per tutte le sessioni del terminale, immettere i comandi seguenti nel file di avvio della shell e quindi riavviare il terminale. Nei comandi seguenti sostituire il valore di :

  • DBSQLCLI_HOST_NAMEcon il valore nome host del server del magazzino in base ai requisiti.
  • DBSQLCLI_HTTP_PATHcon il valore del percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale dai requisiti.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Per impostare le variabili di ambiente solo per la sessione del prompt dei comandi corrente, eseguire i comandi seguenti, sostituendo il valore di :

  • DBSQLCLI_HOST_NAMEcon il valore nome host del server del magazzino in base ai requisiti.
  • DBSQLCLI_HTTP_PATHcon il valore del percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale dai requisiti:with your personal access token value from the requirements.:
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Per impostare le variabili di ambiente per tutte le sessioni del prompt dei comandi, eseguire i comandi seguenti e quindi riavviare il prompt dei comandi, sostituendo il valore di :

  • DBSQLCLI_HOST_NAMEcon il valore nome host del server del magazzino in base ai requisiti.
  • DBSQLCLI_HTTP_PATHcon il valore del percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale dai requisiti.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opzioni di comando

Per usare le --hostnameopzioni , --http-pathe --access-token per fornire all'interfaccia della riga di comando sql di Databricks i dettagli di autenticazione per Databricks SQL Warehouse, eseguire le operazioni seguenti:

Eseguire le operazioni seguenti ogni volta che si esegue un comando con l'interfaccia della riga di comando sql di Databricks:

  • Specificare l'opzione --hostname e il valore nome host del server del magazzino in base ai requisiti.
  • Specificare l'opzione e il --http-path valore del percorso HTTP del warehouse in base ai requisiti.
  • Specificare l'opzione e il --access-token valore del token di accesso personale dai requisiti.

Ad esempio:

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

Origini di query

L'interfaccia della riga di comando di Databricks SQL consente di eseguire query nei modi seguenti:

  • Da una stringa di query.
  • Da un file.
  • In un approccio REPL (Read-Evaluate-Print Loop). Questo approccio fornisce suggerimenti durante la digitazione.

Stringa di query

Per eseguire una query come stringa, usare l'opzione -e seguita dalla query, rappresentata come stringa. Ad esempio:

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

Output:

_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

Per cambiare i formati di output, usare l'opzione --table-format insieme a un valore come ascii per il formato di tabella ASCII, ad esempio:

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

Output:

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

Per un elenco dei valori di formato di output disponibili, vedere i commenti per l'impostazione table_format nel dbsqlclirc file.

file

Per eseguire un file contenente SQL, usare l'opzione -e seguita dal percorso di un .sql file. Ad esempio:

dbsqlcli -e my-query.sql

Contenuto del file di esempio my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

Output:

_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

Per cambiare i formati di output, usare l'opzione --table-format insieme a un valore come ascii per il formato di tabella ASCII, ad esempio:

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

Output:

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

Per un elenco dei valori di formato di output disponibili, vedere i commenti per l'impostazione table_format nel dbsqlclirc file.

REPL

Per immettere la modalità REPL (Read-Evaluate-Print Loop) con ambito nel database predefinito, eseguire il comando seguente:

dbsqlcli

È anche possibile immettere la modalità REPL con ambito in un database specifico, eseguendo il comando seguente:

dbsqlcli <database-name>

Ad esempio:

dbsqlcli default

Per uscire dalla modalità REPL, eseguire il comando seguente:

exit

In modalità REPL è possibile usare i caratteri e le chiavi seguenti:

  • Usare il punto e virgola (;) per terminare una riga.
  • Usare F3 per attivare o disattivare la modalità multilinea.
  • Usare la barra spaziatrice per visualizzare i suggerimenti nel punto di inserimento, se i suggerimenti non sono già visualizzati.
  • Usare le frecce su e giù per spostarsi nei suggerimenti.
  • Usare la freccia destra per completare il suggerimento evidenziato.

Ad esempio:

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

Registrazione

L'interfaccia della riga di comando di Databricks SQL registra i messaggi nel file ~/.dbsqlcli/app.log per impostazione predefinita. Per modificare il nome o il percorso del file, modificare il valore dell'impostazione log_file nel dbsqlclircfile di impostazioni.

Per impostazione predefinita, i messaggi vengono registrati a INFO livello di log e inferiori. Per modificare questo livello di log, modificare il valore dell'impostazione log_level nel dbsqlclirc file delle impostazioni. I valori a livello di log disponibili includono CRITICAL, ERRORWARNING, INFO, e DEBUG vengono valutati in tale ordine. NONE disabilita la registrazione.

Risorse aggiuntive