Databricks SQL Connector for Python

Cikk
10/10/2024

A Databricks SQL Connector for Python egy Python-kódtár, amely lehetővé teszi, hogy Python-kód használatával SQL-parancsokat futtasson az Azure Databricks-fürtökön és a Databricks SQL-tárolókon. A Pythonhoz készült Databricks SQL-összekötőt egyszerűbb beállítani és használni, mint a hasonló Python-kódtárakat, például a pyodbc-t. Ez a kódtár a PEP 249 – Python Database API Specification 2.0-s verziót követi.

Feljegyzés

A Pythonhoz készült Databricks SQL-összekötő tartalmaz egy SQLAlchemy dialektust is az Azure Databrickshez. Lásd: Az SQLAlchemy használata az Azure Databricksben.

Követelmények

Python >=3.8 és <=3.11 rendszerű fejlesztőgép.
A Databricks azt javasolja, hogy pythonos virtuális környezeteket használjon, például a Python részét képező venv által biztosítottakat. A virtuális környezetek segítségével biztosítható, hogy a Python és a Databricks SQL Connector for Python megfelelő verzióit használja együtt. A virtuális környezetek beállítása és használata a jelen cikk hatókörén kívül esik. További információ: Virtuális környezetek létrehozása.
Meglévő fürt vagy SQL Warehouse.

Első lépések

Telepítse a Databricks SQL Connector for Python-kódtárat a fejlesztőgépre a futtatás vagy python -m pip install databricks-sql-connectora .pip install databricks-sql-connector
Gyűjtse össze a használni kívánt fürtre vagy SQL Warehouse-ra vonatkozó alábbi információkat:

Fürt
- A fürt kiszolgálói állomásneve. Ezt a fürt Speciális beállítások > JDBC/ODBC lapján található Kiszolgáló állomásnév értékéből szerezheti be.
- A fürt HTTP-elérési útja. Ezt a fürt Speciális beállítások > JDBC/ODBC lapján található HTTP-elérési út értékről szerezheti be.
SQL Warehouse
- Az SQL Warehouse kiszolgálói állomásneve. Ezt az SQL-raktár Kapcsolat részletei lapján található Kiszolgáló állomásnév értékéből szerezheti be.
- Az SQL Warehouse HTTP-elérési útja. Ezt az SQL Warehouse Kapcsolat részletei lapján található HTTP-elérési út értékből szerezheti be.

Hitelesítés

A Pythonhoz készült Databricks SQL-összekötő a következő Azure Databricks-hitelesítési típusokat támogatja:

Databricks személyes hozzáférési jogkivonat hitelesítése
Microsoft Entra-azonosító jogkivonat hitelesítése
OAuth gépről gépre (M2M) hitelesítés
OAuth user-to-machine (U2M) hitelesítés

A Pythonhoz készült Databricks SQL-összekötő még nem támogatja a következő Azure Databricks-hitelesítési típusokat:

Databricks személyes hozzáférési jogkivonat hitelesítése

Ha a Databricks SQL Connector for Pythont azure Databricks személyes hozzáférési jogkivonat-hitelesítéssel szeretné használni, először létre kell hoznia egy Azure Databricks személyes hozzáférési jogkivonatot az alábbiak szerint:

Az Azure Databricks-munkaterületen kattintson az Azure Databricks-felhasználónevére a felső sávon, majd válassza a legördülő menü Beállítások elemét .
Kattintson a Fejlesztőeszközök elemre.
Az Access-jogkivonatok mellett kattintson a Kezelés gombra.
Kattintson az Új jogkivonat létrehozása elemre.
(Nem kötelező) Írjon be egy megjegyzést, amely segít azonosítani a jogkivonatot a jövőben, és módosíthatja a jogkivonat alapértelmezett 90 napos élettartamát. Élettartam nélküli (nem ajánlott) jogkivonat létrehozásához hagyja üresen az Élettartam (nap) mezőt (üres).
Kattintson a Létrehozás lehetőségre.
Másolja a megjelenített jogkivonatot egy biztonságos helyre, majd kattintson a Kész gombra.

Feljegyzés

