Databricks SQL Connector voor Python

De Databricks SQL Connector voor Python is een Python-bibliotheek waarmee u Python-code kunt gebruiken om SQL-opdrachten uit te voeren op azure Databricks all-purpose compute en Databricks SQL Warehouses. De Databricks SQL Connector voor Python is eenvoudiger in te stellen en te gebruiken dan vergelijkbare Python-bibliotheken, zoals pyodbc. Deze bibliotheek volgt PEP 249 – Python Database API Specification v2.0.

Belangrijk

Databricks SQL Connector voor Python versie 3.0.0 en hoger biedt ondersteuning voor systeemeigen uitvoering van geparameteriseerde query's, waardoor SQL-injectie wordt voorkomen en de queryprestaties kunnen worden verbeterd. Eerdere versies gebruikten inline geparameteriseerde uitvoering, die niet veilig is voor SQL-injectie en andere nadelen heeft. Zie Systeemeigen parameters gebruiken voor meer informatie.

De Databricks SQL Connector voor Python ondersteunt ook het SQLAlchemy-dialect voor Azure Databricks, maar deze moet worden geïnstalleerd om deze functies te kunnen gebruiken. Zie SQLAlchemy gebruiken met Azure Databricks.

Vereisten

Een ontwikkelcomputer met Python 3.8 en hoger.
Databricks raadt u aan om virtuele Python-omgevingen te gebruiken, zoals die worden geleverd door venv die zijn opgenomen in Python. Virtuele omgevingen helpen ervoor te zorgen dat u de juiste versies van Python en de Databricks SQL Connector voor Python samen gebruikt. Het instellen en gebruiken van virtuele omgevingen valt buiten het bereik van dit artikel. Zie Virtuele omgevingen maken voor meer informatie.
Een bestaand rekenproces voor alle doeleinden of SQL Warehouse.

Aan de slag

Installeer de Databricks SQL Connector voor Python. PyArrow is een optionele afhankelijkheid van de Databricks SQL Connector voor Python en is niet standaard geïnstalleerd in versie 4.0.0 en hoger van de connector. Als PyArrow niet is geïnstalleerd, zijn functies zoals CloudFetch en andere Apache Arrow-functionaliteit niet beschikbaar. Dit kan van invloed zijn op de prestaties voor grote hoeveelheden gegevens.
- Als u de lean-connector wilt installeren, gebruikt u:
```
pip install databricks-sql-connector
```
- Als u de volledige connector, inclusief PyArrow, wilt installeren, gebruikt u:
```
pip install databricks-sql-connector[pyarrow]
```
Verzamel de volgende informatie voor het rekenproces voor alle doeleinden of SQL Warehouse dat u wilt gebruiken:

Rekenproces voor alle doeleinden
- De serverhostnaam voor veelzijdige computertoepassingen. U kunt deze ophalen uit de serverhostnaamwaarde op het tabblad Geavanceerde opties > JDBC/ODBC voor uw rekenproces voor alle doeleinden.
- Het HTTP-pad van de berekening voor alle doeleinden. U kunt dit ophalen uit de HTTP-padwaarde op het tabblad Geavanceerde opties > JDBC/ODBC voor uw rekenproces voor alle doeleinden.
Notitie

De SQL-connector biedt geen ondersteuning voor het verbinden met de job-computeomgeving.

SQL Warehouse
- De hostnaam van de server van het SQL-warehouse. U kunt deze ophalen uit de serverhostnaamwaarde op het tabblad Verbindingsgegevens voor uw SQL-warehouse.
- Het HTTP-pad van het SQL-warehouse. U kunt dit ophalen uit de waarde van het HTTP-pad op het tabblad Verbindingsgegevens voor uw SQL-warehouse.

Verificatie

De Databricks SQL Connector voor Python ondersteunt de volgende Azure Databricks-verificatietypen:

Verificatie van persoonlijke toegangstokens van Databricks
Verificatie van Microsoft Entra-id-token
OAuth-machine-naar-machine (M2M) authenticatie
OAuth-verificatie van gebruiker naar machine (U2M)

De Databricks SQL Connector voor Python biedt nog geen ondersteuning voor de volgende Azure Databricks-verificatietypen:

