Databricks SQL-Connector für Python

Artikel
11/16/2024

Der Databricks SQL-Connector für Python ist eine Python-Bibliothek, mit der Sie Python-Code verwenden können, um SQL Befehle in Azure Databricks-Clustern und Databricks SQL-Warehouses auszuführen. Der Databricks SQL-Connector für Python ist einfacher einzurichten und zu verwenden als ähnliche Python-Bibliotheken wie pyodbc. Diese Bibliothek entspricht der PEP 249 – Python Database API Specification v2.0.

Hinweis

Der Databricks SQL Connector für Python enthält auch einen SQLAlchemy-Dialekt für Azure Databricks. Siehe Verwenden von SQLAlchemy mit Azure Databricks.

Anforderungen

Ein Entwicklungscomputer mit Python >=3.8 und <=3.11.
Databricks empfiehlt die Verwendung von virtuellen Python-Umgebungen, etwa denen, die von venv bereitgestellt werden und in Python enthalten sind. Mithilfe virtueller Umgebungen kann sichergestellt werden, dass Sie die richtigen Versionen von Python und des Databricks SQL-Connectors für Python zusammen verwenden. Einrichtung und Verwendung virtueller Umgebungen werden in diesem Artikel nicht behandelt. Weitere Informationen finden Sie unter Erstellen virtueller Umgebungen.
Ein vorhandener Cluster oder vorhandenes SQL-Warehouse.

Erste Schritte

Installieren Sie die Bibliothek für den Databricks SQL-Connector für Python auf Ihrem Entwicklungscomputer, indem Sie pip install databricks-sql-connector oder python -m pip install databricks-sql-connector ausführen.
Sammeln Sie die folgenden Informationen über den Cluster oder das SQL-Warehouse, den oder das Sie verwenden möchten:

Cluster
- Den Serverhostnamen des Clusters. Diesen können Sie dem Wert Serverhostname auf der Registerkarte Erweiterte Optionen > JDBC/ODBC für Ihren Cluster entnehmen.
- Den HTTP-Pfad des Clusters. Diesen finden Sie im Wert HTTP-Pfad auf der Registerkarte Erweiterte Optionen > JDBC/ODBC für Ihren Cluster.
SQL-Warehouse
- Den Serverhostnamen des SQL-Warehouses. Sie finden diesen im Wert Serverhostname auf der Registerkarte Verbindungsdetails für Ihr SQL-Warehouse.
- Den HTTP-Pfad des SQL-Warehouses. Sie finden diesen im Wert HTTP-Pfad auf der Registerkarte Verbindungsdetails für Ihr SQL-Warehouse.

Authentifizierung

Der Databricks SQL-Connector für Python unterstützt die folgenden Azure Databricks-Authentifizierungstypen:

Authentifizierung mit persönlichen Databricks-Zugriffstoken
Microsoft Entra ID-Tokenauthentifizierung
OAuth-M2M-Authentifizierung
OAuth U2M-Authentifizierung (User-to-Machine)

Der Databricks SQL-Connector für Python unterstützt aktuell noch nicht die folgenden Azure Databricks-Authentifizierungstypen:

Authentifizierung mit persönlichen Databricks-Zugriffstoken

Um den Databricks SQL Connector für Python mit der Authentifizierung des persönlichen Zugriffstokens von Azure Databricks zu verwenden, müssen Sie zuerst ein persönliches Azure Databricks-Zugriffstoken erstellen. Führen Sie dazu die Schritte in Azure Databricks persönliche Zugriffstoken für Arbeitsbereichsbenutzer aus.

Verwenden Sie den folgenden Codeschnipsel, um den Databricks SQL-Connector für Python zu authentifizieren. Bei diesem Codeschnipsel wird davon ausgegangen, dass Sie die folgenden Umgebungsvariablen festgelegt haben:

DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
DATABRICKS_HTTP_PATH ist auf den Wert von HTTP-Pfad für Ihren Cluster oder Ihr SQL-Warehouse festgelegt.
DATABRICKS_TOKEN ist auf das persönliche Azure Databricks-Zugriffstoken festgelegt.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Der Databricks-SQL-Connector für die Python-Versionen 2.7.0 und höher unterstützt die M2M-Authentifizierung (Machine-to-Machine) von OAuth. Sie müssen das Databricks-SDK für Python 0.18.0 oder höher ebenfalls installieren (indem Sie beispielsweise pip install databricks-sdk oder python -m pip install databricks-sdk ausführen).

Um den Databricks-SQL-Connector für Python mit der M2M-Authentifizierung von OAuth zu verwenden, müssen Sie die folgenden Schritte ausführen:

