Condividi tramite

Databricks SQL CLI

  • 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 warehouse se non ne esiste già 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, consultare Creare ambienti virtuali.

Installare l'interfaccia della riga di comando di Databricks SQL

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 non sono supportati.

Per usare un token di accesso personale di Azure Databricks, creare un token di accesso personale come segue:

  1. Nell'area di lavoro di Azure Databricks, fare clic sul nome utente di Azure Databricks nella barra superiore, quindi selezionare Impostazioni nell'elenco a discesa.
  2. Fare clic su Sviluppatore.
  3. Accanto a Token di accesso fare clic su Gestisci.
  4. Fare clic su Generare nuovi 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).
  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 esatto token. È 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 un token di accesso personale 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. Consultare l'amministratore dell'area di lavoro o i seguenti argomenti:

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

  • Nel file delle impostazioni dbsqlclirc 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). Selezionare File Impostazioni.
  • Impostando le variabili di ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN. Consultare variabili di ambiente.
  • Specificando le opzioni --hostname, --http-path e --access-token ogni volta che si esegue un comando con l'interfaccia della riga di comando SQL di Databricks. Consultare Opzioni di comando.

Nota

Il file dbsqlclirc 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. Le opzioni --hostname, --http-path e --access-token.
  2. Le variabili di ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e DBSQLCLI_ACCESS_TOKEN.
  3. Il file dbsqlclirc delle impostazioni nel percorso predefinito (o un file di impostazioni alternativo specificato dall'opzione --clirc).

File di impostazioni

Per usare il file dbsqlclirc 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 file dbsqlclirc.

  2. Scorrere fino alla sezione seguente:

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

  3. Rimuovere i quattro caratteri # e:

    1. Accanto a host_name, immettere il valore nome host del server del warehouse in base ai requisiti tra i caratteri "".
    2. Accanto a http_path, immettere il valore percorso HTTP del warehouse in base ai requisiti tra i caratteri "".
    3. Accanto a access_token immettere 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 file dbsqlclirc 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 variabili di ambiente DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH e 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_NAME con il valore nome host del server del warehouse in base ai requisiti.
  • DBSQLCLI_HTTP_PATH con il valore percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale in base ai requisiti.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Finestre

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_NAME con il valore nome host del server del warehouse in base ai requisiti.
  • DBSQLCLI_HTTP_PATH con il valore percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale in base ai requisiti.:
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, quindi riavviare il prompt dei comandi sostituendo il valore di:

  • DBSQLCLI_HOST_NAME con il valore nome host del server del warehouse in base ai requisiti.
  • DBSQLCLI_HTTP_PATH con il valore percorso HTTP del warehouse in base ai requisiti.
  • DBSQLCLI_ACCESS_TOKEN con il valore del token di accesso personale in base ai 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 opzioni --hostname, --http-path e --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 warehouse in base ai requisiti.
  • Specificare l’opzione --http-path e il valore percorso HTTP del warehouse in base ai requisiti.
  • Specificare l'opzione --access-token e il valore del token di accesso personale in base ai 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 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, consultare i commenti per l'impostazione table_format nel file dbsqlclirc.

file

Per eseguire un file contenente SQL, usare l'opzione -e seguita dal percorso di un file .sql. 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, consultare i commenti per l'impostazione table_format nel file dbsqlclirc.

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 file di impostazioni dbsqlclirc.

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

Risorse aggiuntive