Databricks SQL CLI

  • Artikel

Kommentar

Den här artikeln beskriver Databricks SQL CLI, som tillhandahålls som det är och inte stöds av Databricks via kundens tekniska supportkanaler. Frågor och funktionsbegäranden kan kommuniceras via sidan Problem på lagringsplatsen databricks/databricks-sql-cli på GitHub.

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-installation pip som standard. Kontrollera om du har pip installerat 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

Om du vill uppgradera en tidigare installerad version av Databricks SQL CLI kör pip du med något av följande kommandon.

pip install databricks-sql-cli --upgrade

# Or...

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

Om du vill kontrollera den installerade versionen av Databricks SQL CLI kör pip du 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å produktdatabricks SQL CLI med rätt autentiseringsuppgifter.

Databricks SQL CLI stöder autentisering med personlig åtkomsttoken för Databricks. Microsoft Entra-ID-token (tidigare Azure Active Directory) stöds inte.

Om du vill använda autentisering med personlig åtkomsttoken i Azure Databricks skapar du en personlig åtkomsttoken på följande sätt:

  1. I din Azure Databricks-arbetsyta klickar du på ditt Användarnamn för Azure Databricks i det övre fältet och väljer sedan Inställningar i listrutan.
  2. Klicka på Utvecklare.
  3. Bredvid Åtkomsttoken klickar du på Hantera.
  4. Klicka på Generera ny token.
  5. (Valfritt) Ange en kommentar som hjälper dig att identifiera den här token i framtiden och ändra tokens standardlivslängd på 90 dagar. Om du vill skapa en token utan livslängd (rekommenderas inte) lämnar du rutan Livslängd (dagar) tom (tom).
  6. Klicka på Generera.
  7. Kopiera den visade token till en säker plats och klicka sedan på Klar.

Kommentar

Se till att spara den kopierade token på en säker plats. Dela inte din kopierade token med andra. Om du förlorar den kopierade token kan du inte återskapa exakt samma token. I stället måste du upprepa den här proceduren för att skapa en ny token. Om du förlorar den kopierade token eller om du tror att token har komprometterats rekommenderar Databricks starkt att du omedelbart tar bort den token från arbetsytan genom att klicka på papperskorgsikonen (Återkalla) bredvid token på sidan Åtkomsttoken .

Om du inte kan skapa eller använda token på din arbetsyta kan det bero på att arbetsyteadministratören har inaktiverat token eller inte har gett dig behörighet att skapa eller använda token. Se din arbetsyteadministratör eller följande:

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ällningar fil.
  • Genom att DBSQLCLI_HOST_NAMEange miljövariablerna och DBSQLCLI_HTTP_PATHDBSQLCLI_ACCESS_TOKEN . Se Miljövariabler.
  • Genom att --hostnameange alternativen , --http-pathoch --access-token varje gång du kör ett kommando med Databricks SQL CLI. Se Kommandoalternativ.

Kommentar

Inställningsfilen dbsqlclirc måste finnas, även om du anger föregående miljövariabler eller anger föregående kommandoalternativ eller båda.

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ällningar fil

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_nameanger du värdet för servervärdnamnet för ditt lager från kraven mellan "" tecknen.
    2. Bredvid http_pathanger du ditt lagers HTTP-sökvägsvärde från kraven mellan "" tecknen.
    3. Bredvid access_tokenanger du värdet för din personliga åtkomsttoken från 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ärdnamnsvärde från kraven.
  • DBSQLCLI_HTTP_PATHmed ditt lagers HTTP-sökvägsvärde från kraven.
  • DBSQLCLI_ACCESS_TOKEN med ditt personliga åtkomsttokenvärde från 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 kommandotolken kör du följande kommandon och ersätter värdet för:

  • DBSQLCLI_HOST_NAME med ditt lagers servervärdnamnsvärde från kraven.
  • DBSQLCLI_HTTP_PATHmed ditt lagers HTTP-sökvägsvärde från kraven.
  • DBSQLCLI_ACCESS_TOKEN med ditt personliga åtkomsttokenvärde från 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ärdnamnsvärde från kraven.
  • DBSQLCLI_HTTP_PATHmed ditt lagers HTTP-sökvägsvärde från kraven.
  • DBSQLCLI_ACCESS_TOKEN med ditt personliga åtkomsttokenvärde från 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ärdnamnsvärde från kraven.
  • Ange alternativet --http-path och lagrets HTTP-sökvägsvärde från 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 REPL-metod (read-evaluate-print loop). 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