Verificatie van persoonlijke toegangstokens van Databricks

Als u de Databricks SQL Connector voor Python wilt gebruiken met persoonlijke toegangstokenverificatie van Azure Databricks, moet u eerst een persoonlijk azure Databricks-toegangstoken maken. Volg hiervoor de stappen in Persoonlijke toegangstokens maken voor werkruimtegebruikers.

Gebruik het volgende codefragment om de Databricks SQL Connector voor Python te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw rekenproces of SQL Warehouse voor alle doeleinden.
DATABRICKS_HTTP_PATH, ingesteld op de waarde van HTTP Path voor uw algemeen rekenproces of SQL Warehouse.
DATABRICKS_TOKEN, ingesteld op het persoonlijke toegangstoken van Azure Databricks.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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-verificatie van machine-naar-machine (M2M)

Databricks SQL Connector voor Python-versies 2.7.0 en hoger ondersteunen OAuth-verificatie van machine-naar-machine (M2M). U moet ook de Databricks SDK voor Python 0.18.0 of hoger installeren (bijvoorbeeld door uit te voeren pip install databricks-sdk of python -m pip install databricks-sdk).

Als u de Databricks SQL Connector voor Python wilt gebruiken met OAuth M2M-verificatie, moet u het volgende doen:

Maak een Azure Databricks-service-principal in uw Azure Databricks-werkruimte en maak een OAuth-geheim voor die service-principal.

Zie Toegang voor service-principal tot Azure Databricks met OAuth autoriseren om de service-principal en het OAuth-geheim te creëren. Noteer de UUID - of toepassings-id van de service-principal en de geheime waarde voor het OAuth-geheim van de service-principal.
Geef die service-principal toegang tot uw rekencentrum of datawarehouse voor algemeen gebruik.

Om de service-principal toegang te geven tot uw algemene rekenvoorziening of magazijn, zie Compute-machtigingen of Beheer een SQL-warehouse.

Gebruik het volgende codefragment om de Databricks SQL Connector voor Python te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

DATABRICKS_SERVER_HOSTNAME ingesteld op de serverhostnaamwaarde voor uw rekenproces of SQL Warehouse voor alle doeleinden.
DATABRICKS_HTTP_PATH, ingesteld op de waarde van HTTP Path voor uw algemeen rekenproces of SQL Warehouse.
DATABRICKS_CLIENT_ID, ingesteld op de UUID- of Applicatie-ID van de serviceprincipal.
DATABRICKS_CLIENT_SECRET, ingesteld op de geheime waarde voor het OAuth-geheim van de service-principal.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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:
# ...

Verificatie van Microsoft Entra-id-token

Als u de Databricks SQL Connector voor Python wilt gebruiken met Microsoft Entra ID-tokenverificatie, moet u de Databricks SQL Connector voor Python opgeven met het Microsoft Entra ID-token. Ga als volgt te werk om een Microsoft Entra ID-toegangstoken te maken:

Voor een Azure Databricks-gebruiker kunt u de Azure CLI gebruiken. Zie Microsoft Entra ID-tokens handmatig ophalen.
Zie Tokens voor Microsoft Entra ID service-principals ophalen. Zie Service-principals voor het maken van een door Microsoft Entra ID beheerde service-principal.

Microsoft Entra ID-tokens hebben een standaardlevensduur van ongeveer 1 uur. Herhaal dit proces om een nieuw Microsoft Entra ID-token te maken.

Gebruik het volgende codefragment om de Databricks SQL Connector voor Python te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

Stel DATABRICKS_SERVER_HOSTNAME in op de waarde van Server Hostname voor uw algemene rekenproces of SQL-warehouse.
Stel DATABRICKS_HTTP_PATH deze waarde in op HTTP-padwaarde voor uw rekenproces voor alle doeleinden of SQL Warehouse.
Stel DATABRICKS_TOKEN in op het Microsoft Entra ID-token.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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-authenticatie van gebruiker naar machine (U2M)

Databricks SQL Connector voor Python-versies 2.7.0 en hoger bieden ondersteuning voor OAuth-gebruikers-naar-machine-verificatie (U2M). U moet ook de Databricks SDK voor Python 0.19.0 of hoger installeren (bijvoorbeeld door uit te voeren pip install databricks-sdk of python -m pip install databricks-sdk).

