Delen via

Databricks SQL CLI

  • Artikel

Notitie

In dit artikel wordt de Databricks SQL CLI behandeld. Deze wordt geleverd als zodanig en wordt niet ondersteund door Databricks via de technische ondersteuningskanalen van de klant. Vragen en functieaanvragen kunnen worden gecommuniceerd via de pagina Problemen van de databricks/databricks-sql-cli-opslagplaats op GitHub.

Met de Databricks SQL-opdrachtregelinterface (Databricks SQL CLI) kunt u SQL-query's uitvoeren op uw bestaande Databricks SQL-warehouses vanuit uw terminal of Windows-opdrachtprompt in plaats van vanaf locaties zoals de Databricks SQL-editor of een Azure Databricks-notebook. Vanaf de opdrachtregel krijgt u productiviteitsfuncties, zoals suggesties en syntaxismarkeringen.

Vereisten

  • Ten minste één Databricks SQL Warehouse. Maak een magazijn als u er nog geen hebt.
  • Python 3.7 of hoger. Als u wilt controleren of Python is geïnstalleerd, voert u de opdracht python --version uit vanaf de terminal of opdrachtprompt. (Op sommige systemen moet u mogelijk in plaats daarvan invoeren python3 .) Installeer Python als u deze nog niet hebt geïnstalleerd.
  • pip, het installatieprogramma voor het pakket voor Python. Nieuwere versies van Python installeren pip standaard. Als u wilt controleren of u hebt pip geïnstalleerd, voert u de opdracht pip --version uit vanaf de terminal of opdrachtprompt. (Op sommige systemen moet u mogelijk in plaats daarvan invoeren pip3 .) Installeer pip als u deze nog niet hebt geïnstalleerd.
  • (Optioneel) Een hulpprogramma voor het maken en beheren van virtuele Python-omgevingen, zoals venv. Virtuele omgevingen helpen ervoor te zorgen dat u de juiste versies van Python en de Databricks SQL CLI samen gebruikt. Het instellen en gebruiken van virtuele omgevingen valt buiten het bereik van dit artikel. Zie Virtuele omgevingen maken voor meer informatie.

De Databricks SQL CLI installeren

Nadat u aan de vereisten hebt voldaan, installeert u het Databricks SQL CLI-pakket vanuit de Python Packaging Index (PyPI). U kunt pip het Databricks SQL CLI-pakket installeren vanuit PyPI door uit te voeren pip met een van de volgende opdrachten.

pip install databricks-sql-cli

# Or...

python -m pip install databricks-sql-cli

Als u een eerder geïnstalleerde versie van de Databricks SQL CLI wilt upgraden, voert pip u een van de volgende opdrachten uit.

pip install databricks-sql-cli --upgrade

# Or...

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

Als u de geïnstalleerde versie van de Databricks SQL CLI wilt controleren, voert pip u een van de volgende opdrachten uit.

pip show databricks-sql-cli

# Or...

python -m pip show databricks-sql-cli

Verificatie

Voor verificatie moet u de Databricks SQL CLI opgeven met de verbindingsgegevens van uw magazijn. U hebt met name de serverhostnaam en HTTP-padwaarden nodig. U moet ook de Databricks SQL CLI producten met de juiste verificatiereferenties.

De Databricks SQL CLI ondersteunt verificatie van persoonlijke toegangstokens van Databricks. Microsoft Entra ID-tokens (voorheen Azure Active Directory) worden niet ondersteund.

Als u persoonlijke toegangstokenverificatie van Azure Databricks wilt gebruiken, maakt u als volgt een persoonlijk toegangstoken:

  1. Klik in uw Azure Databricks-werkruimte op uw Azure Databricks-gebruikersnaam in de bovenste balk en selecteer vervolgens Instellingen in de vervolgkeuzelijst.
  2. Klik op Ontwikkelaars.
  3. Klik naast Access-tokens op Beheren.
  4. Klik op Nieuw token genereren.
  5. (Optioneel) Voer een opmerking in waarmee u dit token in de toekomst kunt identificeren en de standaardlevensduur van het token van 90 dagen kunt wijzigen. Als u een token zonder levensduur wilt maken (niet aanbevolen), laat u het vak Levensduur (dagen) leeg (leeg).
  6. Klik op Genereren.
  7. Kopieer het weergegeven token naar een veilige locatie en klik vervolgens op Gereed.

Notitie

Zorg ervoor dat u het gekopieerde token op een veilige locatie opslaat. Deel uw gekopieerde token niet met anderen. Als u het gekopieerde token kwijtraakt, kunt u dat token niet opnieuw genereren. In plaats daarvan moet u deze procedure herhalen om een nieuw token te maken. Als u het gekopieerde token kwijtraakt of als u denkt dat het token is aangetast, raadt Databricks u ten zeerste aan dat u dat token onmiddellijk uit uw werkruimte verwijdert door te klikken op het prullenbakpictogram (Intrekken) naast het token op de pagina Toegangstokens .

