Herstellen einer Verbindung von Python und pyodbc zu Azure Databricks

Artikel
05/14/2024

Sie können von Ihrem lokalen Python-Code über ODBC eine Verbindung zu Daten in einem Azure Databricks-Cluster oder SQL-Warehouse herstellen. Hierzu können Sie das Open-Source-Python-Codemodul pyodbc verwenden.

Befolgen Sie diese Anweisungen, um pyodbc zu installieren, zu konfigurieren und zu verwenden.

Weitere Informationen über pyodbc finden Sie im pyodbc Wiki.

Hinweis

Databricks bietet den Databricks SQL Connector für Python als Alternative zu pyodbc an. Der Databricks SQL Connector für Python ist einfacher einzurichten und zu verwenden und verfügt über einen stabileren Satz von Codierungskonstrukten als pyodbc. pyodbc kann jedoch eine bessere Leistung beim Abrufen von Abfrageergebnissen über 10 MB aufweisen.

Diese Anweisungen wurden mit Databricks ODBC-Treiber 2.7.5, pyodbc 5.0.1 und unixODBC 2.3.12 getestet.

Anforderungen

Ein lokaler Entwicklungscomputer, auf dem einer der folgenden Schritte ausgeführt wird:
- macOS
- Windows
- Eine Unix- oder Linux-Distribution, die .rpm- oder .deb-Dateien unterstützt
pip.
Für Unix, Linux oder macOS Homebrew.
Ein Azure Databricks-Cluster, ein Databricks SQL-Warehouse oder beides. Weitere Informationen finden Sie unter Computekonfigurationsreferenz und Was ist ein SQL-Warehouse?.

Schritt 1: Herunterladen, Installieren und Konfigurieren von Software

In diesem Schritt laden Sie den Databricks ODBC-Treiber, das Paket unixodbc und das Modul pyodbc herunter und installieren sie. (Das pyodbc-Modul erfordert das unixodbc-Paket unter Unix, Linux und macOS.) Außerdem konfigurieren Sie einen ODBC-Datenquellennamen (Data Source Name, DSN), um sich mit Ihrem Cluster oder SQL Warehouse zu authentifizieren und eine Verbindung herzustellen.

Laden Sie den Databricks ODBC-Treiber herunter und installieren Sie diesen und konfigurieren Sie einen ODBC-DSN für Ihr Betriebssystem.
Installieren Sie für Unix, Linux und macOS das unixodbc-Paket: Verwenden Sie im Terminal Homebrew, um den Befehl brew install unixodbcauszuführen. Weitere Informationen finden Sie unter unixodbc auf der Homebrew-Website.
Installieren Sie das pyodbc-Modul: Verwenden Sie im Terminal oder der Eingabeaufforderung pip, um den Befehl pip install pyodbc auszuführen. Weitere Informationen finden Sie unter pyodbc auf der PyPI-Website und Installieren im pyodbc-Wiki.

Schritt 2: Testen Ihrer Konfiguration

In diesem Schritt schreiben und führen Sie Python-Code aus, um Ihren Azure Databricks-Cluster oder Ihr Databricks SQL-Warehouse zu verwenden, um die trips-Tabelle im nyctrips-Schema des samples-Katalogs abzufragen und die Ergebnisse anzuzeigen.

Erstellen Sie eine Datei namens pyodbc-demo.py mit folgendem Inhalt. Ersetzen Sie <dsn-name> mit dem Namen des ODBC-DSN, den Sie zuvor erstellt haben, speichern Sie die Datei, und führen Sie die Datei dann mit Ihrem Python-Interpreter aus.

import pyodbc

