Databricks SQL-CLI
Hinweis
Dieser Artikel behandelt die Databricks SQL-CLI, die so wie sie ist bereitgestellt wird und nicht von Databricks über Kanäle des technischen Supports von Kunden unterstützt wird. Fragen und Funktionsanfragen können über die Seite Issues des databricks/databricks-sql-cli-Repositorys auf GitHub übermittelt werden.
Die Databricks SQL-Befehlszeilenschnittstelle (Databricks SQL-CLI) ermöglicht es Ihnen, SQL-Abfragen für Ihr vorhandenen Databricks SQL-Warehouses über Ihr Terminal oder über die Windows-Eingabeaufforderung anstatt über Orte wie den Databricks SQL-Editor oder ein Azure Databricks-Notebook auszuführen. Die Befehlszeile bietet Produktivitätsfeatures wie Vorschläge und Syntaxhervorhebung.
Anforderungen
- Mindestens ein Databricks SQL-Warehouse. Erstellen Sie ein Warehouse, wenn Sie noch keines haben.
- Python 3.7 oder eine höhere Version. Führen Sie über Ihr Terminal oder über die Eingabeaufforderung den Befehl
python --versionaus, um zu überprüfen, ob Python installiert ist. (Bei manchen Systemen muss stattdessenpython3eingegeben werden.) Installieren Sie Python, falls es noch nicht installiert ist. - pip, das Paketinstallationsprogramm für Python. Bei neueren Python-Versionen wird
pipstandardmäßig installiert. Führen Sie über Ihr Terminal oder über die Eingabeaufforderung den Befehlpip --versionaus, um zu überprüfen, obpipinstalliert ist. (Bei manchen Systemen muss stattdessenpip3eingegeben werden.) Installieren Sie pip, falls es noch nicht installiert ist. - (Optional) Ein Hilfsprogramm zum Erstellen und Verwalten virtueller Python-Umgebungen – beispielsweise venv. Mithilfe virtueller Umgebungen kann sichergestellt werden, dass Sie die richtigen Versionen von Python und Databricks SQL-CLI zusammen verwenden. Einrichtung und Verwendung virtueller Umgebungen werden in diesem Artikel nicht behandelt. Weitere Informationen finden Sie unter Erstellen virtueller Umgebungen.
Installieren der Databricks SQL-Befehlszeilenschnittstelle
Nachdem Sie die Anforderungen erfüllt haben, installieren Sie das Databricks SQL CLI-Paket aus dem Python Packaging Index (PyPI). Sie können pip verwenden, um das Paket für die Databricks SQL-CLI aus PyPI zu installieren, indem Sie pip mit einem der folgenden Befehle ausführen.
pip install databricks-sql-cli
# Or...
python -m pip install databricks-sql-cli
Um eine zuvor installierte Version der Databricks SQL-CLI zu aktualisieren, führen Sie pip mit einem der folgenden Befehle aus.
pip install databricks-sql-cli --upgrade
# Or...
python -m pip install databricks-sql-cli --upgrade
Um Ihre installierte Version der Databricks SQL-CLI zu überprüfen, führen Sie pip mit einem der folgenden Befehle aus.
pip show databricks-sql-cli
# Or...
python -m pip show databricks-sql-cli
Authentifizierung
Um sich zu authentifizieren, müssen Sie die Databricks SQL CLI mit den Verbindungsdetails Ihres Warehouse bereitstellen. Genauer gesagt benötigen Sie die Werte für Serverhostname und HTTP-Pfad. Sie müssen außerdem die richtigen Authentifizierungsanmeldeinformationen für die Databricks SQL-CLI angeben.
Die Databricks SQL-CLI unterstützt die Databricks-Authentifizierung mit persönlichen Zugriffstoken. Microsoft Entra ID-Token (ehemals Azure Active Directory) werden nicht unterstützt.
Erstellen Sie zum Verwenden der Authentifizierung mit persönlichem Azure Databricks-Zugriffstoken wie folgt ein persönliches Zugriffstoken:
- Wählen Sie in Ihrem Azure Databricks-Arbeitsbereich in der oberen Leiste Ihren Azure Databricks-Benutzernamen und dann im Dropdownmenü die Option Einstellungen aus.
- Klicken Sie auf Entwickler.
- Klicken Sie neben Zugriffstoken auf Verwalten.
- Klicken Sie auf Neues Token generieren.
- (Optional) Geben Sie einen Kommentar ein, durch den Sie dieses Token in Zukunft identifizieren können, und ändern Sie die standardmäßige Lebensdauer des Tokens von 90 Tagen. Wenn Sie ein Token ohne Gültigkeitsdauer erstellen möchten (nicht empfohlen), lassen Sie das Feld Lebensdauer (Tage) leer.
- Klicken Sie auf Generate (Generieren) .
- Kopieren Sie das angezeigte Token an einen sicheren Speicherort, und klicken Sie auf Fertig.
Hinweis
Achten Sie darauf, den kopierten Token an einem sicheren Ort zu speichern. Geben Sie das kopierte Token nicht an andere Personen weiter. Wenn Sie das kopierte Token verlieren, können Sie das gleiche Token nicht erneut generieren. Stattdessen müssen Sie erneut das Verfahren zum Erstellen eines neuen Tokens durchlaufen. Wenn Sie das kopierte Token verlieren oder glauben, dass das Token kompromittiert wurde, empfiehlt Databricks dringend, dass Sie das Token sofort aus Ihrem Arbeitsbereich löschen. Klicken Sie hierzu auf der Seite Zugriffstoken auf das Papierkorbsymbol (Widerrufen) neben dem Token.
Wenn Sie in Ihrem Arbeitsbereich keine Token erstellen oder verwenden können, liegt dies möglicherweise daran, dass Ihr Arbeitsbereichsadministrator Token deaktiviert hat oder Ihnen keine Berechtigung zum Erstellen oder Verwenden von Token erteilt hat. Wenden Sie sich an Ihren Arbeitsbereichsadministrator oder lesen Sie:
Sie können diese Authentifizierungsinformationen auf verschiedene Arten an die Databricks SQL-CLI übermitteln:
- In der Einstellungsdatei
dbsqlclircam Standardspeicherort (oder durch Angeben einer alternativen Einstellungsdatei mithilfe der Option--clircbei jeder Befehlsausführung über die Databricks SQL-CLI). Weitere Informationen finden Sie unter Einstellungsdatei. - Durch Festlegen der Umgebungsvariablen
DBSQLCLI_HOST_NAME,DBSQLCLI_HTTP_PATHundDBSQLCLI_ACCESS_TOKEN. Weitere Informationen finden Sie unter Umgebungsvariablen. - Durch Angeben der Optionen
--hostname,--http-pathund--access-tokenbei jeder Befehlsausführung über die Databricks SQL-CLI. Weitere Informationen finden Sie unter Befehlsoptionen.
Hinweis
Die dbsqlclirc-Einstellungsdatei muss vorhanden sein, auch wenn Sie die vorangehenden Umgebungsvariablen festlegen oder die vorherigen Befehlsoptionen oder beides angeben.
Bei jeder Verwendung der Databricks SQL-CLI wird in der folgenden Reihenfolge nach Authentifizierungsdetails gesucht, bis die ersten Details gefunden wurden:
- Optionen
--hostname,--http-pathund--access-token - Umgebungsvariablen
DBSQLCLI_HOST_NAME,DBSQLCLI_HTTP_PATHundDBSQLCLI_ACCESS_TOKEN - Einstellungsdatei
dbsqlclircam Standardspeicherort (oder alternative Einstellungsdatei, die mithilfe der Option--clircangegeben wurde)
Einstellungsdatei
Wenn Sie die Einstellungsdatei dbsqlclirc verwenden möchten, um der Databricks SQL-CLI Authentifizierungsdetails für Ihr Databricks SQL-Warehouse zur Verfügung zu stellen, führen Sie die Databricks SQL-CLI zunächst wie folgt aus:
dbsqlcli
Daraufhin wird von der Databricks SQL-CLI eine Einstellungsdatei erstellt. Diese befindet sich unter ~/.dbsqlcli/dbsqlclirc (Unix, Linux und macOS) bzw. unter %HOMEDRIVE%%HOMEPATH%\.dbsqlcli\dbsqlclirc oder %USERPROFILE%\.dbsqlcli\dbsqlclirc (Windows). Gehen Sie zum Anpassen dieser Datei wie folgt vor:
Verwenden Sie einen Text-Editor, um die Datei
dbsqlclirczu öffnen und zu bearbeiten.Scrollen Sie zum folgenden Abschnitt:
# [credentials] # host_name = "" # http_path = "" # access_token = ""Entfernen Sie die vier Rautezeichen (
#), und führen Sie die folgenden Schritte aus:- Geben Sie neben
host_namezwischen den Anführungszeichen ("") den Wert für Serverhostname Ihres Warehouses aus den Anforderungen ein. - Geben Sie neben
http_pathzwischen den Anführungszeichen ("") den Wert für HTTP-Pfad Ihres Warehouses aus den Anforderungen ein. - Geben Sie neben
access_tokenzwischen den Anführungszeichen ("") den Wert Ihres persönlichen Zugriffstokens aus den Anforderungen ein.
Beispiele:
[credentials] host_name = "adb-12345678901234567.8.azuredatabricks.net" http_path = "/sql/1.0/warehouses/1abc2d3456e7f890a" access_token = "dapi12345678901234567890123456789012"- Geben Sie neben
Speichern Sie die Datei
dbsqlclirc.
Anstatt die Datei dbsqlclirc am Standardspeicherort zu verwenden, können Sie auch eine Datei an einem anderen Speicherort angeben. Fügen Sie hierzu die Befehlsoption --clirc sowie den Pfad der alternativen Datei hinzu. Der Inhalt der alternativen Datei muss der oben angegebenen Syntax entsprechen.
Umgebungsvariablen
Führen Sie die folgenden Schritte aus, um der Databricks SQL-CLI Authentifizierungsdetails für Ihr Databricks SQL-Warehouse über die Variablen DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH und DBSQLCLI_ACCESS_TOKEN zur Verfügung zu stellen:
Unix, Linux und macOS
Wenn Sie die Umgebungsvariablen nur für die aktuelle Terminalsitzung festlegen möchten, führen Sie die folgenden Befehle aus. Wenn Sie die Umgebungsvariablen für alle Terminalsitzungen festlegen möchten, geben Sie die folgenden Befehle in die Startdatei Ihrer Shell ein, und starten Sie dann das Terminal neu. Ersetzen Sie die Platzhalterwerte in den folgenden Befehlen wie folgt:
DBSQLCLI_HOST_NAMEdurch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.DBSQLCLI_HTTP_PATHdurch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.DBSQLCLI_ACCESS_TOKENdurch den Wert Ihres persönlichen Zugriffstokens aus den Anforderungen.
export DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
export DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
export DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
Windows
Wenn Sie die Umgebungsvariablen nur für die aktuelle Eingabeaufforderungssitzung festlegen möchten, führen Sie die folgenden Befehle aus, und ersetzen Sie dabei:
DBSQLCLI_HOST_NAMEdurch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.DBSQLCLI_HTTP_PATHdurch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.DBSQLCLI_ACCESS_TOKENdurch den Wert Ihres persönlichen Zugriffstokens aus den Anforderungen.
set DBSQLCLI_HOST_NAME="adb-12345678901234567.8.azuredatabricks.net"
set DBSQLCLI_HTTP_PATH="/sql/1.0/warehouses/1abc2d3456e7f890a"
set DBSQLCLI_ACCESS_TOKEN="dapi12345678901234567890123456789012"
Wenn Sie die Umgebungsvariablen für alle Eingabeaufforderungssitzungen festlegen möchten, führen Sie die folgenden Befehle aus, und starten Sie anschließend Ihre Eingabeaufforderung neu. Ersetzen Sie dabei:
DBSQLCLI_HOST_NAMEdurch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.DBSQLCLI_HTTP_PATHdurch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.DBSQLCLI_ACCESS_TOKENdurch den Wert Ihres persönlichen Zugriffstokens aus den Anforderungen.
setx DBSQLCLI_HOST_NAME "adb-12345678901234567.8.azuredatabricks.net"
setx DBSQLCLI_HTTP_PATH "/sql/1.0/warehouses/1abc2d3456e7f890a"
setx DBSQLCLI_ACCESS_TOKEN "dapi12345678901234567890123456789012"
Befehlsoptionen
Führen Sie die folgenden Schritte aus, um der Databricks SQL-CLI Authentifizierungsdetails für Ihren Databricks SQL-Warehouse über die Optionen --hostname, --http-path und --access-token zur Verfügung zu stellen:
Gehen Sie bei jeder Befehlsausführung über die Databricks SQL-CLI wie folgt vor:
- Geben Sie die Option
--hostnameund den Wert von Serverhostname Ihres Warehouses aus den Anforderungen an. - Geben Sie die Option
--http-pathund den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen an. - Geben Sie die Option
--access-tokenund den Wert Ihres persönlichen Zugriffstokens aus den Anforderungen an.
Beispiele:
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" \
--hostname "adb-12345678901234567.8.azuredatabricks.net" \
--http-path "/sql/1.0/warehouses/1abc2d3456e7f890a" \
--access-token "dapi12345678901234567890123456789012"
Abfragequellen
Mit der Databricks SQL-CLI können Sie Abfragen auf folgende Weise ausführen:
- Über eine Abfragezeichenfolge
- Über eine Datei
- Mit einem REPL-Ansatz (Read-Evaluate-Print Loop, Schleife mit Lesen, Auswerten, Ausgeben). Dieser Ansatz liefert Vorschläge bei der Eingabe.
Abfragezeichenfolge
Wenn Sie eine Abfrage als Zeichenfolge ausführen möchten, verwenden Sie die Option -e, gefolgt von der Abfrage in Form einer Zeichenfolge. Beispiele:
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2"
Ausgabe:
_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
Verwenden Sie zum Ändern des Ausgabeformats die Option --table-format mit einem Wert wie etwa ascii für das ASCII-Tabellenformat. Beispiel:
dbsqlcli -e "SELECT * FROM default.diamonds LIMIT 2" --table-format ascii
Ausgabe:
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
Eine Liste der verfügbaren Ausgabeformatwerte finden Sie in der Datei dbsqlclirc in den Kommentaren für die Einstellung table_format.
Datei
Wenn Sie eine Datei ausführen möchten, die SQL enthält, verwenden Sie die Option -e, gefolgt vom Pfad zu einer Datei vom Typ .sql. Beispiele:
dbsqlcli -e my-query.sql
Inhalt der Beispieldatei my-query.sql:
SELECT * FROM default.diamonds LIMIT 2;
Ausgabe:
_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
Verwenden Sie zum Ändern des Ausgabeformats die Option --table-format mit einem Wert wie etwa ascii für das ASCII-Tabellenformat. Beispiel:
dbsqlcli -e my-query.sql --table-format ascii
Ausgabe:
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
| _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 |
+-----+-------+---------+-------+---------+-------+-------+-------+------+------+------+
Eine Liste der verfügbaren Ausgabeformatwerte finden Sie in der Datei dbsqlclirc in den Kommentaren für die Einstellung table_format.
REPL
Führen Sie den folgenden Befehl aus, um in den auf die Standarddatenbank ausgerichteten REPL-Modus (Read-Evaluate-Print Loop, Schleife mit Lesen, Auswerten, Ausgeben) zu wechseln:
dbsqlcli
Sie können auch in den REPL-Modus wechseln und ihn auf eine bestimmte Datenbank ausrichten. Führen Sie dazu den folgenden Befehl aus:
dbsqlcli <database-name>
Beispiele:
dbsqlcli default
Führen Sie zum Beenden des REPL-Modus den folgenden Befehl aus:
exit
Im REPL-Modus können die folgenden Zeichen und Tasten verwendet werden:
- Verwenden Sie das Semikolon (
;), um eine Zeile zu beenden. - Mit F3 können Sie den Mehrzeilenmodus aktivieren bzw. deaktivieren.
- Verwenden Sie die LEERTASTE, um Vorschläge an der Einfügemarke anzuzeigen, wenn noch keine Vorschläge angezeigt werden.
- Verwenden Sie die NACH-UNTEN- bzw. die NACH-OBEN-TASTE, um zwischen Vorschlägen zu navigieren.
- Verwenden Sie die NACH-RECHTS-TASTE, um den hervorgehobenen Vorschlag zu vervollständigen.
Zum Beispiel:
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
Protokollierung
Die Databricks SQL CLI protokolliert standardmäßig ihre Nachrichten in die Datei ~/.dbsqlcli/app.log. Wenn Sie diesen Dateinamen oder Speicherort ändern möchten, ändern Sie den Wert der log_file Einstellung in der dbsqlclircEinstellungsdatei.
Standardmäßig werden Nachrichten auf INFO Protokollebene und darunter protokolliert. Um diese Protokollebene zu ändern, ändern Sie den Wert der log_level Einstellung in der dbsqlclirc Einstellungsdatei. Verfügbare Werte auf Protokollebene umfassen CRITICAL, ERROR, WARNING, INFO und DEBUG, und werden in dieser Reihenfolge ausgewertet. NONE deaktiviert die Protokollierung.
Zusätzliche Ressourcen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für