Databricks SQL Connector för Python

Artikel
11/14/2024

Databricks SQL Connector för Python är ett Python-bibliotek som gör att du kan använda Python-kod för att köra SQL-kommandon på Azure Databricks-kluster och Databricks SQL-lager. Databricks SQL Connector för Python är enklare att konfigurera och använda än liknande Python-bibliotek som pyodbc. Det här biblioteket följer PEP 249 – Python Database API Specification v2.0.

Kommentar

Databricks SQL Connector för Python innehåller även en SQLAlchemy-dialekt för Azure Databricks. Se Använda SQLAlchemy med Azure Databricks.

Krav

En utvecklingsdator som kör Python >=3.8 och <=3.11.
Databricks rekommenderar att du använder virtuella Python-miljöer, till exempel de som tillhandahålls av venv som ingår i Python. Virtuella miljöer hjälper dig att se till att du använder rätt versioner av Python och Databricks SQL Connector för Python tillsammans. Att konfigurera och använda virtuella miljöer ligger utanför omfånget för den här artikeln. Mer information finns i Skapa virtuella miljöer.
Ett befintligt kluster eller SQL-lager.

Kom igång

Installera Databricks SQL Connector för Python-biblioteket på utvecklingsdatorn genom att köra pip install databricks-sql-connector eller python -m pip install databricks-sql-connector.
Samla in följande information för det kluster eller SQL-lager som du vill använda:

Kluster
- Servervärdnamnet för klustret. Du kan hämta detta från värdet Servervärdnamn på fliken Avancerade alternativ > JDBC/ODBC för klustret.
- HTTP-sökvägen för klustret. Du kan hämta detta från http-sökvägsvärdet på fliken Avancerade alternativ > JDBC/ODBC för klustret.
SQL-lager
- Servervärdnamnet för SQL-lagret. Du kan hämta detta från värdet Servervärdnamn på fliken Anslutningsinformation för DITT SQL-lager.
- HTTP-sökvägen för SQL-lagret. Du kan hämta detta från HTTP-sökvägsvärdet på fliken Anslutningsinformation för DITT SQL-lager.

Autentisering

Databricks SQL Connector för Python stöder följande Azure Databricks-autentiseringstyper:

Autentisering med personlig åtkomsttoken för Databricks
Microsoft Entra ID-tokenautentisering
OAuth-autentisering från dator till dator (M2M)
OAuth-autentisering från användare till dator (U2M)

Databricks SQL Connector för Python stöder ännu inte följande Azure Databricks-autentiseringstyper:

Autentisering med personlig åtkomsttoken för Databricks

Om du vill använda Databricks SQL Connector för Python med personlig åtkomsttokenautentisering i Azure Databricks måste du först skapa en personlig åtkomsttoken för Azure Databricks. Det gör du genom att följa stegen i Personliga åtkomsttoken för Azure Databricks för arbetsyteanvändare.

Om du vill autentisera Databricks SQL Connector för Python använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
DATABRICKS_TOKEN, inställt på den personliga åtkomsttoken för Azure Databricks.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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-autentisering från dator till dator (M2M)

Databricks SQL Connector för Python-versionerna 2.7.0 och senare stöder OAuth-autentisering från maskin till dator (M2M). Du måste också installera Databricks SDK för Python 0.18.0 eller senare (till exempel genom att köra pip install databricks-sdk eller python -m pip install databricks-sdk).

Om du vill använda Databricks SQL Connector för Python med OAuth M2M-autentisering måste du göra följande:

Skapa ett Huvudnamn för Azure Databricks-tjänsten på din Azure Databricks-arbetsyta och skapa en OAuth-hemlighet för tjänstens huvudnamn.

Information om hur du skapar tjänstens huvudnamn och dess OAuth-hemlighet finns i Autentisera åtkomst till Azure Databricks med ett huvudnamn för tjänsten med OAuth (OAuth M2M). Anteckna tjänstens huvudnamns UUID - eller program-ID-värde och det hemliga värdet för tjänstens huvudnamns OAuth-hemlighet.
Ge tjänstens huvudnamn åtkomst till klustret eller informationslagret.

