Databricks-Treiber für SQLTools für Visual Studio Code
Wichtig
Dieses Feature befindet sich in der Public Preview.
Mit dem Databricks-Treiber für SQLTools können Sie die SQLTools-Erweiterung für Visual Studio Code verwenden, um SQL-Objekte zu durchsuchen und SQL-Abfragen in Azure Databricks-Remotearbeitsbereichen auszuführen.
Voraussetzungen
Bevor Sie den Databricks-Treiber für SQLTools verwenden können, müssen Ihr Azure Databricks-Arbeitsbereich und Ihr lokaler Entwicklungscomputer die folgenden Anforderungen erfüllen.
Arbeitsbereichsanforderungen
Sie müssen über mindestens einen Azure Databricks-Arbeitsbereich verfügen, und dieser Arbeitsbereich muss die folgenden Anforderungen erfüllen:
Der Arbeitsbereich muss mindestens ein Databricks SQL-Warehouse enthalten.
Hinweis
Azure Databricks-Cluster werden vom Databricks-Treiber für SQLTools nicht unterstützt.
Bei Arbeitsbereichen, die für Unity Catalog aktiviert sind, muss der Arbeitsbereich mindestens einen Katalog mit mindestens einem Schema (früher als Datenbank bezeichnet) in diesem Katalog enthalten.
Bei Arbeitsbereichen, die nicht für Unity Catalog aktiviert sind, muss der Arbeitsbereich mindestens ein Schema (früher als Datenbank bezeichnet) enthalten.
Anforderungen an den lokalen Entwicklungscomputer
Auf Ihrem lokalen Entwicklungscomputer muss Folgendes installiert sein:
- Visual Studio Code, Version 1.70 oder höher. Wenn Sie Ihre installierte Version anzeigen möchten, müssen Sie unter Linux oder macOS auf Code > Info zu Visual Studio Code im Menü bzw. unter Windows auf Hilfe > Info klicken. Informationen zum Herunterladen, Installieren und Konfigurieren von Visual Studio Code finden Sie unter Einrichten von Visual Studio Code.
- SQLTools-Erweiterung für Visual Studio Code.
- Erweiterung Databricks-Treiber für SQLTools für Visual Studio Code
Wenn Sie die SQLTools-Erweiterung installieren möchten, wechseln Sie zu SQLTools und klicken dann auf Installieren oder:
Klicken Sie in Visual Studio Code im Hauptmenü auf Ansicht > Erweiterungen.
Geben Sie im Feld Nach Extensions in Marketplace suchen
SQLTools
ein.Klicken Sie auf den Eintrag SQLTools von Matheus Teixeira.
Hinweis
Möglicherweise sind mehrere SQLTools-Einträge aufgeführt. Klicken Sie unbedingt auf den Eintrag von Matheus Teixeira.
Klicken Sie auf Installieren.
Wenn Sie die Erweiterung für den Databricks-Treiber für SQLTools installieren möchten, wechseln Sie zu Databricks-Treiber für SQLTools und klicken dann auf Installieren, oder:
- Klicken Sie in Visual Studio Code im Hauptmenü auf Ansicht > Erweiterungen.
- Geben Sie im Feld Nach Extensions in Marketplace suchen
Databricks Driver for SQLTools
ein. - Klicken Sie auf den Eintrag Databricks-Treiber für SQLTools.
- Klicken Sie auf Installieren.
Authentifizierung
Sie müssen die Authentifizierung für den Databricks-Treiber für SQLTools wie folgt einrichten.
Der Databricks-Treiber für SQLTools unterstützt die folgenden Azure Databricks-Authentifizierungstypen:
- Authentifizieren mit persönlichen Azure Databricks-Zugriffstoken
- OAuth Machine-to-Machine-Authentifizierung (M2M) von Azure Databricks
- OAuth-User-to-Machine-Authentifizierung (U2M) von Azure Databricks
- Azure CLI-Authentifizierung
Hinweis
Microsoft Entra ID-Token werden vom Databricks-Treiber für SQLTools nicht unterstützt.
Authentifizieren mit persönlichen Azure Databricks-Zugriffstoken
Um den Databricks-Treiber für SQLTools mit der Authentifizierung über persönliche Azure Databricks-Zugriffstoken zu verwenden, müssen Sie über ein persönliches Azure Databricks-Zugriffstoken verfügen. Führen Sie zum Erstellen eines persönlichen Zugriffstokens die Schritte in Azure Databricks persönliche Zugriffstoken für Arbeitsbereichsbenutzer aus.
OAuth Machine-to-Machine-Authentifizierung (M2M) von Azure Databricks
Sie können die OAuth-Machine-to-Machine-Authentifizierung (M2M) von Azure Databricks verwenden, um sich mit dem Databricks-Treiber für SQLTools wie folgt zu authentifizieren:
Hinweis
Azure Databricks OAuth M2M-Authentifizierung ist in Databricks Driver für SQLTools-Versionen 0.4.2 und höher verfügbar.
- Führen Sie die Konfigurationsschritte für die OAuth M2M-Authentifizierung aus. OAuth-Computer-zu-Computer-Authentifizierung (M2M)
- Erstellen Sie ein Azure Databricks-Konfigurationsprofil mit Ihren OAuth M2M-Authentifizierungskonfigurationseinstellungen. Weitere Informationen finden Sie im Abschnitt „Config“ der OAuth-Machine-to-Machine-Authentifizierung (M2M).
- Installieren und öffnen Sie die Databricks-Erweiterung für Visual Studio Code auf Ihrem lokalen Entwicklungscomputer.
- Klicken Sie in der Databricks-Erweiterung für Visual Studio Code im Bereich Konfiguration auf die Schaltfläche Konfigurieren. Wenn die Schaltfläche Konfigurieren nicht angezeigt wird, klicken Sie stattdessen auf das Zahnradsymbol (Arbeitsbereich konfigurieren).
- Geben Sie in der Befehlspalette als Databricks-Host Ihre arbeitsbereichsspezifische Azure Databricks-URL ein, z. B
https://adb-1234567890123456.7.azuredatabricks.net
, und drücken Sie dann die EINGABETASTE. - Wählen Sie den Konfigurationsprofileintrag aus, der mit dem Eintrag übereinstimmt, den Sie in Schritt 2 erstellt haben.
- Befolgen Sie die Anweisungen auf dem Bildschirm in Ihrem Webbrowser, um die Authentifizierung mit Ihrem Azure Databricks-Konto abzuschließen.
Azure Databricks OAuth-User-to-Machine-Authentifizierung (U2M)
Sie können die Azure Databricks OAuth-User-to-Machine-Authentifizierung (U2M) verwenden, um sich mit dem Databricks Driver für SQLTools wie folgt zu authentifizieren:
Hinweis
Azure Databricks OAuth U2M-Authentifizierung ist in Databricks Driver für SQLTools-Versionen 0.4.2 und höher verfügbar.
- Installieren und öffnen Sie die Databricks-Erweiterung für Visual Studio Code auf Ihrem lokalen Entwicklungscomputer.
- Klicken Sie in der Databricks-Erweiterung für Visual Studio Code im Bereich Konfiguration auf die Schaltfläche Konfigurieren. Wenn die Schaltfläche Konfigurieren nicht angezeigt wird, klicken Sie stattdessen auf das Zahnradsymbol (Arbeitsbereich konfigurieren).
- Geben Sie in der Befehlspalette als Databricks-Host Ihre arbeitsbereichsspezifische Azure Databricks-URL ein, z. B
https://adb-1234567890123456.7.azuredatabricks.net
. Drücken Sie anschließend EINGABE. - Wählen Sie OAuth (U2M) aus.
- Befolgen Sie die Anweisungen auf dem Bildschirm in Ihrem Webbrowser, um die Authentifizierung mit Ihrem Azure Databricks-Konto abzuschließen. Wenn Sie dazu aufgefordert werden, erlauben Sie
all-apis
den Zugriff.
Authentifizierung über die Azure CLI-Authentifizierung
Sie können die Azure-Befehlszeilenschnittstelle wie folgt verwenden, um sich beim Databricks-Treiber für SQLTools zu authentifizieren:
Hinweis
Die Authentifizierung mit der Azure CLI befindet sich in einem experimentellen Featurezustand. Dieses Feature ist im Databricks-Treiber für SQLTools ab Versionen 0.4.2 verfügbar.
- Installieren Sie die Azure CLI auf Ihrem lokalen Entwicklungscomputer, falls Sie dies noch nicht getan haben.
- Installieren und öffnen Sie die Databricks-Erweiterung für Visual Studio Code auf Ihrem lokalen Entwicklungscomputer.
- Klicken Sie in der Databricks-Erweiterung für Visual Studio Code im Bereich Konfiguration auf die Schaltfläche Konfigurieren. Wenn die Schaltfläche Konfigurieren nicht angezeigt wird, klicken Sie stattdessen auf das Zahnradsymbol (Arbeitsbereich konfigurieren).
- Geben Sie in der Befehlspalette als Databricks-Host Ihre arbeitsbereichsspezifische Azure Databricks-URL ein, z. B
https://adb-1234567890123456.7.azuredatabricks.net
. Drücken Sie anschließend EINGABE. - Wählen Sie Azure CLI aus.
- Befolgen Sie die Anweisungen auf dem Bildschirm, um die Authentifizierung mit der Azure CLI abzuschließen.
Herstellen einer Verbindung mit einem Schema
- Klicken Sie in Visual Studio Code auf der Seitenleiste auf das SQLTools-Symbol.
- Wenn Sie die SQLTools-Erweiterung zum ersten Mal verwenden, klicken Sie in der Ansicht SQLTools im Bereich Verbindungen auf Neue Verbindung hinzufügen. Klicken Sie andernfalls in der Titelleiste des Bereichs auf das Symbol Neue Verbindung hinzufügen.
- Klicken Sie auf der Registerkarte SQLTools-Einstellungen für den Schritt Datenbanktreiber auswählen auf das Symbol Databricks.
- Geben Sie für den Schritt Verbindungseinstellungen die folgenden Informationen zu Ihrem Warehouse, Katalog und Schema ein:
Geben Sie unter Verbindungsname einen eindeutigen Namen für diese Verbindung ein.
(Optional) Geben Sie unter Verbindungsgruppe den Namen einer vorhandenen Verbindungsgruppe ein, um die neue Verbindung dieser Gruppe hinzuzufügen. Oder geben Sie einen eindeutigen Namen ein, um für die neue Verbindung eine neue Verbindungsgruppe zu erstellen. Verbindungsgruppen erleichtern das Auffinden von Verbindungen in der Erweiterung.
Wählen Sie für Verbinden mit eine der folgenden Optionen aus:
- Um ein persönliches Azure Databricks-Zugriffstoken für die Authentifizierung zu verwenden, wählen Sie Hostname und Token aus.
- Wählen Sie für Databricks Driver für SQLTools-Versionen 0.4.2 und höher, um die OAuth U2M- oder M2M- oder Azure CLI-Authentifizierung zu verwenden, VS Code Extension (Beta) aus.
Wenn Sie Hostname und Token für Verbinden mit ausgewählt haben, geben Sie für Host die Serverhostname-Einstellung für das Warehouse ein. Informationen zum Abrufen der Einstellung für den Serverhostnamen eines Warehouse finden Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource.
Geben Sie unter Pfad die Einstellung für den HTTP-Pfad des Warehouse oder Clusters ein. Informationen zum Abrufen der Einstellung für den HTTP-Pfad eines Warehouse finden Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource.
Wenn Sie Hostname und Token für Verbinden mit ausgewählt haben, geben Sie für Token den Wert Ihres persönlichen Azure Databricks-Zugriffstokens ein.
Geben Sie unter Katalog den Namen Ihres Katalogs ein.
Hinweis
Bei Arbeitsbereichen, die für Unity Catalog nicht aktiviert sind, können Sie Katalog leer lassen, um den Standardwert von
hive_metastore
zu verwenden.Geben Sie den Namen Ihres Schemas unter Schema ein.
(Optional) Übernehmen Sie für Standardlimit für Datensätze anzeigen den Standardwert
50
, um nur die ersten 50 Zeilen für jede Abfrage anzuzeigen, oder geben Sie einen anderen Grenzwert ein.
- Klicken Sie auf Verbindung testen.
- Klicken Sie auf Verbindung speichern, wenn der Verbindungstest erfolgreich ist.
Ändern der Einstellungen einer Verbindung
Bei diesem Verfahren wird davon ausgegangen, dass Sie erfolgreich eine Verbindung mit mindestens einem Warehouse hergestellt haben.
- Wenn die SQLTools-Ansicht nicht sichtbar ist, müssen Sie in Visual Studio Code auf der Seitenleiste auf das Symbol SQLTools klicken.
- Erweitern Sie im Bereich Verbindungen die Verbindungsgruppe, sofern eine Gruppe für Ihre Zielverbindung vorhanden ist.
- Klicken Sie mit der rechten Maustaste auf die Verbindung, und klicken Sie dann auf Verbindung bearbeiten.
- Ändern Sie die Zieleinstellungen.
- Klicken Sie auf Verbindung testen.
- Klicken Sie auf Verbindung speichern, wenn der Verbindungstest erfolgreich ist.
Durchsuchen der Objekte eines Schemas
- Erweitern Sie im Bereich Verbindungen die Verbindungsgruppe, sofern eine Gruppe für Ihre Zielverbindung vorhanden ist.
- Doppelklicken oder erweitern Sie die Zielverbindung für Ihr Warehouse.
- Erweitern Sie die Zieldatenbank (Schema), sofern eine Datenbank für Ihre Verbindung vorhanden ist.
- Erweitern Sie Tabellen oder Ansichten, wenn eine oder mehrere Tabellen oder Ansichten für Ihre Datenbank (Schema) vorhanden sind.
- Erweitern Sie eine beliebige Zieltabelle oder -ansicht, um die Spalten der Tabelle oder Ansicht anzuzeigen.
Anzeigen der Zeilen oder des Schemas für eine Tabelle oder Ansicht
Erweitern Sie die Tabellen oder Ansichten im Bereich Verbindungen und führen Sie anschließend eine der folgenden Aktionen aus:
- Klicken Sie zum Anzeigen der Zeilen der Tabelle oder Ansicht mit der rechten Maustaste auf die Tabelle oder Ansicht, und klicken Sie auf Tabellendatensätze anzeigen oder Ansichtendatensätze anzeigen.
- Klicken Sie zum Anzeigen des Schemas der Tabelle oder Ansicht mit der rechten Maustaste auf die Tabelle oder Ansicht, und klicken Sie auf Tabelle beschreiben oder Ansicht beschreiben.
Generieren einer Einfügeabfrage für eine Tabelle
- Platzieren Sie den Cursor in einem vorhandenen Editor an der Stelle, an der die Einfügeabfrage hinzugefügt werden soll.
- Erweitern Sie im Bereich Verbindungen die Option Tabellen, klicken Sie mit der rechten Maustaste auf die Tabelle, und klicken Sie auf Einfügeabfrage generieren. Die Definition der Einfügeabfrage wird an der Einfügemarke des Cursors hinzugefügt.
Erstellen und Ausführen einer Abfrage
Bei diesem Verfahren wird davon ausgegangen, dass Sie erfolgreich eine Verbindung mit mindestens einem Warehouse hergestellt haben.
- Erweitern Sie im Bereich Verbindungen die Verbindungsgruppe, sofern eine Gruppe für Ihre Zielverbindung vorhanden ist.
- Doppelklicken oder erweitern Sie die Zielverbindung für Ihr Warehouse.
- Wählen Sie die Verbindung aus, und klicken Sie in der Titelleiste des Bereichs Verbindungen auf Neue SQL-Datei. Eine neue Editor-Registerkarte wird angezeigt.
- Geben Sie Ihre SQL-Abfrage im neuen Editor ein.
- Klicken Sie zum Ausführen der SQL-Abfrage im Editor auf Auf aktiver Verbindung ausführen. Die Ergebnisse der Abfrage werden auf einer neuen Editor-Registerkarte angezeigt.
Vorhandene Abfrage ausführen
Bei diesem Verfahren wird davon ausgegangen, dass Sie erfolgreich eine Verbindung mit mindestens einem Warehouse hergestellt haben.
- Erweitern Sie im Bereich Verbindungen die Verbindungsgruppe, sofern eine Gruppe für Ihre Zielverbindung vorhanden ist.
- Doppelklicken oder erweitern Sie die Zielverbindung für Ihr Warehouse.
- Wählen Sie die Verbindung aus, öffnen Sie eine beliebige Datei mit der Dateierweiterung von
.sql
, oder wählen Sie eine beliebige Gruppe fortlaufender SQL-Anweisungen in einem zuvor geöffneten Editor aus. - Klicken Sie zum Ausführen der SQL-Abfrage über eine geöffnete
.sql
-Datei auf Auf aktiver Verbindung ausführen im Editor, wobei der Inhalt Ihrer.sql
-Datei im Editor angezeigt werden sollte. Die Ergebnisse der Abfrage werden auf einer neuen Editor-Registerkarte angezeigt. - Um eine ausgewählte Gruppe fortlaufender SQL-Anweisungen in einem zuvor geöffneten Editor auszuführen, müssen Sie mit der rechten Maustaste auf Ihre Auswahl und dann auf Ausgewählte Abfrage ausführen klicken. Die Ergebnisse der Abfrage werden auf einer neuen Editor-Registerkarte angezeigt.
Senden von Nutzungsprotokollen an Databricks
Wenn beim Verwenden des Databricks-Treibers für SQLTools Probleme auftreten, können Sie Verwendungsprotokolle und zugehörige Informationen an den Databricks-Support senden, indem Sie die folgenden Schritte ausführen:
- Installieren Sie die Databricks-Erweiterung für Visual Studio Code auf Ihrem lokalen Entwicklungscomputer.
- Aktivieren Sie die Protokollierung, indem Sie die Einstellung Protokolle: Aktiviert überprüfen, oder die Einstellung
databricks.logs.enabled
auftrue
stellen, wie unter Einstellungen für die Databricks-Erweiterung für Visual Studio Code beschrieben. Achten Sie darauf, Visual Studio Code neu zu starten, nachdem Sie die Protokollierung aktiviert haben. - Versuchen Sie, Ihr Problem zu reproduzieren.
- Führen Sie in der Befehlspalette (Ansicht > Befehlspalette im Hauptmenü) den Befehl Databricks: Vollständige Protokolle öffnen aus.
- Senden Sie die ausgegebenen Dateien
Databricks Logs.log
,databricks-cli-logs.json
undsdk-and-extension-logs.json
an den Databricks-Support. - Kopieren Sie auch den Inhalt des Terminals (Ansicht > Terminal) im Kontext des Problems, und senden Sie diesen Inhalt an den Databricks-Support.
Die Informationen in der Ansicht Ausgabe (Ansicht > Ausgabe, Databricks-Protokolle) werden abgeschnitten, wenn Protokolle: Aktiviert aktiviert oder databricks.logs.enabled
auf true
festgelegt ist. Wenn Sie weitere Informationen anzeigen möchten, ändern Sie die folgenden Einstellungen, wie in den Einstellungen für die Databricks-Erweiterung für Visual Studio Code beschrieben:
- Protokolle: Maximale Arraylänge oder
databricks.logs.maxArrayLength
- Protokolle: Maximale Feldlänge oder
databricks.logs.maxFieldLength
- Protokolle: Abschneidetiefe oder
databricks.logs.truncationDepth