Gebruik het volgende codefragment om de Databricks SQL Connector voor Python te verifiëren met OAuth U2M-verificatie. OAuth U2M-verificatie maakt gebruik van realtime menselijke aanmelding en toestemming om het Azure Databricks-doelgebruikersaccount te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

Stel DATABRICKS_SERVER_HOSTNAME in op de waarde van Server Hostname voor uw algemene rekenproces of SQL-warehouse.
Stel DATABRICKS_HTTP_PATH deze waarde in op HTTP-padwaarde voor uw rekenproces voor alle doeleinden of SQL Warehouse.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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:
# ...

Voorbeelden

In de volgende codevoorbeelden ziet u hoe u de Databricks SQL Connector voor Python gebruikt om gegevens op te vragen en in te voegen, metagegevens op te vragen, cursors en verbindingen te beheren, bestanden in Unity Catalog te beheren en logboekregistratie te configureren.

Notitie

In de volgende codevoorbeelden ziet u hoe u een persoonlijk toegangstoken van Azure Databricks gebruikt voor verificatie. Zie Verificatie als u een ander verificatietype wilt gebruiken.

In dit codevoorbeeld worden de server_hostnamewaarden en http_pathaccess_tokenverbindingsvariabelen opgehaald uit deze omgevingsvariabelen:

DATABRICKS_SERVER_HOSTNAME, die de serverhostnaamwaarde van de vereisten vertegenwoordigt.
DATABRICKS_HTTP_PATH, die de HTTP-padwaarde van de vereisten vertegenwoordigt.
DATABRICKS_TOKEN, dat uw toegangstoken aangeeft op basis van de vereisten.

User-Agent instellen

In het volgende codevoorbeeld ziet u hoe u de User-Agent-toepassing instelt product_name voor het bijhouden van gebruik.

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"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

Gegevens opvragen

In het volgende codevoorbeeld ziet u hoe u de Databricks SQL Connector voor Python aanroept om een eenvoudige SQL-opdracht uit te voeren op rekenkracht of SQL Warehouse voor alle doeleinden. Met deze opdracht worden de eerste twee rijen uit de trips tabel in het samples schema van de nyctaxi catalogus geretourneerd.

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)

Querytags

Belangrijk

Deze functie bevindt zich in Private Preview. Neem contact op met uw accountteam om toegang aan te vragen.

In het volgende voorbeeld ziet u hoe u sleutelwaardetags koppelt aan uw SQL-query's voor tracerings- en analysedoeleinden. Querytags worden weergegeven in de system.query.history tabel.

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"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

Gegevens invoegen

In het volgende voorbeeld ziet u hoe u kleine hoeveelheden gegevens kunt invoegen (duizenden rijen):

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)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    cursor.execute("SELECT * FROM squares LIMIT ?", [10])

    result = cursor.fetchall()

    for row in result:
      print(row)

Voor grote hoeveelheden gegevens moet u eerst de gegevens uploaden naar cloudopslag en vervolgens de opdracht COPY INTO uitvoeren.

Metagegevens opvragen

Er zijn speciale methoden voor het ophalen van metagegevens. In het volgende voorbeeld worden metagegevens opgehaald over kolommen in een voorbeeldtabel:

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())

Cursors en verbindingen beheren

Het is een best practice om verbindingen en cursors te sluiten die niet meer in gebruik zijn. Hierdoor worden resources vrijgemaakt op de all-purpose compute van Azure Databricks en de Databricks SQL-warehouses.

U kunt een contextbeheer (de with syntaxis die in eerdere voorbeelden wordt gebruikt) gebruiken om de resources te beheren of expliciet aanroepen close:

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()

Bestanden beheren in Unity Catalog-volumes

Met de Databricks SQL Connector kunt u lokale bestanden schrijven naar Unity Catalog-volumes, bestanden downloaden van volumes en bestanden verwijderen uit volumes, zoals wordt weergegeven in het volgende voorbeeld:

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allowed_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_allowed_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 '/tmp/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'"
    )

Logboekregistratie configureren

De Databricks SQL Connector maakt gebruik van de standaardmodule voor logboekregistratie van Python. In het volgende voorbeeld wordt het logboekniveau geconfigureerd en wordt een foutopsporingslogboek gegenereerd:

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

