Databricks SQL Connector voor Python

Artikel
10/10/2024

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-clusters 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.

Notitie

De Databricks SQL Connector voor Python bevat ook een SQLAlchemy-dialect voor Azure Databricks. Zie SQLAlchemy gebruiken met Azure Databricks.

Vereisten

Een ontwikkelcomputer met Python >=3.8 en <=3.11.
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 cluster of SQL-magazijn.

Aan de slag

Installeer de Databricks SQL Connector voor Python-bibliotheek op uw ontwikkelcomputer door deze uit te voeren pip install databricks-sql-connector of python -m pip install databricks-sql-connector.
Verzamel de volgende informatie voor het cluster of SQL Warehouse dat u wilt gebruiken:

Cluster
- De hostnaam van de server van het cluster. U kunt deze ophalen uit de serverhostnaamwaarde op het tabblad Geavanceerde opties > JDBC/ODBC voor uw cluster.
- Het HTTP-pad van het cluster. U kunt dit ophalen uit de waarde van het HTTP-pad op het tabblad Geavanceerde opties > JDBC/ODBC voor uw cluster.
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-verificatie van machine-naar-machine (M2M)
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 als volgt een persoonlijk Azure Databricks-toegangstoken maken:

Klik in uw Azure Databricks-werkruimte op uw Azure Databricks-gebruikersnaam in de bovenste balk en selecteer vervolgens Instellingen in de vervolgkeuzelijst.
Klik op Ontwikkelaars.
Klik naast Access-tokens op Beheren.
Klik op Nieuw token genereren.
(Optioneel) Voer een opmerking in waarmee u dit token in de toekomst kunt identificeren en de standaardlevensduur van het token van 90 dagen kunt wijzigen. Als u een token zonder levensduur wilt maken (niet aanbevolen), laat u het vak Levensduur (dagen) leeg (leeg).
Klik op Genereren.
Kopieer het weergegeven token naar een veilige locatie en klik vervolgens op Gereed.

Notitie

Zorg ervoor dat u het gekopieerde token op een veilige locatie opslaat. Deel uw gekopieerde token niet met anderen. Als u het gekopieerde token kwijtraakt, kunt u dat token niet opnieuw genereren. In plaats daarvan moet u deze procedure herhalen om een nieuw token te maken. Als u het gekopieerde token kwijtraakt of als u denkt dat het token is aangetast, raadt Databricks u ten zeerste aan dat u dat token onmiddellijk uit uw werkruimte verwijdert door te klikken op het prullenbakpictogram (Intrekken) naast het token op de pagina Toegangstokens .

Als u geen tokens in uw werkruimte kunt maken of gebruiken, kan dit komen doordat uw werkruimtebeheerder tokens heeft uitgeschakeld of u geen toestemming hebt gegeven om tokens te maken of te gebruiken. Raadpleeg uw werkruimtebeheerder of de volgende onderwerpen:

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 cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster 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 tot Azure Databricks verifiëren met een service-principal met behulp van OAuth (OAuth M2M) om de service-principal en het bijbehorende OAuth-geheim te maken. 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 cluster of magazijn.

Als u de service-principal toegang wilt geven tot uw cluster of magazijn, raadpleegt u Compute-machtigingen of beheert u 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 cluster of SQL Warehouse.
DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.
DATABRICKS_CLIENT_ID, ingesteld op de UUID- of toepassings-id van de service-principal.
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 ophalen voor gebruikers met behulp van de Azure CLI.
Zie Een Microsoft Entra ID-toegangstoken ophalen met de Azure CLI voor een Service-principal van Microsoft Entra ID. Zie Service-principals beheren om een door Microsoft Entra ID beheerde service-principals te maken.

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 deze waarde in op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
Ingesteld DATABRICKS_HTTP_PATH op HTTP-padwaarde voor uw cluster of SQL Warehouse.
Ingesteld DATABRICKS_TOKEN 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-verificatie 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 deze waarde in op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
Ingesteld DATABRICKS_HTTP_PATH op HTTP-padwaarde voor uw cluster 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 en logboekregistratie te configureren.