Erstellen Sie einen Azure Databricks-Dienstprinzipal in Ihrem Azure Databricks-Arbeitsbereich, und erstellen Sie ein OAuth-Geheimnis für diesen Dienstprinzipal.

Informationen zum Erstellen des Dienstprinzipals und des geheimen OAuth-Schlüssels finden Sie unter Authentifizierung des Zugriffs bei Azure Databricks mit einem Dienstprinzipal unter Verwendung von OAuth (OAuth M2M). Notieren Sie sich den UUID- oder Anwendungs-ID-Wert des Dienstprinzipals und den Geheimniswert für das OAuth-Geheimnis des Dienstprinzipals.
Gewähren Sie diesem Dienstprinzipal Zugriff auf Ihren Cluster oder Ihr Warehouse.

Informationen dazu, wie Sie dem Dienstprinzipal Zugriff auf Ihren Cluster oder Ihr Warehouse gewähren, finden Sie unter Computeberechtigungen oder Verwaltung eines SQL-Warehouse.

DATABRICKS_SERVER_HOSTNAME ist auf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
DATABRICKS_HTTP_PATH ist auf den Wert von HTTP-Pfad für Ihren Cluster oder Ihr SQL-Warehouse festgelegt.
Legen Sie DATABRICKS_CLIENT_ID auf den UUID- oder Anwendungs-ID-Wert des Dienstprinzipals fest.
DATABRICKS_CLIENT_SECRET ist auf den Wert Geheimnis für das OAuth-Geheimnis des Dienstprinzipals festgelegt.

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

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Microsoft Entra ID-Tokenauthentifizierung

Um den Databricks SQL-Connector für Python mit Microsoft Entra ID-Tokenauthentifizierung zu verwenden, müssen Sie den Databricks SQL-Connector für Python mit dem Microsoft Entra ID-Token bereitstellen. Gehen Sie wie folgt vor, um ein Microsoft Entra ID-Zugriffstoken zu erstellen:

Für eine*n Azure Databricks-Benutzer*in können Sie die Azure CLI verwenden. Weitere Informationen finden Sie unter Abrufen von Microsoft Entra ID-Token für Benutzer mithilfe der Azure CLI.
Einen Microsoft Entra ID-Dienstprinzipal finden Sie unter Abrufen eines Microsoft Entra ID-Zugriffstokens mit der Azure CLI. Informationen zum Erstellen eines verwalteten Dienstprinzipals von Microsoft Entra ID finden Sie unter Verwalten von Dienstprinzipalen.

Microsoft Entra ID-Token haben eine Standardlebensdauer von ca. 1 Stunde. Wiederholen Sie diesen Vorgang, um ein neues Microsoft Entra ID-Token zu erstellen.

Legen Sie DATABRICKS_SERVER_HOSTNAME auf den Wert von Serverhostname für Ihren Cluster oder Ihr SQL-Warehouse fest.
Legen Sie DATABRICKS_HTTP_PATH auf den Wert von HTTP-Pfad für Ihren Cluster oder Ihr SQL-Warehouse fest.
Legen Sie DATABRICKS_TOKEN auf das Microsoft Entra ID-Token fest.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

OAuth U2M-Authentifizierung (User-to-Machine)

Databricks SQL Connector für Python-Versionen 2.7.0 und höher unterstützen OAuth-User-to-Machine-Authentifizierung (U2M). Sie müssen das Databricks-SDK für Python 0.19.0 oder höher ebenfalls installieren, indem Sie beispielsweise pip install databricks-sdk oder python -m pip install databricks-sdk ausführen.

Verwenden Sie den folgenden Codeschnipsel, um den Databricks SQL-Connector für Python mit OAuth-U2M-Authentifizierung zu authentifizieren. Die OAuth-U2M-Authentifizierung verwendet die menschliche Anmeldung und Einwilligung in Echtzeit, um das Azure Databricks-Zielbenutzerkonto zu authentifizieren. Bei diesem Codeschnipsel wird davon ausgegangen, dass Sie die folgenden Umgebungsvariablen festgelegt haben:

Legen Sie DATABRICKS_SERVER_HOSTNAME auf den Wert von Serverhostname für Ihren Cluster oder Ihr SQL-Warehouse fest.
Legen Sie DATABRICKS_HTTP_PATH auf den Wert von HTTP-Pfad für Ihren Cluster oder Ihr SQL-Warehouse fest.

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

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

Beispiele

Die folgenden Codebeispiele zeigen, wie Sie den Databricks SQL-Connector für Python verwenden, um Daten abzufragen und einzufügen, Metadaten abzufragen, Cursor und Verbindungen zu verwalten und die Protokollierung zu konfigurieren.

Hinweis