Ügyeljen arra, hogy a másolt jogkivonatot biztonságos helyre mentse. Ne ossza meg másokkal a másolt jogkivonatot. Ha elveszíti a másolt jogkivonatot, nem tudja pontosan ugyanazt a jogkivonatot újragenerálni. Ehelyett meg kell ismételnie ezt az eljárást egy új jogkivonat létrehozásához. Ha elveszíti a másolt jogkivonatot, vagy úgy véli, hogy a jogkivonat sérült, a Databricks határozottan javasolja, hogy azonnal törölje a jogkivonatot a munkaterületről az Access-jogkivonatok lapon a jogkivonat melletti kuka (Visszavonás) ikonra kattintva.

Ha nem tud jogkivonatokat létrehozni vagy használni a munkaterületen, ennek az lehet az oka, hogy a munkaterület rendszergazdája letiltotta a jogkivonatokat, vagy nem adott engedélyt a jogkivonatok létrehozására vagy használatára. Tekintse meg a munkaterület rendszergazdáját vagy a következő témaköröket:

A Pythonhoz készült Databricks SQL-összekötő hitelesítéséhez használja az alábbi kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

DATABRICKS_SERVER_HOSTNAMEelemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.
DATABRICKS_TOKENbeállításnál állítsa be az Azure Databricks személyes hozzáférési jogkivonatát.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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 machine-to-machine (M2M) hitelesítés

A Databricks SQL Connector for Python 2.7.0-s és újabb verziói támogatják az OAuth machine-to-machine (M2M) hitelesítést. A Python 0.18.0-s vagy újabb verziójához készült Databricks SDK-t is telepítenie kell (például futtatással vagy python -m pip install databricks-sdk).pip install databricks-sdk

A Databricks SQL Connector for Python OAuth M2M-hitelesítéssel való használatához a következőket kell tennie:

Hozzon létre egy Azure Databricks-szolgáltatásnevet az Azure Databricks-munkaterületen, és hozzon létre egy OAuth-titkos kulcsot a szolgáltatásnévhez.

A szolgáltatásnév és az OAuth-titkos kód létrehozásához lásd : Azure Databricks-hozzáférés hitelesítése szolgáltatásnévvel az OAuth (OAuth M2M) használatával. Jegyezze fel a szolgáltatásnév UUID - vagy alkalmazásazonosító-értékét , valamint a szolgáltatásnév OAuth-titkos kódjának titkos értékét.
Adjon hozzáférést a szolgáltatásnévnek a fürthöz vagy a raktárhoz.

Ha hozzáférést szeretne adni a szolgáltatásnévnek a fürthöz vagy a raktárhoz, olvassa el a számítási engedélyeket vagy az SQL-raktár kezelését.

A Pythonhoz készült Databricks SQL-összekötő hitelesítéséhez használja az alábbi kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

DATABRICKS_SERVER_HOSTNAME elemet a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékére állítja.
DATABRICKS_HTTP_PATHelemet, állítsa be a HTTP-elérési út értékét a fürthöz vagy az SQL Warehouse-hoz.
DATABRICKS_CLIENT_ID, állítsa be a szolgáltatásnév UUID - vagy alkalmazásazonosító-értékét .
DATABRICKS_CLIENT_SECRET, állítsa be a szolgáltatásnév OAuth-titkos kódjának titkos értékét.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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-azonosító jogkivonat hitelesítése

Ha a Databricks SQL Connector for Pythont Microsoft Entra ID-jogkivonat-hitelesítéssel szeretné használni, meg kell adnia a Databricks SQL Connector for Pythonnak a Microsoft Entra ID tokent. Microsoft Entra ID hozzáférési jogkivonat létrehozásához tegye a következőket:

Azure Databricks-felhasználó esetén használhatja az Azure CLI-t. Lásd: Microsoft Entra ID-jogkivonatok lekérése felhasználók számára az Azure CLI használatával.
A Microsoft Entra ID szolgáltatásnévvel kapcsolatban lásd : Microsoft Entra ID hozzáférési jogkivonat beszerzése az Azure CLI-vel. A Microsoft Entra ID által felügyelt szolgáltatásnév létrehozásához lásd: Szolgáltatásnevek kezelése.

A Microsoft Entra ID-jogkivonatok alapértelmezett élettartama körülbelül 1 óra. Új Microsoft Entra ID-jogkivonat létrehozásához ismételje meg ezt a folyamatot.

A Pythonhoz készült Databricks SQL-összekötő hitelesítéséhez használja az alábbi kódrészletet. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