Information om hur du ger tjänstens huvudnamn åtkomst till klustret eller informationslagret finns i Beräkningsbehörigheter eller Hantera ett SQL-lager.

Om du vill autentisera Databricks SQL Connector för Python använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

DATABRICKS_SERVER_HOSTNAMEange värdet servervärdnamn för klustret eller SQL-lagret.
DATABRICKS_HTTP_PATHanger du till HTTP-sökvägsvärde för klustret eller SQL-lagret.
DATABRICKS_CLIENT_ID, inställt på tjänstens huvudnamns UUID - eller program-ID-värde .
DATABRICKS_CLIENT_SECRET, ange värdet Hemlig för tjänstens huvudnamns OAuth-hemlighet.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Om du vill använda Databricks SQL Connector för Python med Microsoft Entra ID-tokenautentisering måste du ange Databricks SQL Connector för Python med Microsoft Entra ID-token. Gör följande för att skapa en Microsoft Entra ID-åtkomsttoken:

För en Azure Databricks-användare kan du använda Azure CLI. Se Hämta Microsoft Entra-ID-token för användare med hjälp av Azure CLI.
Ett microsoft entra-ID-tjänsthuvudnamn finns i Hämta en Microsoft Entra ID-åtkomsttoken med Azure CLI. Information om hur du skapar ett microsoft entra-ID för hanterad tjänsthuvudnamn finns i Hantera tjänstens huvudnamn.

Microsoft Entra-ID-token har en standardlivslängd på cirka 1 timme. Om du vill skapa en ny Microsoft Entra-ID-token upprepar du den här processen.

Om du vill autentisera Databricks SQL Connector för Python använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

Ange DATABRICKS_SERVER_HOSTNAME värdet servervärdnamn för klustret eller SQL-lagret.
Ange DATABRICKS_HTTP_PATH värdet för HTTP-sökväg för klustret eller SQL-lagret.
Ange DATABRICKS_TOKEN till Microsoft Entra-ID-token.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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-autentisering från användare till dator (U2M)

Databricks SQL Connector för Python-versionerna 2.7.0 och senare stöder OAuth-autentisering från användare till dator (U2M). Du måste också installera Databricks SDK för Python 0.19.0 eller senare (till exempel genom att köra pip install databricks-sdk eller python -m pip install databricks-sdk).

Om du vill autentisera Databricks SQL Connector för Python med OAuth U2M-autentisering använder du följande kodfragment. OAuth U2M-autentisering använder mänsklig inloggning i realtid och medgivande för att autentisera azure Databricks-målanvändarkontot. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

Ange DATABRICKS_SERVER_HOSTNAME värdet servervärdnamn för klustret eller SQL-lagret.
Ange DATABRICKS_HTTP_PATH värdet för HTTP-sökväg för klustret eller SQL-lagret.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

Exempel

Följande kodexempel visar hur du använder Databricks SQL Connector för Python för att fråga och infoga data, fråga efter metadata, hantera markörer och anslutningar och konfigurera loggning.

Kommentar

Följande kodexempel visar hur du använder en personlig åtkomsttoken för Azure Databricks för autentisering. Om du vill använda andra tillgängliga autentiseringstyper för Azure Databricks i stället kan du läsa Autentisering.

I det här kodexemplet hämtas deras server_hostname, http_pathoch access_token anslutningsvariabelvärden från dessa miljövariabler:

DATABRICKS_SERVER_HOSTNAME, som representerar värdet servervärdnamn från kraven.
DATABRICKS_HTTP_PATH, som representerar http-sökvägsvärdet från kraven.
DATABRICKS_TOKEN, som representerar din åtkomsttoken från kraven.

Du kan använda andra metoder för att hämta dessa anslutningsvariabelvärden. Att använda miljövariabler är bara en metod bland många.

Fråga efter data
Infoga data
Frågemetadata
Hantera markörer och anslutningar
Hantera filer i Unity Catalog-volymer
Konfigurera loggning