Als u geen tokens in uw werkruimte kunt maken of gebruiken, kan dit komen doordat uw werkruimtebeheerder tokens heeft uitgeschakeld of u geen toestemming hebt gegeven om tokens te maken of te gebruiken. Neem de werkruimtebeheerder of het volgende weer:

U kunt deze verificatiegegevens op verschillende manieren opgeven voor de Databricks SQL CLI:

  • In het instellingenbestand op de dbsqlclirc standaardlocatie (of door een alternatief instellingenbestand op te geven via de --clirc optie telkens wanneer u een opdracht uitvoert met de Databricks SQL CLI). Zie Het instellingenbestand.
  • Door de DBSQLCLI_HOST_NAMEen DBSQLCLI_HTTP_PATH DBSQLCLI_ACCESS_TOKEN omgevingsvariabelen in te stellen. Zie Omgevingsvariabelen.
  • Door telkens wanneer u een opdracht uitvoert met de Databricks SQL CLI op --hostname--http-pathte geven en --access-token opties op te geven. Zie opdrachtopties.

Notitie

Het dbsqlclirc instellingenbestand moet aanwezig zijn, zelfs als u de voorgaande omgevingsvariabelen instelt of de voorgaande opdrachtopties of beide opgeeft.

Wanneer u de Databricks SQL CLI uitvoert, wordt in de volgende volgorde naar verificatiedetails gezocht en gestopt wanneer de eerste set details wordt gevonden:

  1. De --hostname, --http-pathen --access-token opties.
  2. De DBSQLCLI_HOST_NAMEen DBSQLCLI_HTTP_PATH DBSQLCLI_ACCESS_TOKEN omgevingsvariabelen.
  3. Het dbsqlclirc instellingenbestand op de standaardlocatie (of een alternatief instellingenbestand dat is opgegeven door de --clirc optie).

Instellingenbestand

Als u het dbsqlclirc instellingenbestand wilt gebruiken om de Databricks SQL CLI te voorzien van verificatiegegevens voor uw Databricks SQL-warehouse, voert u de Databricks SQL CLI voor de eerste keer uit:

dbsqlcli

De Databricks SQL CLI maakt een instellingenbestand voor u, op ~/.dbsqlcli/dbsqlclirc Unix, Linux en macOS, en in %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc of %USERPROFILE%\.dbsqlcli\dbsqlclirc in Windows. Dit bestand aanpassen:

  1. Gebruik een teksteditor om het dbsqlclirc bestand te openen en te bewerken.

  2. Schuif naar de volgende sectie:

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

  3. Verwijder de vier # tekens en:

    1. Voer naast host_namede hostnaamwaarde van uw magazijnserver in op basis van de vereisten tussen de "" tekens.
    2. Voer naast http_pathde HTTP-padwaarde van uw magazijn de waarde in van de vereisten tussen de "" tekens.
    3. Geef naast access_tokenuw persoonlijke toegangstokenwaarde op uit de vereisten tussen de "" tekens.

    Voorbeeld:

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

  4. Sla het bestand dbsqlclirc op.

In plaats van het bestand op de dbsqlclirc standaardlocatie te gebruiken, kunt u ook een bestand op een andere locatie opgeven door de --clirc opdrachtoptie en het pad naar het alternatieve bestand toe te voegen. De inhoud van dat alternatieve bestand moet voldoen aan de voorgaande syntaxis.

Omgevingsvariabelen

Als u de DBSQLCLI_HOST_NAMEvariabelen , DBSQLCLI_HTTP_PATHen DBSQLCLI_ACCESS_TOKEN omgevingsvariabelen wilt gebruiken om de Databricks SQL CLI te voorzien van verificatiegegevens voor uw Databricks SQL Warehouse, gaat u als volgt te werk:

Unix, Linux en macOS

Als u de omgevingsvariabelen alleen wilt instellen voor de huidige terminalsessie, voert u de volgende opdrachten uit. Als u de omgevingsvariabelen voor alle terminalsessies wilt instellen, voert u de volgende opdrachten in het opstartbestand van uw shell in en start u de terminal opnieuw op. Vervang in de volgende opdrachten de waarde van:

  • DBSQLCLI_HOST_NAMEmet de hostnaamwaarde van uw magazijnserver uit de vereisten.
  • DBSQLCLI_HTTP_PATHmet de HTTP-padwaarde van uw magazijn uit de vereisten.
  • DBSQLCLI_ACCESS_TOKEN met uw persoonlijke toegangstokenwaarde uit de vereisten.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Windows