Állítsa be DATABRICKS_SERVER_HOSTNAME a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékét.
Állítsa be DATABRICKS_HTTP_PATH a fürt vagy az SQL Warehouse HTTP-elérési útvonalának értékét.
Állítsa be DATABRICKS_TOKEN a Microsoft Entra ID tokent.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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 user-to-machine (U2M) hitelesítés

A Databricks SQL Connector for Python 2.7.0-s és újabb verziói támogatják az OAuth felhasználó–gép (U2M) hitelesítést. A Python 0.19.0-s vagy újabb verziójához készült Databricks SDK-t is telepítenie kell (például futtatással vagy python -m pip install databricks-sdk).pip install databricks-sdk

A Databricks SQL Connector for Python OAuth U2M-hitelesítéssel való hitelesítéséhez használja az alábbi kódrészletet. Az OAuth U2M-hitelesítés valós idejű emberi bejelentkezést és hozzájárulást használ a cél Azure Databricks-felhasználói fiók hitelesítéséhez. Ez a kódrészlet feltételezi, hogy a következő környezeti változókat állította be:

Állítsa be DATABRICKS_SERVER_HOSTNAME a fürt vagy az SQL Warehouse kiszolgálói állomásnév értékét.
Állítsa be DATABRICKS_HTTP_PATH a fürt vagy az SQL Warehouse HTTP-elérési útvonalának értékét.

A környezeti változók beállításához tekintse meg az operációs rendszer dokumentációját.

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

Példák

Az alábbi példakódok bemutatják, hogyan használható a Databricks SQL Connector for Python az adatok lekérdezésére és beszúrására, a metaadatok lekérdezésére, a kurzorok és kapcsolatok kezelésére, valamint a naplózás konfigurálására.

Feljegyzés

Az alábbi példakód bemutatja, hogyan használható az Azure Databricks személyes hozzáférési jogkivonata a hitelesítéshez. Ha ehelyett más elérhető Azure Databricks-hitelesítési típusokat szeretne használni, tekintse meg a Hitelesítés című témakört.

Ezek a példakódok lekérik a környezeti http_pathváltozókserver_hostname, valamint access_token a kapcsolati változók értékeit:

DATABRICKS_SERVER_HOSTNAME, amely a kiszolgáló állomásnevének értékét jelöli a követelményekből.
DATABRICKS_HTTP_PATH, amely a követelmények HTTP-elérési útját jelöli.
DATABRICKS_TOKEN, amely a hozzáférési jogkivonatot jelöli a követelményekből.

Ezeket a kapcsolatváltozó-értékeket más módszerekkel is beolvashatja. A környezeti változók használata csak egy megközelítés a sok közül.

Adatok lekérdezése
Adatok beszúrása
Metaadatok lekérdezése
Kurzorok és kapcsolatok kezelése
Fájlok kezelése Unity Catalog-kötetekben
Naplózás konfigurálása

Adatok lekérdezése

Az alábbi példakód bemutatja, hogyan hívhatja meg a Databricks SQL Connector for Pythont, hogy egy alapszintű SQL-parancsot futtasson egy fürtön vagy SQL-raktáron. Ez a parancs a katalógus sémájában lévő samples táblázat első két sorát trips nyctaxi adja vissza.

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)

Adat beszúrása

Az alábbi példa bemutatja, hogyan szúrhat be kis mennyiségű adatot (több ezer sort):

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)

Nagy mennyiségű adat esetén először fel kell töltenie az adatokat a felhőbeli tárolóba, majd végre kell hajtania a COPY INTO parancsot.

Metaadatok lekérdezése

Vannak dedikált metódusok a metaadatok lekérésére. Az alábbi példa egy mintatábla oszlopainak metaadatait kéri le:

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

Kurzorok és kapcsolatok kezelése

Ajánlott bezárni a már nem használt kapcsolatokat és kurzorokat. Ez erőforrásokat szabadít fel az Azure Databricks-fürtökön és a Databricks SQL-tárolókon.

Az erőforrások kezeléséhez használhat környezetkezelőt (az with előző példákban használt szintaxist), vagy explicit módon meghívhatja a következőt 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()

Fájlok kezelése Unity Catalog-kötetekben

A Databricks SQL Connector lehetővé teszi helyi fájlok írását Unity Catalog-kötetekbe, fájlokat tölthet le kötetekről, és fájlokat törölhet a kötetekből az alábbi példában látható módon:

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

