Databricks SQL CLI

Med Databricks SQL-kommandoradsgränssnittet (Databricks SQL CLI) kan du köra SQL-frågor på dina befintliga Databricks SQL-lager från terminalen eller Windows-kommandotolken i stället för från platser som Databricks SQL-redigeraren eller en Azure Databricks-notebook-fil. Från kommandoraden får du produktivitetsfunktioner som förslag och syntaxmarkering.

Krav

• Minst ett Databricks SQL-lager. Skapa ett lager, om du inte redan har ett.
• Python 3.7 eller senare. Om du vill kontrollera om du har Python installerat kör du kommandot python --version från terminalen eller kommandotolken. (På vissa system kan du behöva ange i python3 stället.) Installera Python om du inte redan har installerat det.
• pip, paketinstallationsprogrammet för Python. Nyare versioner av Python installerar pip som standard. För att kontrollera om du har pip installerat, kör kommandot pip --version från terminalen eller kommandotolken. (På vissa system kan du behöva ange i pip3 stället.) Installera pip om du inte redan har installerat det.
• (Valfritt) Ett verktyg för att skapa och hantera virtuella Python-miljöer, till exempel venv. Virtuella miljöer hjälper dig att se till att du använder rätt versioner av Python och Databricks SQL CLI tillsammans. Att konfigurera och använda virtuella miljöer ligger utanför omfånget för den här artikeln. Mer information finns i Skapa virtuella miljöer.

Installera Databricks SQL CLI

När du uppfyller kraven installerar du Databricks SQL CLI-paketet från Python Packaging Index (PyPI). Du kan använda pip för att installera Databricks SQL CLI-paketet från PyPI genom att köra pip med något av följande kommandon.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

För att uppgradera en tidigare installerad version av Databricks SQL CLI, kör pip med något av följande kommandon.

pip install databricks-sql-cli --upgrade

# Or...

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

För att kontrollera den installerade versionen av Databricks SQL CLI kör du pip med något av följande kommandon.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Autentisering

För att autentisera måste du ange databricks SQL CLI med information om ditt lagers anslutning. Mer specifikt behöver du värden för servervärdnamn och HTTP-sökväg . Du måste också tillhandahålla Databricks SQL CLI med korrekta autentiseringsuppgifter.

Databricks SQL CLI stöder Databricks personliga åtkomsttoken (PAT). Om du vill använda Azure Databricks PAT-autentisering måste du skapa en personlig åtkomsttoken. Mer information om den här processen finns i Autentisera med personliga åtkomsttoken för Azure Databricks (äldre).

Microsoft Entra-ID-token stöds inte.

Du kan ange den här autentiseringsinformationen för Databricks SQL CLI på flera sätt:

• I inställningsfilen dbsqlclirc på dess standardplats (eller genom att ange en alternativ inställningsfil via --clirc alternativet varje gång du kör ett kommando med Databricks SQL CLI). Se Inställningsfil.
• Genom att ange DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH och DBSQLCLI_ACCESS_TOKEN miljövariablerna. Se Miljövariabler.
• Genom att ange alternativen --hostname, --http-path och --access-token varje gång du kör ett kommando med Databricks SQL CLI. Se Kommandoalternativ.

När du kör Databricks SQL CLI letar det efter autentiseringsinformation i följande ordning och stoppas när den hittar den första uppsättningen med information:

1. Alternativen --hostname, --http-pathoch --access-token .
2. Miljövariablerna DBSQLCLI_HOST_NAMEoch DBSQLCLI_HTTP_PATHDBSQLCLI_ACCESS_TOKEN .
3. Inställningsfilen dbsqlclirc på dess standardplats (eller en alternativ inställningsfil som anges av --clirc alternativet).

Inställningsfil

Om du vill använda dbsqlclirc inställningsfilen för att tillhandahålla Databricks SQL CLI med autentiseringsinformation för ditt Databricks SQL-lager kör du Databricks SQL CLI för första gången på följande sätt:

dbsqlcli

Databricks SQL CLI skapar en inställningsfil åt dig, på ~/.dbsqlcli/dbsqlclirc Unix, Linux och macOS, och på %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc eller %USERPROFILE%\.dbsqlcli\dbsqlclirc i Windows. Så här anpassar du den här filen:

1. Använd en textredigerare för att öppna och redigera dbsqlclirc filen.

2. Bläddra till följande avsnitt:

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

3. Ta bort de fyra # tecknen och:

   1. Bredvid host_name skriver du in serverns värdnamn som anges i kraven mellan tecknen "".
   2. Bredvid http_pathanger du ditt lagers HTTP-sökvägsvärde från kraven mellan "" tecknen.
   3. Bredvid access_token anger du värdet på din personliga åtkomsttoken enligt kraven mellan "" tecknen.

   Till exempel:

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

4. Spara filen dbsqlclirc.

I stället för att använda dbsqlclirc filen på dess standardplats kan du ange en fil på en annan plats genom att lägga till kommandoalternativet --clirc och sökvägen till den alternativa filen. Den alternativa filens innehåll måste överensstämma med föregående syntax.

Miljövariabler