Als u uw code wilt testen, gebruikt u Python-testframeworks zoals pytest. Als u uw code wilt testen onder gesimuleerde omstandigheden zonder Azure Databricks REST API-eindpunten aan te roepen of de status van uw Azure Databricks-accounts of -werkruimten te wijzigen, kunt u Python-mockbibliotheken zoals unittest.mock gebruiken.

Bijvoorbeeld, gegeven het volgende bestand met de naam helpers.py dat een get_connection_personal_access_token functie bevat die een persoonlijk toegangstoken van Azure Databricks gebruikt om een verbinding met een Azure Databricks-werkruimte tot stand te brengen, en een select_nyctaxi_trips functie die de verbinding gebruikt om het opgegeven aantal gegevensrijen op te halen uit de trips tabel binnen het samples catalogus' nyctaxi schema:

# 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("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

En gezien het volgende bestand met de naam main.py die de get_connection_personal_access_token en select_nyctaxi_trips functies aanroept:

# 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)

Het volgende bestand met de naam test_helpers.py test of de select_nyctaxi_trips functie het verwachte antwoord retourneert. In plaats van een echte verbinding met de doelwerkruimte te maken, wordt met deze test een Connection object gesimuleerd. Met de test worden ook enkele gegevens gesimuleerd die voldoen aan het schema en de waarden die zich in de echte gegevens bevinden. De test retourneert de gesimuleerde gegevens via de gesimuleerde verbinding en controleert vervolgens of een van de gesimuleerde gegevensrijen overeenkomt met de verwachte waarde.

# 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

Omdat de select_nyctaxi_trips functie een SELECT instructie bevat en daarom de status van de trips tabel niet wijzigt, is mocking niet absoluut vereist in dit voorbeeld. Met mocking kunt u uw tests echter snel uitvoeren zonder te wachten tot er een werkelijke verbinding met de werkruimte is gemaakt. Met mocking kunt u ook meerdere keren gesimuleerde tests uitvoeren voor functies die de status van een tabel kunnen wijzigen, zoals INSERT INTO, UPDATEen DELETE FROM.

API-verwijzing

Deze sectie bevat API-verwijzing voor het databricks-sql-connector pakket. Zie databricks-sql-connector in de Python Package Index (PyPI).

Moduul

De databricks.sql module van het databricks-sql-connector pakket bevat de methode voor het initialiseren van een verbinding met een SQL Warehouse.

verbindingsmethode

Initialiseert een verbinding met een SQL Warehouse. Hiermee wordt een verbindingsobject geretourneerd.

Kenmerk	Typologie	Description
`server_hostname`	`str`	Verplicht. De serverhostnaam voor de rekenkracht voor alle doeleinden of SQL Warehouse, bijvoorbeeld `adb-1234567890123456.7.azuredatabricks.net`. Zie de instructies in Aan de slag om de hostnaam van de server op te halen.
`http_path`	`str`	Verplicht. Het HTTP-pad van het rekenproces voor alle doeleinden of SQL Warehouse, bijvoorbeeld `sql/protocolv1/o/1234567890123456/1234-567890-test123` voor berekeningen voor alle doeleinden of `/sql/1.0/warehouses/a1b234c567d8e9fa` voor een SQL-warehouse. Zie de instructies in Aan de slag om het HTTP-pad op te halen.
`access_token` `auth_type`, `credentials_provider`, `passwordusername`	`str`	Informatie over azure Databricks-verificatie-instellingen. Zie Verificatie voor meer informatie.
`session_configuration`	`dict[str, Any]`	Een woordenlijst met spark-sessieconfiguratieparameters. Het instellen van een configuratie is gelijk aan het gebruik van de `SET key=val` SQL-opdracht. Voer de SQL-opdracht `SET -v` uit om een volledige lijst met beschikbare configuraties op te halen. Standaard ingesteld op `None`. Voorbeeld: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Optional. Aanvullende paren (sleutel, waarde) die moeten worden ingesteld in HTTP-headers op elke RPC-aanvraag die de client doet. Normaal gesproken worden er geen extra HTTP-headers ingesteld. Standaard ingesteld op `None`.
`catalog`	`str`	Optional. De eerste catalogus die moet worden gebruikt voor de verbinding. Standaard ingesteld op `None` (in welk geval de standaardcatalogus, typisch `hive_metastore`, zal worden gebruikt).
`schema`	`str`	Optional. Het eerste schema dat moet worden gebruikt voor de verbinding. Wordt standaard ingesteld op `None` (in dat geval wordt het standaardschema `default` gebruikt). Sinds versie 2.0
`use_cloud_fetch`	`bool`	Optional. Of u aanvragen voor ophalen rechtstreeks naar het cloudobjectarchief wilt verzenden om segmenten met gegevens te downloaden. Standaard ingesteld op `True`. Stel in op `False` om ophaalaanvragen direct naar Azure Databricks te verzenden. Als `use_cloud_fetch` is ingesteld op `True`, maar netwerktoegang wordt geblokkeerd, zullen de ophaalaanvragen mislukken. Sinds versie 2.8
`user_agent_entry`	`str`	Optional. De User-Agent vermelding die moet worden opgenomen in de HTTP-aanvraagheader voor het bijhouden van gebruik. Standaard ingesteld op `PyDatabricksSqlConnector`.