Notitie

In de volgende codevoorbeelden ziet u hoe u een persoonlijk toegangstoken van Azure Databricks gebruikt voor verificatie. Als u in plaats daarvan andere beschikbare Azure Databricks-verificatietypen wilt gebruiken, raadpleegt u Verificatie.

In dit codevoorbeeld worden de server_hostnamewaarden en access_token http_pathverbindingsvariabelen 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.

U kunt andere methoden gebruiken om deze verbindingsvariabelewaarden op te halen. Het gebruik van omgevingsvariabelen is slechts één benadering tussen veel.

Query's uitvoeren op gegevens
Gegevens invoegen
Querymetagegevens
Cursors en verbindingen beheren
Bestanden beheren in Unity Catalog-volumes
Logboekregistratie configureren

Querygegevens

In het volgende codevoorbeeld ziet u hoe u de Databricks SQL Connector voor Python aanroept om een eenvoudige SQL-opdracht uit te voeren op een cluster of SQL Warehouse. Met deze opdracht worden de eerste twee rijen uit de trips tabel in het schema van nyctaxi de samples 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)

Gegevens invoegen

In het volgende voorbeeld ziet u hoe u kleine hoeveelheden gegevens invoegt (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)]
    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)

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

Querymetagegevens

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. Hiermee worden resources op Azure Databricks-clusters en Databricks SQL-warehouses vrijgemaakt.

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_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'"
    )

Logboekregistratie configureren

De Databricks SQL Connector maakt gebruik van de standaardmodule voor logboekregistratie van Python. U kunt het logboekregistratieniveau configureren dat vergelijkbaar is met het volgende:

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.

Op basis van het volgende bestand met de naam helpers.py van een functie die gebruikmaakt van een get_connection_personal_access_token persoonlijk toegangstoken van Azure Databricks om een verbinding met een Azure Databricks-werkruimte te retourneren, en een select_nyctaxi_trips functie die gebruikmaakt van de verbinding om het opgegeven aantal gegevensrijen op te halen uit de trips tabel in het schema van nyctaxi de samples catalogus:

# 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

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.

Pakket

databricks-sql-connector

Gebruik: pip install databricks-sql-connector

Zie ook databricks-sql-connector in de Python Package Index (PyPI).

Module

databricks.sql

Gebruik: from databricks import sql

Klassen

Geselecteerde klassen omvatten het volgende:

Klassen
`Connection` Een sessie op een Azure Databricks-rekenresource.
`Cursor` Een mechanisme voor het doorkruisen van gegevensrecords.
`Row` Een rij met gegevens in een SQL-queryresultaat.

`Connection` klas

Als u een Connection object wilt maken, roept u de databricks.sql.connect methode aan met de volgende parameters:

Parameters
`server_hostname` Type: `str` De serverhostnaam voor het cluster of SQL Warehouse. Zie de instructies eerder in dit artikel om de hostnaam van de server op te halen. Deze parameter is vereist. Voorbeeld: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Type: `str` Het HTTP-pad van het cluster of SQL Warehouse. Zie de instructies eerder in dit artikel om het HTTP-pad op te halen. Deze parameter is vereist. Voorbeeld: `sql/protocolv1/o/1234567890123456/1234-567890-test123` voor een cluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` voor een SQL Warehouse.
`access_token`, `auth_type` Type: `str` Informatie over azure Databricks-verificatie-instellingen. Zie Verificatie voor meer informatie.
`session_configuration` Type: `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`. Deze parameter is optioneel. Voorbeeld: `{"spark.sql.variable.substitute": True}`
`http_headers` Type: `List[Tuple[str, str]]]` 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`. Deze parameter is optioneel. Sinds versie 2.0
`catalog` Type: `str` De eerste catalogus die moet worden gebruikt voor de verbinding. Standaard ingesteld `None` op (in dat geval wordt de standaardcatalogus meestal `hive_metastore`gebruikt). Deze parameter is optioneel. Sinds versie 2.0
`schema` Type: `str` Het eerste schema dat moet worden gebruikt voor de verbinding. Standaard ingesteld `None` op (in dat geval wordt het standaardschema `default` gebruikt). Deze parameter is optioneel. Sinds versie 2.0
`use_cloud_fetch` Type: `bool` `True` om ophaalaanvragen rechtstreeks naar het cloudobjectarchief te verzenden om segmenten met gegevens te downloaden. `False` (de standaardinstelling) om aanvragen voor ophalen rechtstreeks naar Azure Databricks te verzenden. Als `use_cloud_fetch` deze optie is ingesteld `True` op maar netwerktoegang wordt geblokkeerd, mislukken de ophaalaanvragen. Sinds versie 2.8

