Databricks SQL-CLI

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 --version aus, um zu überprüfen, ob Python installiert ist. (Bei manchen Systemen muss stattdessen python3 eingegeben werden.) Installieren Sie Python, falls es noch nicht installiert ist.
• pip, das Paketinstallationsprogramm für Python. Bei neueren Python-Versionen wird pip standardmäßig installiert. Führen Sie über Ihr Terminal oder über die Eingabeaufforderung den Befehl pip --version aus, um zu überprüfen, ob pip installiert ist. (Bei manchen Systemen muss stattdessen pip3 eingegeben 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 Databricks personal access tokens (PATs). Um die Azure Databricks PAT-Authentifizierung zu verwenden, müssen Sie ein persönliches Zugriffstoken erstellen. Ausführliche Informationen zu diesem Prozess finden Sie unter Azure Databricks-Authentifizierung für persönliche Zugriffstoken.

Microsoft Entra ID-Token werden nicht unterstützt.

Sie können diese Authentifizierungsinformationen auf verschiedene Arten an die Databricks SQL-CLI übermitteln:

• In der Einstellungsdatei dbsqlclirc am Standardspeicherort (oder durch Angeben einer alternativen Einstellungsdatei mithilfe der Option --clirc bei jeder Befehlsausführung über die Databricks SQL-CLI). Weitere Informationen finden Sie unter Einstellungsdatei.
• Durch Festlegen der Umgebungsvariablen DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH und DBSQLCLI_ACCESS_TOKEN. Weitere Informationen finden Sie unter Umgebungsvariablen.
• Durch Angeben der Optionen --hostname, --http-path und --access-token bei jeder Befehlsausführung über die Databricks SQL-CLI. Weitere Informationen finden Sie unter Befehlsoptionen.

Bei jeder Verwendung der Databricks SQL-CLI wird in der folgenden Reihenfolge nach Authentifizierungsdetails gesucht, bis die ersten Details gefunden wurden:

1. Optionen --hostname, --http-path und --access-token
2. Umgebungsvariablen DBSQLCLI_HOST_NAME, DBSQLCLI_HTTP_PATH und DBSQLCLI_ACCESS_TOKEN
3. Einstellungsdatei dbsqlclirc am Standardspeicherort (oder alternative Einstellungsdatei, die mithilfe der Option --clirc angegeben 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:

1. Verwenden Sie einen Text-Editor, um die Datei dbsqlclirc zu öffnen und zu bearbeiten.

2. Scrollen Sie zum folgenden Abschnitt:

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

3. Entfernen Sie die vier Rautezeichen (#), und führen Sie die folgenden Schritte aus:

   1. Geben Sie neben host_name zwischen den Anführungszeichen ("") den Wert für Serverhostname Ihres Warehouses aus den Anforderungen ein.
   2. Geben Sie neben http_path zwischen den Anführungszeichen ("") den Wert für HTTP-Pfad Ihres Warehouses aus den Anforderungen ein.
   3. Geben Sie neben access_token zwischen 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"
   

4. 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_NAME durch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_HTTP_PATH durch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_ACCESS_TOKEN durch 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_NAME durch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_HTTP_PATH durch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_ACCESS_TOKEN durch 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_NAME durch den Wert von Serverhostname Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_HTTP_PATH durch den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen.
• DBSQLCLI_ACCESS_TOKEN durch 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 --hostname und den Wert von Serverhostname Ihres Warehouses aus den Anforderungen an.
• Geben Sie die Option --http-path und den Wert von HTTP-Pfad Ihres Warehouses aus den Anforderungen an.
• Geben Sie die Option --access-token und 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 dbsqlclirc-Einstellungsdatei.

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

• Infodatei für die Databricks SQL-CLI
• Tutorial zur Databricks-SQL-Anweisungsausführungs-API