Die folgenden Codebeispiele veranschaulichen, wie ein persönliches Azure Databricks-Zugriffstoken für die Authentifizierung verwendet wird. Informationen zur Verwendung anderer verfügbarer Azure Databricks-Authentifizierungstypen finden Sie unter Authentifizierung.

Diese Codebeispiele rufen ihre Werte für server_hostname-, http_path- und access_token-Verbindungsvariablen aus diesen Umgebungsvariablen ab:

DATABRICKS_SERVER_HOSTNAME, das den Serverhostname-Wert aus den Anforderungen darstellt.
DATABRICKS_HTTP_PATH, das den HTTP-Pfad-Wert aus den Anforderungen darstellt.
DATABRICKS_TOKEN, das Ihr Zugriffstoken aus den Anforderungen darstellt.

Sie können auch andere Methoden verwenden, um diese Verbindungsvariablenwerte abzurufen. Die Verwendung von Umgebungsvariablen ist nur ein Ansatz unter vielen.

Daten abfragen
Einfügen von Daten
Abfragen von Metadaten
Verwalten von Cursor und Verbindungen
Verwalten von Dateien in Unity Catalog-Volumes
Konfigurieren der Protokollierung

Daten abfragen

Im folgenden Codebeispiel wird veranschaulicht, wie der Databricks SQL-Connector für Python aufgerufen wird, um einen einfachen SQL-Befehl auf einem Cluster oder SQL-Warehouse auszuführen. Dieser Befehl gibt die ersten beiden Zeilen aus der Tabelle trips im Schema nyctaxi des Katalogs samples zurück.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT 2")
    result = cursor.fetchall()

    for row in result:
      print(row)

Einfügen von Daten

Im folgenden Beispiel wird veranschaulicht, wie kleine Datenmengen (Tausende von Zeilen) eingefügt werden:

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

    cursor.execute("SELECT * FROM squares LIMIT 10")

    result = cursor.fetchall()

    for row in result:
      print(row)

Bei großen Datenmengen sollten Sie die Daten zunächst in den Cloudspeicher hochladen und dann den Befehl COPY INTO ausführen.

Abfragen von Metadaten

Es gibt dedizierte Methoden zum Abrufen von Metadaten. Im folgenden Beispiel werden Metadaten zu Spalten in einer Beispieltabelle abgerufen:

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

Verwalten von Cursor und Verbindungen

Es empfiehlt sich, Verbindungen und Cursor zu schließen, die nicht mehr verwendet werden. Dadurch werden Ressourcen auf Azure Databricks-Clustern und Databricks SQL-Warehouses freigegeben.

Sie können einen Kontext-Manager (die in den vorherigen Beispielen verwendete with-Syntax) verwenden, um die Ressourcen zu verwalten, oder explizit close aufrufen:

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Verwalten von Dateien in Unity Catalog-Volumes

Mit dem Databricks SQL-Connector können Sie lokale Dateien in Unity Catalog-Volumes schreiben, Dateien aus Volumes herunterladen und Dateien aus Volumes löschen, wie im folgenden Beispiel gezeigt:

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allows_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allows_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/temp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

Konfigurieren der Protokollierung

Der Databricks SQL-Connector verwendet das Standardprotokollierungsmodul von Python. Sie können den Protokolliergrad ähnlich wie im Folgenden konfigurieren:

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

Testen

Verwenden Sie Python-Testframeworks wie pytest, um Ihren Code zu testen. Um Ihren Code unter simulierten Bedingungen zu testen, ohne Azure Databricks-REST-API-Endpunkte aufzurufen oder den Status Ihrer Azure Databricks-Konten oder -Arbeitsbereiche zu ändern, können Sie Python-Pseudobibliotheken wie unittest.mock verwenden.

Ein Beispiel: Angenommen, die folgende Datei namens helpers.py enthält eine get_connection_personal_access_token-Funktion, die ein persönliches Azure Databricks-Zugriffstoken verwendet, um eine Verbindung mit einem Azure Databricks-Arbeitsbereich zurückzugeben, und eine select_nyctaxi_trips-Funktion, die die Verbindung verwendet, um die angegebene Anzahl von Datenzeilen aus der Tabelle trips im Schema nyctaxi des Katalogs samples abzurufen:

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
  result: List[Row] = cursor.fetchall()
  return result

Nehmen wir außerdem an, die folgende Datei mit dem Namen main.py ruft die Funktionen get_connection_personal_access_token und select_nyctaxi_trips auf:

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