Naplózás konfigurálása

A Databricks SQL Connector a Python szabványos naplózási modulját használja. A naplózási szintet az alábbiakhoz hasonlóan konfigurálhatja:

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

Tesztelés

A kód teszteléséhez használjon Python-tesztelési keretrendszereket, például a pytestet. Ha szimulált körülmények között szeretné tesztelni a kódot az Azure Databricks REST API-végpontok meghívása vagy az Azure Databricks-fiókok vagy -munkaterületek állapotának módosítása nélkül, használhat Python-mintakódtárakat, például unittest.mockot.

Ha például a következő fájl neve helpers.py egy get_connection_personal_access_token olyan függvényt tartalmaz, amely egy Azure Databricks személyes hozzáférési jogkivonatot használ egy Azure Databricks-munkaterülethez való kapcsolat visszaadásához, és egy select_nyctaxi_trips olyan függvényt, amely a kapcsolatot használja a katalógus sémájában szereplő samples tábla megadott számú adatsorának trips lekéréséheznyctaxi:

# 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

És mivel a következő fájl neve meghívja main.py a get_connection_personal_access_token és select_nyctaxi_trips függvények:

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

A következő elnevezett test_helpers.py fájl ellenőrzi, hogy a select_nyctaxi_trips függvény a várt választ adja-e vissza. Ahelyett, hogy valódi kapcsolatot hoz létre a cél-munkaterülethez, ez a teszt egy Connection objektumot szimulál. A teszt néhány olyan adatot is szimulál, amely megfelel a valós adatok sémájának és értékeinek. A teszt a szimulált kapcsolaton keresztül adja vissza a szimulált adatokat, majd ellenőrzi, hogy a szimulált adatsorok egyik értéke megegyezik-e a várt értékkel.

# 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

Mivel a select_nyctaxi_trips függvény utasítást SELECT tartalmaz, ezért nem módosítja a trips tábla állapotát, ebben a példában nem feltétlenül szükséges a modellezés. A gúnyolással azonban gyorsan futtathatja a teszteket anélkül, hogy tényleges kapcsolatra kellene várnia a munkaterülettel. A gúnyolással szimulált teszteket is futtathat többször olyan függvények esetében, amelyek megváltoztathatják egy tábla állapotát, például INSERT INTO: , UPDATEés DELETE FROM.

Csomag

databricks-sql-connector

Használat: pip install databricks-sql-connector

Lásd még a Databricks-sql-connectort a Python-csomagindexben (PyPI).

Modul

databricks.sql

Használat: from databricks import sql

Osztályok

A kiválasztott osztályok a következőket tartalmazzák:

Osztályok
`Connection` Munkamenet egy Azure Databricks számítási erőforráson.
`Cursor` Az adatrekordok átjárásának mechanizmusa.
`Row` Adatsor egy SQL-lekérdezés eredményében.

`Connection` osztály

Objektum létrehozásához Connection hívja meg a databricks.sql.connect metódust a következő paraméterekkel:

Paraméterek
`server_hostname` Típus: `str` A fürt vagy az SQL Warehouse kiszolgálói állomásneve. A kiszolgáló állomásnevének lekéréséhez tekintse meg a cikk korábbi utasításait. Ez a paraméter kötelező. Példa: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Típus: `str` A fürt vagy az SQL Warehouse HTTP-elérési útja. A HTTP-elérési út lekéréséhez tekintse meg a cikk korábbi utasításait. Ez a paraméter kötelező. Példa: `sql/protocolv1/o/1234567890123456/1234-567890-test123` fürt esetében. `/sql/1.0/warehouses/a1b234c567d8e9fa` SQL-raktárhoz.
`access_token`, `auth_type` Típus: `str` Információk az Azure Databricks hitelesítési beállításairól. További részletekért lásd: Hitelesítés.
`session_configuration` Típus: `dict[str, Any]` A Spark-munkamenet konfigurációs paramétereinek szótára. A konfiguráció beállítása egyenértékű az `SET key=val` SQL-parancs használatával. Futtassa az SQL-parancsot `SET -v` az elérhető konfigurációk teljes listájának lekéréséhez. Alapértelmezett érték: `None`. Ez a paraméter nem kötelező. Példa: `{"spark.sql.variable.substitute": True}`
`http_headers` Típus: `List[Tuple[str, str]]]` További (kulcs, érték) párok, hogy beállítsa a HTTP-fejlécek minden RPC-kérést az ügyfél által. A tipikus használat nem állít be további HTTP-fejléceket. Alapértelmezett érték: `None`. Ez a paraméter nem kötelező. A 2.0-s verzió óta
`catalog` Típus: `str` A kapcsolathoz használni kívánt kezdeti katalógus. Alapértelmezés szerint `None` (ebben az esetben általában az alapértelmezett katalógus `hive_metastore`lesz használva). Ez a paraméter nem kötelező. A 2.0-s verzió óta
`schema` Típus: `str` A kapcsolathoz használandó kezdeti séma. Alapértelmezett érték `None` (ebben az esetben az alapértelmezett séma `default` lesz használva). Ez a paraméter nem kötelező. A 2.0-s verzió óta
`use_cloud_fetch` Típus: `bool` `True` lekéréses kérések közvetlenül a felhőobjektum-tárolóba való elküldéséhez adattömbök letöltéséhez. `False` (alapértelmezett) a lekéréses kérelmek közvetlenül az Azure Databricksnek való elküldéséhez. Ha `use_cloud_fetch` be van állítva, `True` de a hálózati hozzáférés le van tiltva, akkor a beolvasási kérelmek sikertelenek lesznek. A 2.8-as verzió óta

A kiválasztott Connection metódusok a következők:

Metódusok
`close` Bezárja az adatbázishoz való kapcsolatot, és felszabadítja az összes társított erőforrást a kiszolgálón. A kapcsolatra irányuló további hívások a következőt `Error`fogják eredményezni: . Nincsenek paraméterek. Nincs visszatérési érték.
`cursor` Egy új `Cursor` objektumot ad vissza, amely lehetővé teszi az adatbázis rekordjainak bejárását. Nincsenek paraméterek.

`Cursor` osztály

Objektum létrehozásához Cursor hívja meg az Connection osztály metódusát cursor .

A kijelölt Cursor attribútumok a következőket tartalmazzák:

Attribútumok

Attribútumok
`arraysize` A metódussal `fetchmany` a belső pufferméretet adja meg, amely azt is jelzi, hogy a rendszer hány sort hív le egyszerre a kiszolgálóról. Az alapértelmezett érték `10000`. Szűk eredmények (olyan eredmények, amelyekben az egyes sorok nem tartalmaznak sok adatot), a jobb teljesítmény érdekében növelnie kell ezt az értéket. Olvasási-írási hozzáférés.
`description` Objektumokat tartalmazó Pythont `list` `tuple` tartalmaz. Mindegyik `tuple` objektum 7 értéket tartalmaz, és mindegyik `tuple` objektum első 2 eleme az egyetlen eredményoszlopot leíró információkat tartalmazza az alábbiak szerint: - `name`: Az oszlop neve. - `type_code`: Az oszlop típusát képviselő sztring. Egy egész szám oszlop például a következő típusú kóddal rendelkezik `int`: . A 7 elemből `tuple` álló objektumok fennmaradó 5 eleme nincs implementálva, és az értékek nincsenek definiálva. Ezek általában 4-ként lesznek visszaadva `None` értékek, amelyeket egyetlen `True` érték követ. Írásvédett hozzáférés.

arraysize

A metódussal fetchmany a belső pufferméretet adja meg, amely azt is jelzi, hogy a rendszer hány sort hív le egyszerre a kiszolgálóról. Az alapértelmezett érték 10000. Szűk eredmények (olyan eredmények, amelyekben az egyes sorok nem tartalmaznak sok adatot), a jobb teljesítmény érdekében növelnie kell ezt az értéket.

Olvasási-írási hozzáférés.

description

Objektumokat tartalmazó Pythont list tuple tartalmaz. Mindegyik tuple objektum 7 értéket tartalmaz, és mindegyik tuple objektum első 2 eleme az egyetlen eredményoszlopot leíró információkat tartalmazza az alábbiak szerint:

- name: Az oszlop neve.
- type_code: Az oszlop típusát képviselő sztring. Egy egész szám oszlop például a következő típusú kóddal rendelkezik int: .

A 7 elemből tuple álló objektumok fennmaradó 5 eleme nincs implementálva, és az értékek nincsenek definiálva. Ezek általában 4-ként lesznek visszaadva
None értékek, amelyeket egyetlen True érték követ.