Om du vill använda DBSQLCLI_HOST_NAMEmiljövariablerna , DBSQLCLI_HTTP_PATHoch DBSQLCLI_ACCESS_TOKEN för att tillhandahålla Databricks SQL CLI med autentiseringsinformation för ditt Databricks SQL-lager gör du följande:

Unix, Linux och macOS

Om du bara vill ange miljövariablerna för den aktuella terminalsessionen kör du följande kommandon. Ange miljövariablerna för alla terminalsessioner genom att ange följande kommandon i gränssnittets startfil och sedan starta om terminalen. I följande kommandon ersätter du värdet för:

• DBSQLCLI_HOST_NAME med ditt lagers servervärdnamn från kravens värde.
• DBSQLCLI_HTTP_PATH med ditt lagers HTTP-sökvägsvärde från kraven.
• DBSQLCLI_ACCESS_TOKEN med värdet på din personliga åtkomsttoken enligt kraven.

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

Windows

Om du bara vill ange miljövariablerna för den aktuella kommandotolksession kör du följande kommandon och ersätter värdet för:

• DBSQLCLI_HOST_NAME med ditt lagers servervärdnamn från kravens värde.
• DBSQLCLI_HTTP_PATH med ditt lagers HTTP-sökvägsvärde från kraven.
• DBSQLCLI_ACCESS_TOKEN med ditt personliga åtkomsttokenvärde enligt kraven.

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

Om du vill ange miljövariablerna för alla kommandotolkssessioner kör du följande kommandon och startar sedan om kommandotolken och ersätter värdet för:

• DBSQLCLI_HOST_NAME med ditt lagers servervärdnamn från kravens värde.
• DBSQLCLI_HTTP_PATH med ditt lagers HTTP-sökvägsvärde från kraven.
• DBSQLCLI_ACCESS_TOKEN med värdet på din personliga åtkomsttoken enligt kraven.

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

Kommandoalternativ

Om du vill använda --hostnamealternativen , --http-pathoch --access-token för att tillhandahålla Databricks SQL CLI med autentiseringsinformation för ditt Databricks SQL-lager gör du följande:

Gör följande varje gång du kör ett kommando med Databricks SQL CLI:

• Ange alternativet --hostname och lagrets servervärdnamn ifrån kraven.
• Ange alternativet --http-path och lagrets HTTP-sökväg enligt kraven.
• Ange alternativet --access-token och värdet för din personliga åtkomsttoken från kraven.

Till exempel:

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

Frågekällor

Med Databricks SQL CLI kan du köra frågor på följande sätt:

• Från en frågesträng.
• Från en fil.
• I en metod för read-evaluate-print loop (REPL). Den här metoden innehåller förslag när du skriver.

Frågesträng

Om du vill köra en fråga som en sträng använder du -e alternativet följt av frågan, som representeras som en sträng. Till exempel:

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

Utdata:

_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

Om du vill växla utdataformat använder du --table-format alternativet tillsammans med ett värde som ascii för ASCII-tabellformat, till exempel:

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

Utdata:

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

En lista över tillgängliga utdataformatvärden finns i kommentarerna för table_format inställningen i dbsqlclirc filen.

Fil

Om du vill köra en fil som innehåller SQL använder du -e alternativet följt av sökvägen till en .sql fil. Till exempel:

dbsqlcli -e my-query.sql

Innehållet i exempelfilen my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

Utdata:

_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

Om du vill växla utdataformat använder du --table-format alternativet tillsammans med ett värde som ascii för ASCII-tabellformat, till exempel:

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

Utdata:

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

En lista över tillgängliga utdataformatvärden finns i kommentarerna för table_format inställningen i dbsqlclirc filen.

REPL

Om du vill ange repl-läge (read-evaluate-print loop) som är begränsat till standarddatabasen kör du följande kommando:

dbsqlcli

Du kan också ange REPL-läge som är begränsat till en specifik databas genom att köra följande kommando:

dbsqlcli <database-name>

Till exempel:

dbsqlcli default

Om du vill avsluta REPL-läget kör du följande kommando:

exit

I REPL-läge kan du använda följande tecken och nycklar:

• Använd semikolonet (;) för att avsluta en rad.
• Använd F3 för att växla flerradsläge.
• Använd blankstegsfältet för att visa förslag vid insättningspunkten om förslag inte redan visas.
• Använd upp- och nedpilarna för att navigera i förslag.
• Använd högerpilen för att slutföra det markerade förslaget.

Till exempel:

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

Loggning

Databricks SQL CLI loggar sina meddelanden till filen ~/.dbsqlcli/app.log som standard. Om du vill ändra det här filnamnet eller platsen ändrar du värdet för log_file inställningen i inställningsfilendbsqlclirc.

Som standard loggas meddelanden på INFO loggnivå och nedan. Ändra loggnivån genom att ändra värdet för log_level inställningen i inställningsfilen dbsqlclirc . Tillgängliga loggnivåvärden är CRITICAL, ERROR, WARNING, INFOoch och DEBUG utvärderas i den ordningen. NONE inaktiverar loggning.

Ytterligare resurser

• Databricks SQL CLI README
• Handledningsguide för att köra API för Databricks SQL-uttalanden