`Connection` klas

Vertegenwoordigt een verbinding met compute of een SQL Warehouse.

Methoden

De Connection klasse biedt de volgende methoden.

Methode	Description
`close`	Hiermee sluit u de verbinding met de database en worden alle gekoppelde resources op de server vrijgegeven. Eventuele extra aanroepen naar deze verbinding leiden tot een `Error`. Geen parameters. Geen retourwaarde.
`cursor`	Retourneert een nieuw Cursor-object waarmee doorkruising van de records in een database mogelijk is. Geen parameters.

`Cursor` klas

Vertegenwoordigt een mechanisme om gegevensrecords te doorlopen.

Als u een Cursor object wilt maken, roept u de cursor methode van de klasse Connection aan.

Kenmerken

Geselecteerde Cursor kenmerken omvatten het volgende:

Attribute Description

arraysize Wordt gebruikt met de fetchmany methode, geeft de interne buffergrootte op, wat ook het aantal rijen dat daadwerkelijk van de server tegelijk wordt opgehaald. De standaardwaarde is 10000. Voor smalle resultaten (resultaten waarin elke rij niet veel gegevens bevat), moet u deze waarde verhogen voor betere prestaties. Lees-schrijftoegang.

Attribute	Description
`arraysize`	Wordt gebruikt met de `fetchmany` methode, geeft de interne buffergrootte op, wat ook het aantal rijen dat daadwerkelijk van de server tegelijk wordt opgehaald. De standaardwaarde is `10000`. Voor smalle resultaten (resultaten waarin elke rij niet veel gegevens bevat), moet u deze waarde verhogen voor betere prestaties. Lees-schrijftoegang.
`description`	Bevat een Python `list` met `tuple` objecten. Elk van deze `tuple` objecten bevat 7 waarden, waarbij de eerste twee items van elk `tuple` object informatie over één resultaatkolom als volgt beschrijft: `name`: de naam van de kolom. `type_code`: een tekenreeks die het type kolom aangeeft. Een kolom met een geheel getal heeft bijvoorbeeld een typecode van `int`. De overige vijf items van elk 7-itemobject `tuple` worden niet geïmplementeerd en hun waarden worden niet gedefinieerd. Ze worden meestal geretourneerd als 4 `None` waarden, gevolgd door één `True` waarde. Alleen-lezentoegang.

description

Bevat een Python list met tuple objecten. Elk van deze tuple objecten bevat 7 waarden, waarbij de eerste twee items van elk tuple object informatie over één resultaatkolom als volgt beschrijft:

name: de naam van de kolom.
type_code: een tekenreeks die het type kolom aangeeft. Een kolom met een geheel getal heeft bijvoorbeeld een typecode van int. De overige vijf items van elk 7-itemobject tuple worden niet geïmplementeerd en hun waarden worden niet gedefinieerd. Ze worden meestal geretourneerd als 4 None waarden, gevolgd door één True waarde. Alleen-lezentoegang.

Methoden

Geselecteerde Cursor methoden omvatten het volgende:

Methode	Description
`cancel`	Onderbreekt het uitvoeren van een databasequery of opdracht die door de cursor is gestart. Als u de gekoppelde resources op de server wilt vrijgeven, roept u de `close` methode aan nadat u de methode hebt `cancel` aangeroepen. Geen parameters. Geen retourwaarde.
`close`	Hiermee sluit u de cursor en worden de bijbehorende resources op de server vrijgegeven. Als u een al gesloten cursor sluit, kan er een fout optreden. Geen parameters. Geen retourwaarde.
`execute`	Bereidt een databasequery of opdracht voor en voert deze vervolgens uit. Parameters: `operation`: Vereist. De query of opdracht om voor te bereiden en vervolgens uit te voeren. Type: `str` Voorbeeld zonder de `parameters` parameter: `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Voorbeeld met de `parameters` parameter (met behulp van systeemeigen positionele parameters): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: optioneel. Een reeks parameters die moeten worden gebruikt met de `operation` parameter. De standaardwaarde is `None`. Typ: `dictionary` Geen retourwaarde.
`executemany`	Bereidt en voert vervolgens een databasequery of opdracht uit met behulp van alle parameterreeksen in het `seq_of_parameters` argument. Alleen de uiteindelijke resultatenset wordt bewaard. Parameters: `operation`: Vereist. De query of opdracht om voor te bereiden en vervolgens uit te voeren. Typ: `str` `seq_of_parameters`: Vereist. Een reeks van veel sets parameterwaarden die moeten worden gebruikt met de `operation` parameter. Type: `list` van `dict` Geen retourwaarde.
`catalogs`	Voer een metagegevensquery uit over de catalogi. De werkelijke resultaten moeten vervolgens worden opgehaald met `fetchmany` of `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: Veldnaam: `TABLE_CAT`. De naam van de catalogus. Typ: `str` Geen parameters. Geen retourwaarde. Sinds versie 1.0
`schemas`	Voer een metagegevensquery uit over de schema's. De werkelijke resultaten moeten vervolgens worden opgehaald met `fetchmany` of `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: Veldnaam: `TABLE_SCHEM`. De naam van het schema. Typ: `str` Veldnaam: `TABLE_CATALOG`. De catalogus waartoe het schema behoort. Typ: `str` Parameters: `catalog_name`: optioneel. Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `schema_name`: optioneel. Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` Geen retourwaarde. Sinds versie 1.0
`tables`	Voer een metagegevensquery uit over tabellen en weergaven. De werkelijke resultaten moeten vervolgens worden opgehaald met `fetchmany` of `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: Veldnaam: `TABLE_CAT`. De catalogus waartoe de tabel behoort. Typ: `str` Veldnaam: `TABLE_SCHEM`. Het schema waartoe de tabel behoort. Typ: `str` Veldnaam: `TABLE_NAME`. De naam van de tabel. Typ: `str` Veldnaam: `TABLE_TYPE`. Het soort relatie, bijvoorbeeld `VIEW` of `TABLE` (van toepassing op Databricks Runtime 10.4 LTS en hoger, evenals op Databricks SQL; eerdere versies van Databricks Runtime retourneren een lege tekenreeks). Typ: `str` Parameters: `catalog_name`: optioneel. Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `schema_name`: optioneel. Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `table_name`: optioneel. Een tabelnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `table_types`: optioneel. Een lijst met tabeltypen die overeenkomen, bijvoorbeeld `TABLE` of `VIEW`. Typ: `List[str]` Geen retourwaarde. Sinds versie 1.0
`columns`	Voer een metagegevensquery uit over de kolommen. De werkelijke resultaten moeten vervolgens worden opgehaald met `fetchmany` of `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: Veldnaam: `TABLE_CAT`. De catalogus waartoe de kolom behoort. Typ: `str` Veldnaam: `TABLE_SCHEM`. Het schema waartoe de kolom behoort. Typ: `str` Veldnaam: `TABLE_NAME`. De naam van de tabel waartoe de kolom behoort. Typ: `str` Veldnaam: `COLUMN_NAME`. De naam van de kolom. Typ: `str` Parameters: `catalog_name`: optioneel. Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `schema_name`: optioneel. Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `table_name`: optioneel. Een tabelnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` `column_name`: optioneel. Een kolomnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Typ: `str` Geen retourwaarde. Sinds versie 1.0
`fetchall`	Hiermee haalt u alle (of alle resterende) rijen van een query op. Geen parameters. Retourneert alle (of alle resterende) rijen van de query als python `list` van `Row` objecten. Genereert een `Error` als de vorige aanroep naar de `execute` methode geen gegevens heeft geretourneerd of er nog geen `execute` aanroep is gedaan.
`fetchmany`	Hiermee haalt u de volgende rijen van een query op. Parameters: `size`: optioneel. Het aantal volgende rijen dat moet worden opgehaald. Als dit niet is opgegeven, wordt de waarde van het `arraysize` kenmerk gebruikt. Type: `int`. Voorbeeld: `cursor.fetchmany(10)` Retourneert maximaal `size` (of het `arraysize` kenmerk als `size` niet is opgegeven) van de volgende rijen van een query als een Python `list` met `Row` objecten. Als er minder rijen `size` over zijn om op te halen, worden alle resterende rijen geretourneerd. Genereert een `Error` als de vorige aanroep naar de `execute` methode geen gegevens heeft geretourneerd of er nog geen `execute` aanroep is gedaan.
`fetchone`	Hiermee haalt u de volgende rij van de gegevensset op. Geen parameters. Retourneert de volgende rij van de gegevensset als één reeks als een Python-object `tuple` of retourneert `None` als er geen beschikbare gegevens meer zijn. Genereert een `Error` als de vorige aanroep naar de `execute` methode geen gegevens heeft geretourneerd of er nog geen `execute` aanroep is gedaan.
`fetchall_arrow`	Hiermee worden alle (of alle resterende) rijen van een query opgehaald als een PyArrow-object `Table` . Query's die zeer grote hoeveelheden gegevens retourneren, moeten in plaats daarvan worden gebruikt `fetchmany_arrow` om het geheugenverbruik te verminderen. Geen parameters. Retourneert alle (of alle resterende) rijen van de query als een PyArrow-tabel. Genereert een `Error` als de vorige aanroep naar de `execute` methode geen gegevens heeft geretourneerd of er nog geen `execute` aanroep is gedaan. Sinds versie 2.0
`fetchmany_arrow`	Hiermee haalt u de volgende rijen van een query op als een PyArrow-object `Table` . Parameters: `size`: optioneel. Het aantal volgende rijen dat moet worden opgehaald. Als dit niet is opgegeven, wordt de waarde van het `arraysize` kenmerk gebruikt. Type: `int`. Voorbeeld: `cursor.fetchmany_arrow(10)` Retourneert tot het `size`-argument (of het `arraysize`-kenmerk als `size` niet is opgegeven) van de volgende rijen van een query als een Python-PyArrow `Table`-object. Genereert een `Error` als de vorige aanroep naar de `execute` methode geen gegevens heeft geretourneerd of er nog geen `execute` aanroep is gedaan. Sinds versie 2.0

`Row` klas

De rijklasse is een tuple-achtige gegevensstructuur die een afzonderlijke resultaatrij in een SQL-queryresultaat vertegenwoordigt. Als de rij een kolom met de naam "my_column"bevat, kunt u het "my_column" veld row openen via row.my_column. U kunt ook numerieke indicies gebruiken om bijvoorbeeld row[0]toegang te krijgen tot velden. Als de kolomnaam niet is toegestaan als de naam van een kenmerkmethode (bijvoorbeeld begint met een cijfer), hebt u toegang tot het veld als row["1_my_column"].

Sinds versie 1.0

Geselecteerde Row methoden zijn onder andere:

Methoden

Methode	Description
`asDict`	Retourneert een woordenlijstweergave van de rij, die wordt geïndexeerd op veldnamen. Als er dubbele veldnamen zijn, wordt een van de dubbele velden (maar slechts één) geretourneerd in de woordenlijst. Welk duplicaatveld wordt geretourneerd, is niet gedefinieerd.

Typeconversies

De volgende tabel wijst Apache Spark SQL-gegevenstypen toe aan hun Python-gegevenstype-equivalenten.

Apache Spark SQL-gegevenstype	Python-gegevenstype
`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`

Telemetrieverzameling

De Databricks SQL Connector voor Python verzamelt telemetriegegevens om Azure Databricks te helpen de betrouwbaarheid te verbeteren en problemen op te lossen. Telemetrie is standaard ingeschakeld en verzamelt de volgende operationele gegevens:

Details van clientomgevingen, zoals stuurprogrammaversie, Python-runtime en besturingssysteem
Verbindingsconfiguraties voor stuurprogramma's (met uitzondering van persoonsgegevens)
Latentiemetingen voor bewerkingen
Indelingen voor uitvoerresultaten, zoals inline JSON of Apache Arrow
Bewerkingstypen, zoals het uitvoeren van query's, metagegevensquery's of volumebewerkingen.
Foutclassificatiegegevens
Aantal nieuwe pogingen

Belangrijk

Azure Databricks verzamelt geen query-inhoud, queryresultaten of persoonlijke gegevens (PII) via telemetrie.

Als u telemetrieverzameling wilt uitschakelen, stelt u de enable_telemetry parameter 0 in op bij het maken van een verbinding.

Probleemoplossing en Diagnose

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Bericht

Probleem: wanneer u uw code uitvoert, ziet u een bericht dat lijkt op Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Mogelijke oorzaak: de doorgegeven waarde naar access_token is geen geldig persoonlijk toegangstoken voor Azure Databricks.

Aanbevolen oplossing: controleer of de waarde die is access_token doorgegeven juist is en probeer het opnieuw.

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

Probleem: wanneer u uw code uitvoert, ziet u een bericht dat lijkt op Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Mogelijke oorzaak: de doorgegeven server_hostname waarde is niet de juiste hostnaam.

Aanbevolen oplossing: controleer of de waarde die is server_hostname doorgegeven juist is en probeer het opnieuw.

Zie Verbindingsgegevens ophalen voor een Azure Databricks-rekenresource voor meer informatie over het vinden van de hostnaam van de server.

`IpAclError` Bericht

Probleem: wanneer u uw code uitvoert, ziet u het bericht Error during request to server: IpAclValidation wanneer u de connector probeert te gebruiken in een Azure Databricks-notebook.

Mogelijke oorzaak: er is mogelijk ip-acceptatie ingeschakeld voor de Azure Databricks-werkruimte. Bij gebruik van IP-allowlisting zijn verbindingen van Spark-clusters terug naar het controlevlak niet standaard toegestaan.

Aanbevolen oplossing: vraag de beheerder om het subnet van het rekenvlak toe te voegen aan de acceptatielijst voor IP-adressen.

Aanvullende bronnen

Zie voor meer informatie:

De Databricks SQL Connector voor Python-opslagplaats op GitHub
Gegevenstypen
Ingebouwde typen (voor, bool, bytearray, en floatint) op de str
datum/tijd (voor datetime.date en datatime.datetime) op de Python-website
decimaal (voor decimal.Decimal) op de Python-website
Ingebouwde constanten (voor NoneType) op de Python-website

Feedback

Is deze pagina nuttig?

Last updated on 2025-10-31

Delen via

Databricks SQL Connector voor Python

Vereisten

Aan de slag

Rekenproces voor alle doeleinden

SQL Warehouse

Verificatie

Verificatie van persoonlijke toegangstokens van Databricks

OAuth-verificatie van machine-naar-machine (M2M)

Verificatie van Microsoft Entra-id-token

OAuth-authenticatie van gebruiker naar machine (U2M)

Voorbeelden

User-Agent instellen

Gegevens opvragen

Querytags

Gegevens invoegen

Metagegevens opvragen

Cursors en verbindingen beheren

Bestanden beheren in Unity Catalog-volumes

Logboekregistratie configureren

Testen

API-verwijzing

Moduul

verbindingsmethode

Connection klas

Methoden

Cursor klas

Kenmerken

Methoden

Row klas

Methoden

Typeconversies

Telemetrieverzameling

Probleemoplossing en Diagnose

tokenAuthWrapperInvalidAccessToken: Invalid access token Bericht

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

IpAclError Bericht

Aanvullende bronnen

Feedback

Aanvullende resources

`Connection` klas

`Cursor` klas

`Row` klas

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Bericht

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

`IpAclError` Bericht