Írásvédett hozzáférés.

A kiválasztott Cursor metódusok a következők:

Metódusok
`cancel` Megszakítja a kurzor által indított adatbázis-lekérdezések vagy parancsok futtatását. A társított erőforrások kiszolgálón való kiadásához hívja meg a `close` metódus meghívása `cancel` után. Nincsenek paraméterek. Nincs visszatérési érték.
`close` Bezárja a kurzort, és felszabadítja a társított erőforrásokat a kiszolgálón. Egy már bezárt kurzor bezárása hibát jelezhet. Nincsenek paraméterek. Nincs visszatérési érték.
`execute` Előkészít és futtat egy adatbázis-lekérdezést vagy -parancsot. Nincs visszatérési érték. Paraméterek: `operation` Típus: `str` A előkészítendő és futtatandó lekérdezés vagy parancs. Ez a paraméter kötelező. Példa paraméter `parameters` nélkül: `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Példa a paraméterrel `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Típus: szótár A paraméterrel használandó paraméterek sorozata `operation` . Ez a paraméter nem kötelező. Az alapértelmezett érték `None`.
`executemany` Előkészít és futtat egy adatbázis-lekérdezést vagy parancsot az `seq_of_parameters` argumentum összes paraméterütemezésével. A rendszer csak a végső eredményhalmazt őrzi meg. Nincs visszatérési érték. Paraméterek: `operation` Típus: `str` A előkészítendő és futtatandó lekérdezés vagy parancs. Ez a paraméter kötelező. `seq_of_parameters` Típus: `listdict` Számos paraméterérték-készlet sorozata, amelyet a `operation` paraméter. Ez a paraméter kötelező.
`catalogs` Metaadat-lekérdezés végrehajtása a katalógusokról. A tényleges eredményeket ezután le kell kérni a következővel `fetchmany` : vagy `fetchall`. Az eredményhalmaz fontos mezői a következők: - Mező neve: `TABLE_CAT`. Típus: `str`. A katalógus neve. Nincsenek paraméterek. Nincs visszatérési érték. Az 1.0-s verzió óta
`schemas` Metaadat-lekérdezés végrehajtása a sémákról. A tényleges eredményeket ezután le kell kérni a következővel `fetchmany` : vagy `fetchall`. Az eredményhalmaz fontos mezői a következők: - Mező neve: `TABLE_SCHEM`. Típus: `str`. A séma neve. - Mező neve: `TABLE_CATALOG`. Típus: `str`. A katalógus, amelyhez a séma tartozik. Nincs visszatérési érték. Az 1.0-s verzió óta Paraméterek: `catalog_name` Típus: `str` Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `schema_name` Típus: `str` Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező.
`tables` Metaadat-lekérdezés végrehajtása táblákról és nézetekről. A tényleges eredményeket ezután le kell kérni a következővel `fetchmany` : vagy `fetchall`. Az eredményhalmaz fontos mezői a következők: - Mező neve: `TABLE_CAT`. Típus: `str`. A katalógus, amelyhez a tábla tartozik. - Mező neve: `TABLE_SCHEM`. Típus: `str`. Az a séma, amelyhez a tábla tartozik. - Mező neve: `TABLE_NAME`. Típus: `str`. A tábla neve. - Mező neve: `TABLE_TYPE`. Típus: `str`. A reláció típusa, például `VIEW` vagy `TABLE` (a Databricks Runtime 10.4 LTS és újabb verziókra, valamint a Databricks SQL-re vonatkozik; a Databricks Runtime korábbi verziói üres sztringet adnak vissza). Nincs visszatérési érték. Az 1.0-s verzió óta Paraméterek `catalog_name` Típus: `str` Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `schema_name` Típus: `str` Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `table_name` Típus: `str` Egy táblanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `table_types` Típus: `List[str]` Az egyező táblázattípusok listája, például`TABLE`.`VIEW` Ez a paraméter nem kötelező.
`columns` Metaadat-lekérdezés végrehajtása az oszlopokról. A tényleges eredményeket ezután le kell kérni a következővel `fetchmany` : vagy `fetchall`. Az eredményhalmaz fontos mezői a következők: - Mező neve: `TABLE_CAT`. Típus: `str`. Az a katalógus, amelyhez az oszlop tartozik. - Mező neve: `TABLE_SCHEM`. Típus: `str`. Az a séma, amelyhez az oszlop tartozik. - Mező neve: `TABLE_NAME`. Típus: `str`. Annak a táblának a neve, amelyhez az oszlop tartozik. - Mező neve: `COLUMN_NAME`. Típus: `str`. Az oszlop neve. Nincs visszatérési érték. Az 1.0-s verzió óta Paraméterek: `catalog_name` Típus: `str` Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `schema_name` Típus: `str` Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `table_name` Típus: `str` Egy táblanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező. `column_name` Típus: `str` Egy oszlopnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Ez a paraméter nem kötelező.
`fetchall` Lekéri egy lekérdezés összes (vagy az összes fennmaradó) sorát. Nincsenek paraméterek. A lekérdezés összes (vagy az összes fennmaradó) sorát adja vissza Python-értékként `list` . `Row` Objektumok. `Error` Ha a metódus előző hívása `execute` nem ad vissza adatokat, vagy még nem `execute` történt hívás.
`fetchmany` Lekéri a lekérdezés következő sorait. A lekérdezés következő sorainak legfeljebb `size` (vagy `arraysize` ha `size` nincs megadva) attribútumát adja vissza objektum Python-objektumként `list` `Row` . Ha a beolvasandó soroknál `size` kevesebb sor van hátra, a rendszer az összes többi sort visszaadja. `Error` Ha a metódus előző hívása `execute` nem ad vissza adatokat, vagy még nem `execute` történt hívás. Paraméterek: `size` Típus: `int` A következő lekérendő sorok száma. Ez a paraméter nem kötelező. Ha nincs megadva, a rendszer az `arraysize` attribútum értékét használja. Példa: `cursor.fetchmany(10)`
`fetchone` Lekéri az adathalmaz következő sorát. Nincsenek paraméterek. Az adathalmaz következő sorát adja vissza egyetlen sorozatként Pythonként `tuple` objektumot, vagy visszaadja `None` , ha nincs több elérhető adat. `Error` Ha a metódus előző hívása `execute` nem ad vissza adatokat, vagy még nem `execute` történt hívás.
`fetchall_arrow` PyArrow-objektumként `Table` lekéri egy lekérdezés összes (vagy az összes fennmaradó) sorát. A nagyon nagy mennyiségű adatot visszaadó lekérdezéseket inkább a memóriahasználat csökkentésére kell használni `fetchmany_arrow` . Nincsenek paraméterek. A lekérdezés összes (vagy az összes fennmaradó) sorát PyArrow-táblaként adja vissza. `Error` Ha a metódus előző hívása `execute` nem ad vissza adatokat, vagy még nem `execute` történt hívás. A 2.0-s verzió óta
`fetchmany_arrow` Lekéri a lekérdezés következő sorait PyArrow-objektumként `Table` . Visszaadja a `size` lekérdezés következő sorainak argumentumát (vagy `arraysize` ha `size` nincs megadva) Python PyArrow-ként `Table` tárgy. `Error` Ha a metódus előző hívása `execute` nem ad vissza adatokat, vagy még nem `execute` történt hívás. A 2.0-s verzió óta Paraméterek: `size` Típus: `int` A következő lekérendő sorok száma. Ez a paraméter nem kötelező. Ha nincs megadva, a rendszer az `arraysize` attribútum értékét használja. Példa: `cursor.fetchmany_arrow(10)`