Fråga efter data

I följande kodexempel visas hur du anropar Databricks SQL Connector för Python för att köra ett grundläggande SQL-kommando i ett kluster eller SQL-lager. Det här kommandot returnerar de två första raderna trips från tabellen i samples katalogens nyctaxi schema.

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)

Infoga data

I följande exempel visas hur du infogar små mängder data (tusentals rader):

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)

För stora mängder data bör du först ladda upp data till molnlagring och sedan köra kommandot COPY INTO .

Frågemetadata

Det finns dedikerade metoder för att hämta metadata. I följande exempel hämtas metadata om kolumner i en exempeltabell:

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

Hantera markörer och anslutningar

Det är en bra idé att stänga alla anslutningar och markörer som inte längre används. Detta frigör resurser i Azure Databricks-kluster och Databricks SQL-lager.

Du kan använda en kontexthanterare (syntaxen with som användes i tidigare exempel) för att hantera resurserna, eller uttryckligen anropa 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()

Hantera filer i Unity Catalog-volymer

Med Databricks SQL Connector kan du skriva lokala filer till Unity Catalog-volymer, ladda ned filer från volymer och ta bort filer från volymer, enligt följande exempel:

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

Konfigurera loggning

Databricks SQL Connector använder Pythons standardloggningsmodul. Du kan konfigurera loggningsnivån ungefär så här:

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

Testning

Om du vill testa koden använder du Python-testramverk som pytest. Om du vill testa koden under simulerade förhållanden utan att anropa Azure Databricks REST API-slutpunkter eller ändra tillståndet för dina Azure Databricks-konton eller arbetsytor kan du använda Python-modelleringsbibliotek som unittest.mock.