Als u de omgevingsvariabelen alleen wilt instellen voor de huidige opdrachtpromptsessie, voert u de volgende opdrachten uit, waarbij u de waarde van:

  • DBSQLCLI_HOST_NAMEmet de hostnaamwaarde van uw magazijnserver uit de vereisten.
  • DBSQLCLI_HTTP_PATHmet de HTTP-padwaarde van uw magazijn uit de vereisten.
  • DBSQLCLI_ACCESS_TOKEN met uw persoonlijke toegangstokenwaarde uit de vereisten.:
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"

Als u de omgevingsvariabelen voor alle opdrachtpromptsessies wilt instellen, voert u de volgende opdrachten uit en start u de opdrachtprompt opnieuw, waarbij u de waarde van:

  • DBSQLCLI_HOST_NAMEmet de hostnaamwaarde van uw magazijnserver uit de vereisten.
  • DBSQLCLI_HTTP_PATHmet de HTTP-padwaarde van uw magazijn uit de vereisten.
  • DBSQLCLI_ACCESS_TOKEN met uw persoonlijke toegangstokenwaarde uit de vereisten.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"

Opdrachtopties

Ga als volgt te werk om de --hostname--http-path--access-token Databricks SQL CLI te gebruiken met verificatiegegevens voor uw Databricks SQL Warehouse:

Ga als volgt te werk wanneer u een opdracht uitvoert met de Databricks SQL CLI:

  • Geef de optie en de --hostname serverhostnaamwaarde van uw magazijn op uit de vereisten.
  • Geef de optie en de --http-path HTTP-padwaarde van uw magazijn op uit de vereisten.
  • Geef de --access-token optie en de waarde van uw persoonlijke toegangstoken op uit de vereisten.

Voorbeeld:

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

Querybronnen

Met de Databricks SQL CLI kunt u query's op de volgende manieren uitvoeren:

  • Uit een querytekenreeks.
  • Uit een bestand.
  • In een REPL-benadering (Read-Evaluate-Print Loop). Deze benadering biedt suggesties terwijl u typt.

Queryreeks

Als u een query als een tekenreeks wilt uitvoeren, gebruikt u de -e optie gevolgd door de query, weergegeven als een tekenreeks. Voorbeeld:

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

Uitvoer:

_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

Als u wilt schakelen tussen uitvoerindelingen, gebruikt u de --table-format optie samen met een waarde zoals ascii voor ASCII-tabelindeling, bijvoorbeeld:

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

Uitvoer:

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

Zie de opmerkingen voor de table_format instelling in het dbsqlclirc bestand voor een lijst met beschikbare waarden voor de uitvoerindeling.

Bestand

Als u een bestand wilt uitvoeren dat SQL bevat, gebruikt u de -e optie gevolgd door het pad naar een .sql bestand. Voorbeeld:

dbsqlcli -e my-query.sql

Inhoud van het voorbeeldbestand my-query.sql :

SELECT * FROM default.diamonds LIMIT 2;

Uitvoer:

_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

Als u wilt schakelen tussen uitvoerindelingen, gebruikt u de --table-format optie samen met een waarde zoals ascii voor ASCII-tabelindeling, bijvoorbeeld:

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

Uitvoer:

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

Zie de opmerkingen voor de table_format instelling in het dbsqlclirc bestand voor een lijst met beschikbare waarden voor de uitvoerindeling.

REPL

Voer de volgende opdracht uit om de REPL-modus (Read-Evaluate-Print Loop) in te voeren die is gericht op de standaarddatabase:

dbsqlcli

U kunt ook de REPL-modus opgeven die is gericht op een specifieke database door de volgende opdracht uit te voeren:

dbsqlcli <database-name>

Voorbeeld:

dbsqlcli default

Voer de volgende opdracht uit om de REPL-modus af te sluiten:

exit

In de REPL-modus kunt u de volgende tekens en sleutels gebruiken:

  • Gebruik de puntkomma (;) om een regel te beëindigen.
  • Gebruik F3 om de modus met meerdere regels in te schakelen.
  • Gebruik de spatiebalk om suggesties weer te geven op de invoegpositie als er nog geen suggesties worden weergegeven.
  • Gebruik de pijl-omhoog en pijl-omlaag om door suggesties te navigeren.
  • Gebruik de pijl-rechts om de gemarkeerde suggestie te voltooien.

Voorbeeld:

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

Logboekregistratie

De Databricks SQL CLI registreert standaard de berichten in het bestand ~/.dbsqlcli/app.log . Als u deze bestandsnaam of locatie wilt wijzigen, wijzigt u de waarde van de log_file instelling in het dbsqlclirc instellingenbestand.

Berichten worden standaard geregistreerd op logboekniveau INFO en lager. Als u dit logboekniveau wilt wijzigen, wijzigt u de waarde van de log_level instelling in het dbsqlclirc instellingenbestand. Beschikbare waarden op logboekniveau zijn onder andere CRITICAL, ERROR, WARNING, INFOen DEBUG worden in die volgorde geëvalueerd. NONE schakelt logboekregistratie uit.

Aanvullende bronnen