Die folgende Datei mit dem Namen test_helpers.py testet, ob die select_nyctaxi_trips Funktion die erwartete Antwort zurückgibt. Anstatt eine echte Verbindung mit dem Zielarbeitsbereich zu erstellen, simuliert dieser Test ein Connection-Objekt. Zudem simuliert der Test einige Daten, die dem Schema und den Werten aus den realen Daten entsprechen. Der Test gibt die simulierten Daten über die simulierte Verbindung zurück und überprüft dann, ob einer der simulierten Datenzeilenwerte dem erwarteten Wert entspricht.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

Da die Funktion select_nyctaxi_trips eine SELECT-Anweisung enthält und daher den Status der Tabelle trips nicht ändert, sind in diesem Beispiel nicht unbedingt Pseudoelemente (Mocking) erforderlich. Mithilfe von Pseudoelementen können Sie Ihre Tests jedoch schnell ausführen, ohne darauf zu warten, dass eine tatsächliche Verbindung mit dem Arbeitsbereich hergestellt wird. Außerdem können Sie simulierte Tests mehrmals für Funktionen ausführen, die den Status einer Tabelle ändern können, z. B. INSERT INTO, UPDATE und DELETE FROM.

Paket

databricks-sql-connector

Verwendung: pip install databricks-sql-connector

Siehe auch databricks-sql-connector im Python-Paketindex (PyPI).

Modul

databricks.sql

Verwendung: from databricks import sql

Klassen

Zu den ausgewählten Klassen gehören:

Klassen
`Connection` Sitzung auf einer Azure Databricks-Computeressource
`Cursor` Mechanismus zum Durchlaufen von Datensätzen
`Row` Datenzeile in einem SQL-Abfrageergebnis

`Connection`-Klasse

Rufen Sie zum Erstellen eines Connection-Objekts die databricks.sql.connect-Methode mit den folgenden Parametern auf:

Parameter
`server_hostname` Typ: `str` Der Serverhostname für den Cluster oder das SQL-Warehouse. Informationen zum Ermitteln des Serverhostnamens finden Sie in den Anweisungen weiter oben in diesem Artikel. Dieser Parameter ist erforderlich. Beispiel: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Typ: `str` Der HTTP-Pfad des Clusters oder SQL-Warehouses. Informationen zum Abrufen des HTTP-Pfads finden Sie in den Anweisungen weiter oben in diesem Artikel. Dieser Parameter ist erforderlich. Beispiel: `sql/protocolv1/o/1234567890123456/1234-567890-test123` für einen Cluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` für ein SQL-Warehouse.
`access_token`, `auth_type` Typ: `str` Informationen zu Azure Databricks-Authentifizierungseinstellungen. Ausführliche Informationen finden Sie unter Authentifizierung.
`session_configuration` Typ: `dict[str, Any]` Ein Wörterbuch mit Spark-Sitzungskonfigurationsparametern. Das Festlegen einer Konfiguration entspricht der Verwendung des SQL-Befehls `SET key=val`. Führen Sie den SQL-Befehl `SET -v` aus, um eine vollständige Liste der verfügbaren Konfigurationen abzurufen. Der Standardwert ist `None`. Dieser Parameter ist optional. Beispiel: `{"spark.sql.variable.substitute": True}`
`http_headers` Typ: `List[Tuple[str, str]]]` Zusätzliche (Schlüssel-Wert-)Paare, die in HTTP-Headern für jede RPC-Anforderung vom Client festgelegt werden sollen. Bei der typischen Verwendung werden keine zusätzlichen HTTP-Header festgelegt. Der Standardwert ist `None`. Dieser Parameter ist optional. Seit Version 2.0
`catalog` Typ: `str` Der Anfangskatalog für die Verbindung. Der Standardwert ist `None` (in diesem Fall wird der Standardkatalog verwendet, in der Regel `hive_metastore`). Dieser Parameter ist optional. Seit Version 2.0
`schema` Typ: `str` Das Anfangsschema für die Verbindung. Der Standardwert ist `None` (in diesem Fall wird das Standardschema verwendet, in der Regel `default`). Dieser Parameter ist optional. Seit Version 2.0
`use_cloud_fetch` Typ: `bool` `True`, um Abrufanforderungen direkt an den Cloudobjektspeicher zu senden, um Datenblöcke herunterzuladen. `False` (Standardeinstellung), um Abrufanforderungen direkt an Azure Databricks zu senden. Wenn `use_cloud_fetch` auf `True` festgelegt wurde, der Netzwerkzugriff jedoch blockiert ist, führen die Abrufanforderungen zu Fehlern. Seit Version 2.8

Zu den ausgewählten Connection-Methoden gehören:

Methoden
`close` Schließt die Verbindung mit der Datenbank und gibt alle zugeordneten Ressourcen auf dem Server frei. Alle zusätzlichen Aufrufe dieser Verbindung lösen einen `Error` aus. Keine Parameter. Kein Rückgabewert.
`cursor` Gibt ein neues `Cursor`-Objekt zurück, das das Durchlaufen der Datensätze in einer Datenbank ermöglicht. Keine Parameter.

`Cursor`-Klasse

Rufen Sie zum Erstellen eines Cursor-Objekts die cursor-Methode der Klasse Connection auf.

Zu den ausgewählten Cursor-Attributen gehören:

Attribute

Attribute
`arraysize` Wird mit der `fetchmany`-Methode verwendet und gibt die interne Puffergröße an. Dies legt auch fest, wie viele Zeilen tatsächlich gleichzeitig vom Server abgerufen werden. Der Standardwert ist `10000`. Für schmale Ergebnisse (Ergebnisse, in denen die einzelnen Zeilen nicht viele Daten enthalten) sollten Sie diesen Wert erhöhen, um eine bessere Leistung zu erzielen. Lese-/Schreibzugriff.
`description` Enthält eine Python-`list` mit `tuple`-Objekten. Jedes dieser `tuple`-Objekte enthält 7 Werte, wobei die ersten zwei Elemente jedes `tuple`-Objekts Informationen enthalten, die eine einzelne Ergebnisspalte wie folgt beschreiben: - `name`: Der Name der Spalte. - `type_code`: Eine Zeichenfolge, die den Typ der Spalte angibt. Beispielsweise hat eine ganzzahlige Spalte den Typcode `int`. Die verbleibenden fünf Elemente jedes aus sieben Elementen bestehenden `tuple`-Objekts werden nicht implementiert, und ihre Werte sind nicht definiert. Sie werden in der Regel als 4 `None`-Werte gefolgt von einem einzelnen `True`-Wert zurückgegeben. Schreibgeschützter Zugriff.

arraysize

Wird mit der fetchmany-Methode verwendet und gibt die interne Puffergröße an. Dies legt auch fest, wie viele Zeilen tatsächlich gleichzeitig vom Server abgerufen werden. Der Standardwert ist 10000. Für schmale Ergebnisse (Ergebnisse, in denen die einzelnen Zeilen nicht viele Daten enthalten) sollten Sie diesen Wert erhöhen, um eine bessere Leistung zu erzielen.

Lese-/Schreibzugriff.

description

Enthält eine Python-list mit tuple-Objekten. Jedes dieser tuple-Objekte enthält 7 Werte, wobei die ersten zwei Elemente jedes tuple-Objekts Informationen enthalten, die eine einzelne Ergebnisspalte wie folgt beschreiben:

- name: Der Name der Spalte.
- type_code: Eine Zeichenfolge, die den Typ der Spalte angibt. Beispielsweise hat eine ganzzahlige Spalte den Typcode int.

Die verbleibenden fünf Elemente jedes aus sieben Elementen bestehenden tuple-Objekts werden nicht implementiert, und ihre Werte sind nicht definiert. Sie werden in der Regel als 4
None-Werte gefolgt von einem einzelnen True-Wert zurückgegeben.

Schreibgeschützter Zugriff.

Zu den ausgewählten Cursor-Methoden gehören:

Methoden
`cancel` Unterbricht die Ausführung von Datenbankabfragen oder -befehlen, die der Cursor gestartet hat. Um die zugeordneten Ressourcen auf dem Server freizugeben, rufen Sie die `close`-Methode auf, nachdem Sie die `cancel`-Methode aufgerufen haben. Keine Parameter. Kein Rückgabewert.
`close` Schließt den Cursor und gibt die zugeordneten Ressourcen auf dem Server frei. Das Schließen eines bereits geschlossenen Cursors kann einen Fehler auslösen. Keine Parameter. Kein Rückgabewert.
`execute` Bereitet eine Datenbankabfrage oder einen Datenbankbefehl vor und führt sie bzw. ihn dann aus. Kein Rückgabewert. Parameter: `operation` Typ: `str` Die Abfrage oder der Befehl, die bzw. der vorbereitet und dann ausgeführt werden soll. Dieser Parameter ist erforderlich. Beispiel ohne den `parameters`-Parameter: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Beispiel mit dem `parameters`-Parameter: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Typ: Wörterbuch Eine Sequenz von Parametern, die zusammen mit dem `operation`-Parameter verwendet werden sollen. Dieser Parameter ist optional. Der Standardwert ist `None`.
`executemany` Bereitet eine Datenbankabfrage oder einen Datenbankbefehl mit allen Parametersequenzen im `seq_of_parameters`-Argument vor und führt sie dann aus. Nur das endgültige Resultset wird beibehalten. Kein Rückgabewert. Parameter: `operation` Typ: `str` Die Abfrage oder der Befehl, die bzw. der vorbereitet und dann ausgeführt werden soll. Dieser Parameter ist erforderlich. `seq_of_parameters` Typ: `list` von `dict` Eine Sequenz aus vielen Sätzen von Parameterwerten, die mit dem `operation`-Parameter verwendet werden sollen. Dieser Parameter ist erforderlich.
`catalogs` Führen Sie eine Metadatenabfrage zu den Katalogen aus. Die tatsächlichen Ergebnisse sollten dann mit `fetchmany` oder `fetchall` abgerufen werden. Wichtige Felder im Resultset sind: – Feldname: `TABLE_CAT`. Geben Sie Folgendes ein: `str`. Der Name des Katalogs. Keine Parameter. Kein Rückgabewert. Seit Version 1.0
`schemas` Führen Sie eine Metadatenabfrage zu den Schemas aus. Die tatsächlichen Ergebnisse sollten dann mit `fetchmany` oder `fetchall` abgerufen werden. Wichtige Felder im Resultset sind: – Feldname: `TABLE_SCHEM`. Geben Sie Folgendes ein: `str`. Der Name des Schemas. – Feldname: `TABLE_CATALOG`. Geben Sie Folgendes ein: `str`. Der Katalog, zu dem das Schema gehört. Kein Rückgabewert. Seit Version 1.0 Parameter: `catalog_name` Typ: `str` Ein Katalogname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `schema_name` Typ: `str` Ein Schemaname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional.
`tables` Führen Sie eine Metadatenabfrage zu Tabellen und Sichten aus. Die tatsächlichen Ergebnisse sollten dann mit `fetchmany` oder `fetchall` abgerufen werden. Wichtige Felder im Resultset sind: – Feldname: `TABLE_CAT`. Geben Sie Folgendes ein: `str`. Der Katalog, zu dem die Tabelle gehört. – Feldname: `TABLE_SCHEM`. Geben Sie Folgendes ein: `str`. Das Schema, zu dem die Tabelle gehört. – Feldname: `TABLE_NAME`. Geben Sie Folgendes ein: `str`. Der Name der Tabelle. – Feldname: `TABLE_TYPE`. Geben Sie Folgendes ein: `str`. Die Art der Beziehung, z. B. `VIEW` oder `TABLE` (gilt für die Databricks-Runtime 10.4 LTS und höher sowie für Databricks SQL, frühere Versionen der Databricks-Runtime geben eine leere Zeichenfolge zurück). Kein Rückgabewert. Seit Version 1.0 Parameter `catalog_name` Typ: `str` Ein Katalogname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `schema_name` Typ: `str` Ein Schemaname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `table_name` Typ: `str` Ein Tabellenname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `table_types` Typ: `List[str]` Eine Liste von Tabellentypen, die abgeglichen werden sollen, z. B. `TABLE` oder `VIEW`. Dieser Parameter ist optional.
`columns` Führen Sie eine Metadatenabfrage zu den Spalten aus. Die tatsächlichen Ergebnisse sollten dann mit `fetchmany` oder `fetchall` abgerufen werden. Wichtige Felder im Resultset sind: – Feldname: `TABLE_CAT`. Geben Sie Folgendes ein: `str`. Der Katalog, zu dem die Spalte gehört. – Feldname: `TABLE_SCHEM`. Geben Sie Folgendes ein: `str`. Das Schema, zu dem die Spalte gehört. – Feldname: `TABLE_NAME`. Geben Sie Folgendes ein: `str`. Der Name der Tabelle, zu der die Spalte gehört. – Feldname: `COLUMN_NAME`. Geben Sie Folgendes ein: `str`. Name der Spalte. Kein Rückgabewert. Seit Version 1.0 Parameter: `catalog_name` Typ: `str` Ein Katalogname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `schema_name` Typ: `str` Ein Schemaname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `table_name` Typ: `str` Ein Tabellenname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional. `column_name` Typ: `str` Ein Spaltenname, zu dem Informationen abgerufen werden sollen. Das `%`-Zeichen wird als Platzhalter interpretiert. Dieser Parameter ist optional.
`fetchall` Ruft alle (oder alle verbleibenden) Zeilen einer Abfrage ab. Keine Parameter. Gibt alle (oder alle verbleibenden) Zeilen der Abfrage als Python-`list` aus `Row`-Objekten zurück. Löst einen `Error` aus, wenn beim vorherigen Aufruf der `execute`-Methode keine Daten zurückgegeben wurden oder wenn noch kein `execute`-Aufruf erfolgt ist.
`fetchmany` Ruft die nächsten Zeilen einer Abfrage ab. Gibt bis zur mit dem `size`-Attribut (oder dem `arraysize`-Attribut, wenn `size` nicht angegeben ist) angegebenen Anzahl an nächsten Zeilen einer Abfrage als Python-`list` von `Row`-Objekten zurück. Wenn weniger als `size` Zeilen vorhanden sind, die abgerufen werden sollen, werden alle verbleibenden Zeilen zurückgegeben. Löst einen `Error` aus, wenn beim vorherigen Aufruf der `execute`-Methode keine Daten zurückgegeben wurden oder wenn noch kein `execute`-Aufruf erfolgt ist. Parameter: `size` Typ: `int` Die Anzahl der abzurufenden nächsten Zeilen. Dieser Parameter ist optional. Wenn kein Wert angegeben wird, wird der Wert des `arraysize`-Attributs verwendet. Beispiel: `cursor.fetchmany(10)`
`fetchone` Ruft die nächste Zeile des Datasets ab. Keine Parameter. Gibt die nächste Zeile des Datasets als einzelne Sequenz als Python- `tuple`-Objekt zurück, oder gibt `None` zurück, wenn keine weiteren Daten verfügbar sind. Löst einen `Error` aus, wenn beim vorherigen Aufruf der `execute`-Methode keine Daten zurückgegeben wurden oder wenn noch kein `execute`-Aufruf erfolgt ist.
`fetchall_arrow` Ruft alle (oder alle verbleibenden) Zeilen einer Abfrage als PyArrow-`Table` ab. Bei Abfragen, die sehr große Datenmengen zurückgeben, sollte stattdessen `fetchmany_arrow` verwendet werden, um den Arbeitsspeicherverbrauch zu verringern. Keine Parameter. Gibt alle (oder alle verbleibenden) Zeilen der Abfrage als PyArrow-Tabelle zurück. Löst einen `Error` aus, wenn beim vorherigen Aufruf der `execute`-Methode keine Daten zurückgegeben wurden oder wenn noch kein `execute`-Aufruf erfolgt ist. Seit Version 2.0
`fetchmany_arrow` Ruft die nächsten Zeilen einer Abfrage als PyArrow-`Table`-Objekt ab. Gibt bis zur mit dem `size`-Argument (oder dem `arraysize`-Attribut, wenn `size`-nicht angegeben ist) angegebenen Anzahl an nächsten Zeilen einer Abfrage als Python PyArrow- `Table`-Objekt Löst einen `Error` aus, wenn beim vorherigen Aufruf der `execute`-Methode keine Daten zurückgegeben wurden oder wenn noch kein `execute`-Aufruf erfolgt ist. Seit Version 2.0 Parameter: `size` Typ: `int` Die Anzahl der abzurufenden nächsten Zeilen. Dieser Parameter ist optional. Wenn kein Wert angegeben wird, wird der Wert des `arraysize`-Attributs verwendet. Beispiel: `cursor.fetchmany_arrow(10)`

`Row`-Klasse

Die row-Klasse ist eine tupelähnliche Datenstruktur, die eine einzelne Ergebniszeile darstellt. Wenn die Zeile eine Spalte mit dem Namen "my_column" enthält, können Sie auf das Feld "my_column" von row über row.my_column zugreifen. Sie können ebenso numerische Indizes verwenden, um auf Felder zuzugreifen, z. B row[0]. Wenn der Spaltenname als Attributmethodenname nicht zulässig ist (z. B. weil er mit einer Ziffer beginnt), können Sie auf das Feld als row["1_my_column"] zugreifen.

Seit Version 1.0

Zu den ausgewählten Row-Methoden gehören:

| asDict

Gibt eine Wörterbuchdarstellung der Zeile zurück, die durch Feldnamen indiziert wird. Wenn doppelte Feldnamen vorhanden sind, wird eines der doppelten Felder (aber nur eins) im Wörterbuch zurückgegeben. Welches doppelte Feld zurückgegeben wird, ist nicht definiert.

Keine Parameter.

Gibt ein dict von Feldern zurück. |

Typkonvertierungen

In der folgenden Tabelle werden Apache Spark-SQL-Datentypen den entsprechenden Python-Datentypen zugeordnet.

Apache Spark-SQL-Datentyp	Python-Datentyp
`array`	`numpy.ndarray`
`bigint`	`int`
`binary`	`bytearray`
`boolean`	`bool`
`date`	`datetime.date`
`decimal`	`decimal.Decimal`
`double`	`float`
`int`	`int`
`map`	`str`
`null`	`NoneType`
`smallint`	`int`
`string`	`str`
`struct`	`str`
`timestamp`	`datetime.datetime`
`tinyint`	`int`

Problembehandlung

`tokenAuthWrapperInvalidAccessToken: Invalid access token`-Meldung

Problem: Wenn Sie Ihren Code ausführen, wird eine Meldung ähnlich Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token angezeigt.

Mögliche Ursache: Der an access_token übergebene Wert ist kein gültiges persönliches Azure Databricks-Zugriffstoken.

Empfohlene Korrektur: Überprüfen Sie, ob der an access_token übergebene Wert korrekt ist, und versuchen Sie es dann noch einmal.

`gaierror(8, 'nodename nor servname provided, or not known')`-Meldung

Problem: Wenn Sie Ihren Code ausführen, wird eine Meldung ähnlich Error during request to server: gaierror(8, 'nodename nor servname provided, or not known') angezeigt.

Mögliche Ursache: Der an server_hostname übergebene Wert ist nicht der richtige Hostname.

Empfohlene Korrektur: Überprüfen Sie, ob der an server_hostname übergebene Wert korrekt ist, und versuchen Sie es dann noch einmal.

Weitere Informationen zum Suchen des Hostnamen des Servers finden Sie unter Abrufen von Verbindungsdetails für eine Azure Databricks-Computeressource.

`IpAclError`-Meldung

Problem: Wenn Sie Ihren Code ausführen, wird die Meldung Error during request to server: IpAclValidation angezeigt, wenn Sie versuchen, den Connector auf einem Azure Databricks-Notebook zu verwenden.

Mögliche Ursache: Möglicherweise ist die IP-Positivliste für den Azure Databricks-Arbeitsbereich aktiviert. Bei der IP-Positivliste sind Verbindungen von Spark-Clustern zurück zur Steuerungsebene standardmäßig nicht zulässig.

Empfohlene Korrektur: Bitten Sie Ihre*n Administrator*in, das Computeebenensubnetz der IP-Positivliste hinzuzufügen.

Zusätzliche Ressourcen

Weitere Informationen finden Sie unter

Das Repository Databricks SQL-Connector für Python auf GitHub
Datentypen
Integrierte Typen (für bool, bytearray, float, int und str) auf der Python-Website
datetime (für datetime.date und datatime.datetime) auf der Python-Website
decimal (für decimal.Decimal) auf der Python-Website
Integrierte Konstanten (für NoneType) auf der Python-Website

Freigeben über

Databricks SQL-Connector für Python

Anforderungen

Erste Schritte

Cluster

SQL-Warehouse

Authentifizierung

Authentifizierung mit persönlichen Databricks-Zugriffstoken

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Microsoft Entra ID-Tokenauthentifizierung

OAuth U2M-Authentifizierung (User-to-Machine)

Beispiele

Daten abfragen

Einfügen von Daten

Abfragen von Metadaten

Verwalten von Cursor und Verbindungen

Verwalten von Dateien in Unity Catalog-Volumes

Konfigurieren der Protokollierung

Testen

API-Referenz

Paket

Modul

Klassen

`Connection`-Klasse

`Cursor`-Klasse

`Row`-Klasse

Typkonvertierungen

Problembehandlung

`tokenAuthWrapperInvalidAccessToken: Invalid access token`-Meldung

`gaierror(8, 'nodename nor servname provided, or not known')`-Meldung

`IpAclError`-Meldung

Zusätzliche Ressourcen

Feedback

Zusätzliche Ressourcen

Freigeben über

Databricks SQL-Connector für Python

Anforderungen

Erste Schritte

Cluster

SQL-Warehouse

Authentifizierung

Authentifizierung mit persönlichen Databricks-Zugriffstoken

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Microsoft Entra ID-Tokenauthentifizierung

OAuth U2M-Authentifizierung (User-to-Machine)

Beispiele

Daten abfragen

Einfügen von Daten

Abfragen von Metadaten

Verwalten von Cursor und Verbindungen

Verwalten von Dateien in Unity Catalog-Volumes

Konfigurieren der Protokollierung

Testen

API-Referenz

Paket

Modul

Klassen

Connection-Klasse

Cursor-Klasse

Row-Klasse

Typkonvertierungen

Problembehandlung

tokenAuthWrapperInvalidAccessToken: Invalid access token-Meldung

gaierror(8, 'nodename nor servname provided, or not known')-Meldung

IpAclError-Meldung

Zusätzliche Ressourcen

Feedback

Zusätzliche Ressourcen

`Connection`-Klasse

`Cursor`-Klasse

`Row`-Klasse

`tokenAuthWrapperInvalidAccessToken: Invalid access token`-Meldung

`gaierror(8, 'nodename nor servname provided, or not known')`-Meldung

`IpAclError`-Meldung