Geselecteerde Connection methoden omvatten het volgende:

Methoden
`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 dat doorkruising via de records in een database mogelijk maakt. Geen parameters.

`Cursor` klas

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

Geselecteerde Cursor kenmerken omvatten het volgende:

Kenmerken

Kenmerken
`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 met informatie over één resultaatkolom als volgt beschrijven: - `name`: De naam van de kolom. - `type_code`: Een tekenreeks die het type van de 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.

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 met informatie over één resultaatkolom als volgt beschrijven:

- name: De naam van de kolom.
- type_code: Een tekenreeks die het type van de 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.

Geselecteerde Cursor methoden omvatten het volgende:

Methoden
`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 na het aanroepen van de `cancel` methode. 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 en voert vervolgens een databasequery of opdracht uit. Geen retourwaarde. Parameters: `operation` Type: `str` De query of opdracht om de query of opdracht voor te bereiden en vervolgens uit te voeren. Deze parameter is vereist. Voorbeeld zonder de `parameters` parameter: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Voorbeeld met de `parameters` parameter: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Type: woordenlijst Een reeks parameters die moeten worden gebruikt met de `operation` parameter. Deze parameter is optioneel. De standaardwaarde is `None`.
`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. Geen retourwaarde. Parameters: `operation` Type: `str` De query of opdracht om de query of opdracht voor te bereiden en vervolgens uit te voeren. Deze parameter is vereist. `seq_of_parameters` Type: `list` van `dict` Een reeks van veel sets parameterwaarden die moeten worden gebruikt met de `operation` parameter. Deze parameter is vereist.
`catalogs` Voer een metagegevensquery uit over de catalogi. De werkelijke resultaten moeten vervolgens worden opgehaald met of `fetchmany` `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: - Veldnaam: `TABLE_CAT`. Type: `str`. De naam van de catalogus. 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 of `fetchmany` `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: - Veldnaam: `TABLE_SCHEM`. Type: `str`. De naam van het schema. - Veldnaam: `TABLE_CATALOG`. Type: `str`. De catalogus waartoe het schema behoort. Geen retourwaarde. Sinds versie 1.0 Parameters: `catalog_name` Type: `str` Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `schema_name` Type: `str` Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel.
`tables` Voer een metagegevensquery uit over tabellen en weergaven. De werkelijke resultaten moeten vervolgens worden opgehaald met of `fetchmany` `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: - Veldnaam: `TABLE_CAT`. Type: `str`. De catalogus waartoe de tabel behoort. - Veldnaam: `TABLE_SCHEM`. Type: `str`. Het schema waartoe de tabel behoort. - Veldnaam: `TABLE_NAME`. Type: `str`. De naam van de tabel. - Veldnaam: `TABLE_TYPE`. Type: `str`. 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). Geen retourwaarde. Sinds versie 1.0 Parameters `catalog_name` Type: `str` Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `schema_name` Type: `str` Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `table_name` Type: `str` Een tabelnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `table_types` Type: `List[str]` Een lijst met tabeltypen die overeenkomen, bijvoorbeeld `TABLE` of `VIEW`. Deze parameter is optioneel.
`columns` Voer een metagegevensquery uit over de kolommen. De werkelijke resultaten moeten vervolgens worden opgehaald met of `fetchmany` `fetchall`. Belangrijke velden in de resultatenset zijn onder andere: - Veldnaam: `TABLE_CAT`. Type: `str`. De catalogus waartoe de kolom behoort. - Veldnaam: `TABLE_SCHEM`. Type: `str`. Het schema waartoe de kolom behoort. - Veldnaam: `TABLE_NAME`. Type: `str`. De naam van de tabel waartoe de kolom behoort. - Veldnaam: `COLUMN_NAME`. Type: `str`. De naam van de kolom. Geen retourwaarde. Sinds versie 1.0 Parameters: `catalog_name` Type: `str` Een catalogusnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `schema_name` Type: `str` Een schemanaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `table_name` Type: `str` Een tabelnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel. `column_name` Type: `str` Een kolomnaam voor het ophalen van informatie over. Het `%` teken wordt geïnterpreteerd als een jokerteken. Deze parameter is optioneel.
`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. Retourneert maximaal `size` (of het `arraysize` kenmerk als `size` dit niet is opgegeven) van de volgende rijen van een query als Python `list` van `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. Parameters: `size` Type: `int` Het aantal volgende rijen dat moet worden weergegeven. Deze parameter is optioneel. Als dit niet is opgegeven, wordt de waarde van het `arraysize` kenmerk gebruikt. Voorbeeld: `cursor.fetchmany(10)`
`fetchone` Hiermee haalt u de volgende rij van de gegevensset op. Geen parameters. Retourneert de volgende rij van de gegevensset als één reeks als python `tuple` object of retourneert `None` als er geen gegevens meer beschikbaar 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` . Retourneert het `size` argument (of het `arraysize` kenmerk als `size` dit niet is opgegeven) van de volgende rijen van een query als 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 Parameters: `size` Type: `int` Het aantal volgende rijen dat moet worden weergegeven. Deze parameter is optioneel. Als dit niet is opgegeven, wordt de waarde van het `arraysize` kenmerk gebruikt. Voorbeeld: `cursor.fetchmany_arrow(10)`