`Row` osztály

A sorosztály egy rekordszerű adatstruktúra, amely egy egyéni eredménysort jelöl. Ha a sor tartalmaz egy oszlopot a névvel "my_column", akkor a "my_column" mező row a következőn keresztül row.my_columnérhető el: Numerikus indexekkel is elérheti például row[0]a mezőket. Ha az oszlopnév nem engedélyezett attribútummetódus-névként (például egy számjegygel kezdődik), akkor a mezőt a következőképpen row["1_my_column"]érheti el.

Az 1.0-s verzió óta

A kiválasztott Row metódusok a következők:

| asDict

A sor szótári ábrázolását adja vissza, amelyet mezőnevek indexelnek. Ha ismétlődő mezőnevek vannak, az ismétlődő mezők egyike (de csak egy) lesz visszaadva a szótárban. A visszaadott duplikált mező nincs meghatározva.

Nincsenek paraméterek.

Mezőket dict ad vissza. |

Típuskonverziók

Az alábbi táblázat az Apache Spark SQL-adattípusokat a Python-adattípus megfelelőire képezi le.

Apache Spark SQL-adattípus	Python-adattípus
`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`

Hibaelhárítás

`tokenAuthWrapperInvalidAccessToken: Invalid access token` üzenet

Probléma: A kód futtatásakor a következőhöz hasonló üzenet jelenik meg Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Lehetséges ok: Az átadott access_token érték nem érvényes Azure Databricks személyes hozzáférési jogkivonat.