Med följande fil med namnet helpers.py som innehåller en get_connection_personal_access_token funktion som använder en personlig Åtkomsttoken för Azure Databricks för att returnera en anslutning till en Azure Databricks-arbetsyta och en select_nyctaxi_trips funktion som använder anslutningen för att hämta det angivna antalet datarader från trips tabellen i samples katalogens 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(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
  result: List[Row] = cursor.fetchall()
  return result

Och med följande fil med namnet main.py som anropar get_connection_personal_access_token funktionerna och select_nyctaxi_trips :

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

Följande fil med namnet test_helpers.py testar om select_nyctaxi_trips funktionen returnerar det förväntade svaret. I stället för att skapa en verklig anslutning till målarbetsytan hånar det här testet ett Connection objekt. Testet hånar också vissa data som överensstämmer med schemat och värdena som finns i verkliga data. Testet returnerar de simulerade data via den simulerade anslutningen och kontrollerar sedan om ett av de simulerade dataradernas värden matchar det förväntade värdet.

# 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

select_nyctaxi_trips Eftersom funktionen innehåller en SELECT -instruktion och därför inte ändrar tabellens trips tillstånd är det inte absolut nödvändigt att håna i det här exemplet. Men genom att håna kan du snabbt köra dina tester utan att vänta på att en faktisk anslutning ska göras med arbetsytan. Genom att håna kan du också köra simulerade tester flera gånger för funktioner som kan ändra en tabells tillstånd, till exempel INSERT INTO, UPDATEoch DELETE FROM.

Paket

databricks-sql-connector

Användning: pip install databricks-sql-connector

Se även databricks-sql-connector i Python Package Index (PyPI).

Modul

databricks.sql

Användning: from databricks import sql

Klasser

Bland de valda klasserna finns följande:

Klasser
`Connection` En session på en Azure Databricks-beräkningsresurs.
`Cursor` En mekanism för att bläddra över dataposter.
`Row` En rad med data i ett SQL-frågeresultat.

`Connection` klass

Om du vill skapa ett Connection objekt anropar du databricks.sql.connect metoden med följande parametrar:

Parametrar
`server_hostname` Typ: `str` Servervärdnamnet för klustret eller SQL-lagret. Information om hur du hämtar serverns värdnamn finns i anvisningarna tidigare i den här artikeln. Den här parametern krävs. Exempel: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Typ: `str` HTTP-sökvägen för klustret eller SQL-lagret. Information om hur du hämtar HTTP-sökvägen finns i anvisningarna tidigare i den här artikeln. Den här parametern krävs. Exempel: `sql/protocolv1/o/1234567890123456/1234-567890-test123` för ett kluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` för ett SQL-lager.
`access_token`, `auth_type` Typ: `str` Information om autentiseringsinställningar för Azure Databricks. Mer information finns i Autentisering.
`session_configuration` Typ: `dict[str, Any]` En ordlista med konfigurationsparametrar för Spark-sessioner. Att ange en konfiguration motsvarar att använda SQL-kommandot `SET key=val` . Kör SQL-kommandot `SET -v` för att hämta en fullständig lista över tillgängliga konfigurationer. Standardvärdet är `None`. Den här parametern är valfri. Exempel: `{"spark.sql.variable.substitute": True}`
`http_headers` Typ: `List[Tuple[str, str]]]` Ytterligare par (nyckel, värde) som ska anges i HTTP-huvuden på varje RPC-begäran som klienten gör. Typisk användning ställer inte in några extra HTTP-huvuden. Standardvärdet är `None`. Den här parametern är valfri. Sedan version 2.0
`catalog` Typ: `str` Den första katalogen som ska användas för anslutningen. Standardvärdet är `None` (i vilket fall standardkatalogen, vanligtvis `hive_metastore`, används). Den här parametern är valfri. Sedan version 2.0
`schema` Typ: `str` Initialt schema som ska användas för anslutningen. Standardvärdet är `None` (i vilket fall standardschemat `default` används). Den här parametern är valfri. Sedan version 2.0
`use_cloud_fetch` Typ: `bool` `True` för att skicka hämtningsbegäranden direkt till molnobjektlagret för att ladda ned datasegment. `False` (standardinställningen) för att skicka hämtningsbegäranden direkt till Azure Databricks. Om `use_cloud_fetch` är inställt på `True` men nätverksåtkomsten blockeras misslyckas hämtningsbegäranden. Sedan version 2.8

Bland de valda Connection metoderna finns följande:

Metoder
`close` Stänger anslutningen till databasen och släpper alla associerade resurser på servern. Eventuella ytterligare anrop till den här anslutningen genererar en `Error`. Inga parametrar. Inget returvärde.
`cursor` Returnerar ett nytt `Cursor` objekt som möjliggör bläddering över posterna i en databas. Inga parametrar.

`Cursor` klass

Om du vill skapa ett Cursor objekt anropar du Connection klassens cursor -metod.

Bland de markerade Cursor attributen finns följande:

Attribut

Attribut
`arraysize` Används med `fetchmany` metoden, anger den interna buffertstorleken, vilket också är hur många rader som faktiskt hämtas från servern åt gången. Standardvärdet är `10000`. För smala resultat (resultat där varje rad inte innehåller mycket data) bör du öka det här värdet för bättre prestanda. Läs- och skrivåtkomst.
`description` Innehåller en Python `list` med `tuple` objekt. Vart och ett av dessa `tuple` objekt innehåller 7 värden, där de första två objekten i varje `tuple` objekt innehåller information som beskriver en enda resultatkolumn på följande sätt: - `name`: Namnet på kolumnen. - `type_code`: En sträng som representerar typen av kolumn. Till exempel har en heltalskolumn en typkod av `int`. De återstående 5 objekten i varje objekt med 7 objekt `tuple` implementeras inte och deras värden definieras inte. De returneras vanligtvis som 4 `None` värden följt av ett enda `True` värde. Skrivskyddad åtkomst.

arraysize

Används med fetchmany metoden, anger den interna buffertstorleken, vilket också är hur många rader som faktiskt hämtas från servern åt gången. Standardvärdet är 10000. För smala resultat (resultat där varje rad inte innehåller mycket data) bör du öka det här värdet för bättre prestanda.

Läs- och skrivåtkomst.

description

Innehåller en Python list med tuple objekt. Vart och ett av dessa tuple objekt innehåller 7 värden, där de första två objekten i varje tuple objekt innehåller information som beskriver en enda resultatkolumn på följande sätt:

- name: Namnet på kolumnen.
- type_code: En sträng som representerar typen av kolumn. Till exempel har en heltalskolumn en typkod av int.

De återstående 5 objekten i varje objekt med 7 objekt tuple implementeras inte och deras värden definieras inte. De returneras vanligtvis som 4
None värden följt av ett enda True värde.

Skrivskyddad åtkomst.

Bland de valda Cursor metoderna finns följande:

Metoder
`cancel` Avbryter körningen av en databasfråga eller ett kommando som markören har startat. Om du vill frigöra de associerade resurserna på servern anropar du `close` när metoden anropats `cancel` . Inga parametrar. Inget returvärde.
`close` Stänger markören och släpper de associerade resurserna på servern. Om du stänger en redan stängd markör kan ett fel uppstå. Inga parametrar. Inget returvärde.
`execute` Förbereder och kör sedan en databasfråga eller ett kommando. Inget returvärde. Parametrar: `operation` Typ: `str` Frågan eller kommandot som ska förberedas och sedan köras. Den här parametern krävs. Exempel utan parametern `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Exempel med parametern `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Typ: ordlista En sekvens med parametrar som ska användas med parametern `operation` . Den här parametern är valfri. Standardvärdet är `None`.
`executemany` Förbereder och kör sedan en databasfråga eller ett kommando med alla parametersekvenser i `seq_of_parameters` argumentet. Endast den slutliga resultatuppsättningen behålls. Inget returvärde. Parametrar: `operation` Typ: `str` Frågan eller kommandot som ska förberedas och sedan köras. Den här parametern krävs. `seq_of_parameters` Typ: `list` av `dict` En sekvens med många uppsättningar med parametervärden som ska användas med `operation` parameter. Den här parametern krävs.
`catalogs` Kör en metadatafråga om katalogerna. Faktiska resultat ska sedan hämtas med hjälp av `fetchmany` eller `fetchall`. Viktiga fält i resultatuppsättningen är: - Fältnamn: `TABLE_CAT`. Typ: `str`. Namnet på katalogen. Inga parametrar. Inget returvärde. Sedan version 1.0
`schemas` Kör en metadatafråga om schemana. Faktiska resultat ska sedan hämtas med hjälp av `fetchmany` eller `fetchall`. Viktiga fält i resultatuppsättningen är: - Fältnamn: `TABLE_SCHEM`. Typ: `str`. Namnet på schemat. - Fältnamn: `TABLE_CATALOG`. Typ: `str`. Katalogen som schemat tillhör. Inget returvärde. Sedan version 1.0 Parametrar: `catalog_name` Typ: `str` Ett katalognamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `schema_name` Typ: `str` Ett schemanamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri.
`tables` Kör en metadatafråga om tabeller och vyer. Faktiska resultat ska sedan hämtas med hjälp av `fetchmany` eller `fetchall`. Viktiga fält i resultatuppsättningen är: - Fältnamn: `TABLE_CAT`. Typ: `str`. Katalogen som tabellen tillhör. - Fältnamn: `TABLE_SCHEM`. Typ: `str`. Schemat som tabellen tillhör. - Fältnamn: `TABLE_NAME`. Typ: `str`. Tabellens namn. - Fältnamn: `TABLE_TYPE`. Typ: `str`. Typen av relation, till exempel `VIEW` eller `TABLE` (gäller för Databricks Runtime 10.4 LTS och senare samt för Databricks SQL; tidigare versioner av Databricks Runtime returnerar en tom sträng). Inget returvärde. Sedan version 1.0 Parametrar `catalog_name` Typ: `str` Ett katalognamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `schema_name` Typ: `str` Ett schemanamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `table_name` Typ: `str` Ett tabellnamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `table_types` Typ: `List[str]` En lista över tabelltyper som ska matcha, till exempel `TABLE` eller `VIEW`. Den här parametern är valfri.
`columns` Kör en metadatafråga om kolumnerna. Faktiska resultat ska sedan hämtas med hjälp av `fetchmany` eller `fetchall`. Viktiga fält i resultatuppsättningen är: - Fältnamn: `TABLE_CAT`. Typ: `str`. Katalogen som kolumnen tillhör. - Fältnamn: `TABLE_SCHEM`. Typ: `str`. Schemat som kolumnen tillhör. - Fältnamn: `TABLE_NAME`. Typ: `str`. Namnet på den tabell som kolumnen tillhör. - Fältnamn: `COLUMN_NAME`. Typ: `str`. Kolumnens namn. Inget returvärde. Sedan version 1.0 Parametrar: `catalog_name` Typ: `str` Ett katalognamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `schema_name` Typ: `str` Ett schemanamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `table_name` Typ: `str` Ett tabellnamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri. `column_name` Typ: `str` Ett kolumnnamn att hämta information om. Tecknet `%` tolkas som ett jokertecken. Den här parametern är valfri.
`fetchall` Hämtar alla (eller alla återstående) rader i en fråga. Inga parametrar. Returnerar alla (eller alla återstående) rader i frågan som en Python `list` av `Row` Objekt. Genererar ett `Error` om det tidigare anropet `execute` till metoden inte returnerade några data eller om inget `execute` anrop ännu har gjorts.
`fetchmany` Hämtar nästa rader i en fråga. Returnerar upp till `size` (eller `arraysize` attributet om `size` det inte anges) för nästa rader i en fråga som en Python `list` med `Row` objekt. Om det finns färre rader kvar `size` att hämta returneras alla återstående rader. Genererar ett `Error` om det tidigare anropet `execute` till metoden inte returnerade några data eller om inget `execute` anrop ännu har gjorts. Parametrar: `size` Typ: `int` Antalet nästa rader som ska hämtas. Den här parametern är valfri. Om det inte anges används värdet för `arraysize` attributet. Exempel: `cursor.fetchmany(10)`
`fetchone` Hämtar nästa rad i datauppsättningen. Inga parametrar. Returnerar nästa rad i datauppsättningen som en enda sekvens som en Python `tuple` eller returnerar `None` om det inte finns fler tillgängliga data. Genererar ett `Error` om det tidigare anropet `execute` till metoden inte returnerade några data eller om inget `execute` anrop ännu har gjorts.
`fetchall_arrow` Hämtar alla (eller alla återstående) rader i en fråga som ett PyArrow-objekt `Table` . Frågor som returnerar mycket stora mängder data bör i stället användas `fetchmany_arrow` för att minska minnesförbrukningen. Inga parametrar. Returnerar alla (eller alla återstående) rader i frågan som en PyArrow-tabell. Genererar ett `Error` om det tidigare anropet `execute` till metoden inte returnerade några data eller om inget `execute` anrop ännu har gjorts. Sedan version 2.0
`fetchmany_arrow` Hämtar nästa rader i en fråga som ett PyArrow-objekt `Table` . Returnerar upp till `size` argumentet (eller attributet om `size` det `arraysize` inte anges) för nästa rader i en fråga som en Python PyArrow `Table` objekt. Genererar ett `Error` om det tidigare anropet `execute` till metoden inte returnerade några data eller om inget `execute` anrop ännu har gjorts. Sedan version 2.0 Parametrar: `size` Typ: `int` Antalet nästa rader som ska hämtas. Den här parametern är valfri. Om det inte anges används värdet för `arraysize` attributet. Exempel: `cursor.fetchmany_arrow(10)`

`Row` klass

Radklassen är en tupppelliknande datastruktur som representerar en enskild resultatrad. Om raden innehåller en kolumn med namnet "my_column"kan du komma åt fältet "my_column" row via row.my_column. Du kan också använda numeriska dikter för att komma åt fält, till exempel row[0]. Om kolumnnamnet inte tillåts som ett attributmetodnamn (till exempel börjar det med en siffra) kan du komma åt fältet som row["1_my_column"].

Sedan version 1.0

Bland de valda Row metoderna finns:

| asDict

Returnerar en ordlisterepresentation av raden, som indexeras med fältnamn. Om det finns duplicerade fältnamn returneras ett av de duplicerade fälten (men bara ett) i ordlistan. Vilket duplicerat fält som returneras har inte definierats.

Inga parametrar.

Returnerar ett dict fält. |

Typkonverteringar

I följande tabell mappas Apache Spark SQL-datatyper till motsvarande Python-datatyper.

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

Felsökning

`tokenAuthWrapperInvalidAccessToken: Invalid access token` meddelande

Problem: När du kör koden visas ett meddelande som liknar Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Möjlig orsak: Värdet som skickas till är inte en giltig personlig Åtkomsttoken för access_token Azure Databricks.

Rekommenderad korrigering: Kontrollera att det värde som skickades till access_token är korrekt och försök igen.

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

Problem: När du kör koden visas ett meddelande som liknar Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Möjlig orsak: Värdet som skickas till server_hostname är inte rätt värdnamn.

Rekommenderad korrigering: Kontrollera att det värde som skickades till server_hostname är korrekt och försök igen.

Mer information om hur du hittar serverns värdnamn finns i Hämta anslutningsinformation för en Azure Databricks-beräkningsresurs.

`IpAclError` meddelande

Problem: När du kör koden visas meddelandet Error during request to server: IpAclValidation när du försöker använda anslutningsappen i en Azure Databricks-notebook-fil.

Möjlig orsak: Du kan ha ip-tillåtna listor aktiverade för Azure Databricks-arbetsytan. Med listan över TILLÅTNA IP-adresser tillåts inte anslutningar från Spark-kluster tillbaka till kontrollplanet som standard.

Rekommenderad korrigering: Be administratören att lägga till undernätet för beräkningsplanet i listan över tillåtna IP-adresser.

Ytterligare resurser

Mer information finns i:

Databricks SQL Connector för Python-lagringsplatsen på GitHub
Datatyper
Inbyggda typer (för bool, bytearray, float, intoch str) på Python-webbplatsen
datetime (för datetime.date och datatime.datetime) på Python-webbplatsen
decimal ( för decimal.Decimal) på Python-webbplatsen
Inbyggda konstanter (för NoneType) på Python-webbplatsen

Dela via

Databricks SQL Connector för Python

Krav

Kom igång

Kluster

SQL-lager

Autentisering

Autentisering med personlig åtkomsttoken för Databricks

OAuth-autentisering från dator till dator (M2M)

Microsoft Entra ID-tokenautentisering

OAuth-autentisering från användare till dator (U2M)

Exempel

Fråga efter data

Infoga data

Frågemetadata

Hantera markörer och anslutningar

Hantera filer i Unity Catalog-volymer

Konfigurera loggning

Testning

API-referens

Paket

Modul

Klasser

`Connection` klass

`Cursor` klass

`Row` klass

Typkonverteringar

Felsökning

`tokenAuthWrapperInvalidAccessToken: Invalid access token` meddelande

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

`IpAclError` meddelande

Ytterligare resurser

Feedback

Ytterligare resurser

Dela via

Databricks SQL Connector för Python

Krav

Kom igång

Kluster

SQL-lager

Autentisering

Autentisering med personlig åtkomsttoken för Databricks

OAuth-autentisering från dator till dator (M2M)

Microsoft Entra ID-tokenautentisering

OAuth-autentisering från användare till dator (U2M)

Exempel

Fråga efter data

Infoga data

Frågemetadata

Hantera markörer och anslutningar

Hantera filer i Unity Catalog-volymer

Konfigurera loggning

Testning

API-referens

Paket

Modul

Klasser

Connection klass

Cursor klass

Row klass

Typkonverteringar

Felsökning

tokenAuthWrapperInvalidAccessToken: Invalid access token meddelande

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

IpAclError meddelande

Ytterligare resurser

Feedback

Ytterligare resurser

`Connection` klass

`Cursor` klass

`Row` klass

`tokenAuthWrapperInvalidAccessToken: Invalid access token` meddelande

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

`IpAclError` meddelande