`Row` klas

De rijklasse is een tuple-achtige gegevensstructuur die een afzonderlijke resultaatrij 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:

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

Geen parameters.

Retourneert een dict of meer velden. |

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`

Probleemoplossing

`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 waarde die is access_token doorgegeven, is geen geldig persoonlijk toegangstoken van 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. Met vermelding van IP-adressen zijn verbindingen van Spark-clusters terug naar het besturingsvlak 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
Data types
Ingebouwde typen (voorbool, bytearray, float, en intstr) op de Python-website
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

Delen via

Databricks SQL Connector voor Python

Vereisten

Aan de slag

Cluster

SQL Warehouse

Verificatie

Verificatie van persoonlijke toegangstokens van Databricks

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

Verificatie van Microsoft Entra-id-token

OAuth-verificatie van gebruiker naar machine (U2M)

Voorbeelden

Querygegevens

Gegevens invoegen

Querymetagegevens

Cursors en verbindingen beheren

Bestanden beheren in Unity Catalog-volumes

Logboekregistratie configureren

Testen

API-verwijzing

Pakket

Module

Klassen

`Connection` klas

`Cursor` klas

`Row` klas

Typeconversies

Probleemoplossing

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Bericht

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

`IpAclError` Bericht

Aanvullende bronnen

Feedback

Aanvullende resources

Delen via

Databricks SQL Connector voor Python

Vereisten

Aan de slag

Cluster

SQL Warehouse

Verificatie

Verificatie van persoonlijke toegangstokens van Databricks

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

Verificatie van Microsoft Entra-id-token

OAuth-verificatie van gebruiker naar machine (U2M)

Voorbeelden

Querygegevens

Gegevens invoegen

Querymetagegevens

Cursors en verbindingen beheren

Bestanden beheren in Unity Catalog-volumes

Logboekregistratie configureren

Testen

API-verwijzing

Pakket

Module

Klassen

Connection klas

Cursor klas

Row klas

Typeconversies

Probleemoplossing

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