# Connect to the Databricks cluster by using the
# Data Source Name (DSN) that you created earlier.
conn = pyodbc.connect("DSN=<dsn-name>", autocommit=True)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute(f"SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Starten Sie den Cluster, welcher der HTTPPath-Einstellung in Ihrer DSN entspricht, um die Ausführung des Codes zu beschleunigen.
Führen Sie die pyodbc-demo.py-Datei mit Ihrem Python-Interpreter aus. Informationen zu den Zeilen der Tabelle werden angezeigt.

Nächste Schritte

Um den Python-Testcode für einen anderen Cluster oder ein SQL-Warehouse auszuführen, erstellen Sie einen anderen DSN, und ändern Sie <dsn-name> in den Namen des DSN.
Ändern Sie die execute-Befehlszeichenfolge, um den Python-Testcode mit einer anderen SQL-Abfrage auszuführen.

Verwenden einer DSN-losen-Verbindung

Als Alternative zur Verwendung eines DSN-Namens können Sie die Verbindungseinstellungen auch inline angeben. Das folgende Beispiel zeigt, wie Sie eine DSN-lose Verbindungszeichenfolge für die Authentifizierung des persönlichen Zugriffstokens von Azure Databricks verwenden. In diesem Beispiel wird davon ausgegangen, dass Sie die folgenden Umgebungsvariablen haben:

Legen Sie DATABRICKS_SERVER_HOSTNAME auf den Namen Ihrer Arbeitsbereichsinstanz fest, z. B. adb-1234567890123456.7.azuredatabricks.net.
Legen Sie DATABRICKS_HTTP_PATH auf den HTTP-Pfadwert für den Zielcluster oder das SQL-Warehouse im Arbeitsbereich fest. Wie Sie den Wert des HTTP-Pfads abrufen, erfahren Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource.
Legen Sie DATABRICKS_TOKEN auf das persönliche Azure Databricks-Zugriffstoken für den Zielbenutzer fest. Informationen zum Erstellen eines persönlichen Zugriffstokens finden Sie unter Persönliche Azure Databricks-Zugriffstoken für Arbeitsbereich-Benutzer.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation des Betriebssystems.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=3;" +
  "UID=token;" +
  f"PWD={os.getenv('DATABRICKS_TOKEN')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Im folgenden Beispiel wird die browserbasierte OAuth-Authentifizierung (User-to-Machine, U2M) oder OAuth 2.0 anstelle eines persönlichen Azure Databricks-Zugriffstokens verwendet. In diesem Beispiel wird davon ausgegangen, dass Sie bereits die vorherigen DATABRICKS_SERVER_HOSTNAME und DATABRICKS_HTTP_PATH-Umgebungsvariablen festgelegt haben.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=2;" +
  "PWD=1234567",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Im folgenden Beispiel wird die Authentifizierung von OAuth-Clientanmeldeinformationen (Machine-to-Machine, M2M) oder OAuth 2.0-Clientanmeldeinformationen verwendet. In diesem Beispiel wird davon ausgegangen, dass Sie die vorherigen DATABRICKS_SERVER_HOSTNAME und DATABRICKS_HTTP_PATH-Umgebungsvariablen sowie die folgenden Umgebungsvariablen bereits festgelegt haben:

Legen Sie ARM_CLIENT_ID auf den Wert von Anwendungs-ID (Client-ID) des Dienstprinzipals fest.
Legen Sie DATABRICKS_OAUTH_SECRET auf den geheimen OAuth-Wert des Dienstprinzipals fest. (Microsoft Entra ID-Geheimnisse (ehemals Azure Active Directory) werden für die Authentifizierung von OAuth M2M- oder OAuth 2.0-Clientanmeldeinformationen mit dem Databricks ODBC-Treiber nicht unterstützt.)

Weitere Informationen finden Sie unter OAuth-M2M-Authentifizierung.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=1;" +
  f"Auth_Client_ID={os.getenv('ARM_CLIENT_ID')};" +
  f"Auth_Client_Secret={os.getenv('DATABRICKS_OAUTH_SECRET')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

Problembehandlung

In diesem Abschnitt werden häufige Probleme bei der Verwendung von pyodbc mit Databricks behandelt.

Unicode-Decodierungsfehler

Issue: Sie erhalten eine Fehlermeldung mit etwa folgendem Wortlaut:

<class 'pyodbc.Error'> returned a result with an error set
Traceback (most recent call last):
File "/Users/user/.pyenv/versions/3.7.5/lib/python3.7/encodings/utf_16_le.py", line 16, in decode
return codecs.utf_16_le_decode(input, errors, True)
UnicodeDecodeError: 'utf-16-le' codec can't decode bytes in position 2112-2113: illegal UTF-16 surrogate

Ursache: In pyodbc-Version 4.0.31 oder darunter liegt ein Problem vor, das sich mit solchen Symptomen manifestieren kann, wenn Abfragen ausgeführt werden, die Spalten mit langen Namen oder eine lange Fehlermeldung zurückgeben. Das Problem wurde durch eine neuere Version von pyodbc behoben.

Lösung: Aktualisieren Sie Ihre Installation von pyodbc auf Version 4.0.32 oder höher.

Allgemeine Problembehandlung

Weitere Informationen finden Sie unter Issues im Repository mkleeodi/pyodbc auf GitHub.

Freigeben über