Javasolt javítás: Ellenőrizze, hogy az átadott access_token érték helyes-e, majd próbálkozzon újra.

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

Probléma: A kód futtatásakor a következőhöz hasonló üzenet jelenik meg Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Lehetséges ok: Az átadott server_hostname érték nem a megfelelő állomásnév.

Javasolt javítás: Ellenőrizze, hogy az átadott server_hostname érték helyes-e, majd próbálkozzon újra.

A kiszolgáló állomásnevének megkereséséről további információt az Azure Databricks számítási erőforrás kapcsolati adatainak lekérése című témakörben talál.

`IpAclError` üzenet

Probléma: A kód futtatásakor megjelenik az üzenet Error during request to server: IpAclValidation , amikor egy Azure Databricks-jegyzetfüzetben próbálja használni az összekötőt.

Lehetséges ok: Lehetséges, hogy engedélyezve van az IP-engedélyezési lista az Azure Databricks-munkaterületen. Az IP-cím engedélyezésével a Spark-fürtök és a vezérlősík közötti kapcsolatok alapértelmezés szerint nem engedélyezettek.

Javasolt javítás: Kérje meg a rendszergazdát, hogy adja hozzá a számításisík-alhálózatot az IP-engedélyezési listához.

További erőforrások

További információk:

A Databricks SQL Connector for Python-adattár a GitHubon
Adattípusok
Beépített típusok (a boolPython webhelyén , bytearray, floatés intstr)
datetime (for datetime.date és datatime.datetime) a Python webhelyén
decimális (for decimal.Decimal) a Python webhelyén
Beépített konstansok (a NoneTypePython webhelyén)

Megosztás a következőn keresztül:

Databricks SQL Connector for Python

Követelmények

Első lépések

Fürt

SQL Warehouse

Hitelesítés

Databricks személyes hozzáférési jogkivonat hitelesítése

OAuth machine-to-machine (M2M) hitelesítés

Microsoft Entra-azonosító jogkivonat hitelesítése

OAuth user-to-machine (U2M) hitelesítés

Példák

Adatok lekérdezése

Adat beszúrása

Metaadatok lekérdezése

Kurzorok és kapcsolatok kezelése

Fájlok kezelése Unity Catalog-kötetekben

Naplózás konfigurálása

Tesztelés

API-referencia

Csomag

Modul

Osztályok

`Connection` osztály

`Cursor` osztály

`Row` osztály

Típuskonverziók

Hibaelhárítás

`tokenAuthWrapperInvalidAccessToken: Invalid access token` üzenet

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

`IpAclError` üzenet

További erőforrások

Visszajelzés

További források

Megosztás a következőn keresztül:

Databricks SQL Connector for Python

Követelmények

Első lépések

Fürt

SQL Warehouse

Hitelesítés

Databricks személyes hozzáférési jogkivonat hitelesítése

OAuth machine-to-machine (M2M) hitelesítés

Microsoft Entra-azonosító jogkivonat hitelesítése

OAuth user-to-machine (U2M) hitelesítés

Példák

Adatok lekérdezése

Adat beszúrása

Metaadatok lekérdezése

Kurzorok és kapcsolatok kezelése

Fájlok kezelése Unity Catalog-kötetekben

Naplózás konfigurálása

Tesztelés

API-referencia

Csomag

Modul

Osztályok

Connection osztály

Cursor osztály

Row osztály

Típuskonverziók

Hibaelhárítás

tokenAuthWrapperInvalidAccessToken: Invalid access token üzenet

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

IpAclError üzenet

További erőforrások

Visszajelzés

További források

`Connection` osztály

`Cursor` osztály

`Row` osztály

`tokenAuthWrapperInvalidAccessToken: Invalid access token` üzenet

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

`IpAclError` üzenet