Databricks SQL-összekötő Pythonhoz

A Databricks SQL Connector for Python egy Python-kódtár, amellyel Python-kód használatával futtathat SQL-parancsokat az Azure Databricks teljes célú számítási és Databricks SQL-tárolóiban. 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.

Fontos

A Databricks SQL Connector for Python 3.0.0-s és újabb verziója támogatja a natív paraméteres lekérdezés-végrehajtást, amely megakadályozza az SQL-injektálást, és javíthatja a lekérdezési teljesítményt. A korábbi verziók beágyazott paraméteres végrehajtást használtak, ami nem biztonságos az SQL-injektálástól, és más hátrányai is vannak. További információ: Natív paraméterek használata.

A Pythonhoz készült Databricks SQL-összekötő támogatja az Azure Databricks SQLAlchemy dialektusát is, de a funkciók használatához telepíteni kell. Lásd: Az SQLAlchemy használata az Azure Databricksben.

Követelmények

Python 3.8-at vagy újabb verziót futtató 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ő teljes célú számítási vagy SQL-raktár.

Első lépések

Telepítse a Pythonhoz készült Databricks SQL-összekötőt. A PyArrow a Databricks SQL Connector for Python opcionális függősége, és alapértelmezés szerint nincs telepítve az összekötő 4.0.0-s és újabb verziójában. Ha a PyArrow nincs telepítve, az olyan funkciók, mint a CloudFetch és más Apache Arrow funkciók nem érhetők el, ami befolyásolhatja a nagy mennyiségű adat teljesítményét.
- A „lean connector” telepítéséhez használja a következőt:
```
pip install databricks-sql-connector
```
- A teljes összekötő ( beleértve a PyArrow-t is) telepítéséhez használja a következőket:
```
pip install databricks-sql-connector[pyarrow]
```
Gyűjtse össze a következő információkat a használni kívánt teljes célú számítási vagy SQL-raktárral kapcsolatban:

Teljes körű számítás
- A teljes célú számítás kiszolgálói állomásneve. Ezt a kiszolgáló gazdagépneve értékéből szerezheti be a speciális beállítások > JDBC/ODBC lapján a teljes célú számításhoz.
- A teljes célú számítás HTTP-elérési útja. Ezt a teljes célú számítás lapján található > értékéből szerezheti be.
Feljegyzés

Az SQL-csatlakozó nem támogatja a számítási munkákhoz való csatlakozást.

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 ID token hitelesítés
OAuth machine-to-machine (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. Ehhez kövesse a munkaterület-felhasználók személyes hozzáférési jogkivonatainak létrehozása című szakasz lépéseit.

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Állítsa a kiszolgáló gazdagépneve értékre a teljes célú számítási vagy SQL-raktár esetében.
DATABRICKS_HTTP_PATH, állítsa HTTP Path értékre az általános célú számítási vagy SQL tárolóhoz.
DATABRICKS_TOKEN beállítása az Azure Databricks személyes hozzáférési tokenre.

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 gép-gép közötti (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 Databricks SDK for Python 0.18.0 vagy újabb verzióját is telepítenie kell (például a vagy a pip install databricks-sdk futtatásával).

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: Szolgáltatásnév hozzáférésének engedélyezése az Azure Databrickshez az OAuth 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ási főazonosítónak az általános célú számítási egységhez vagy raktárhoz.

Ha hozzáférést szeretne adni a szolgáltatási főnévnek az általános célú számításhoz vagy tárházhoz, tekintse meg a számítási engedélyeket vagy az SQL-tárház 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 a kiszolgáló gazdagépneve értékre állítsa be a teljes célú számítási vagy SQL-raktár esetében.
DATABRICKS_HTTP_PATH, állítsa HTTP Path értékre az általános célú számítási vagy SQL tárolóhoz.
DATABRICKS_CLIENT_ID, állítsa be a szolgáltatás főképviselőjének UUID - vagy alkalmazásazonosítójá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ó token 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 manuális beszerzése.
A Microsoft Entra ID szolgáltatásnévvel kapcsolatban lásd: Jogkivonatok lekérése szolgáltatásnevekhez. A Microsoft Entra ID által felügyelt szolgáltatásnév létrehozásához tekintse meg a szolgáltatásnevek című témakört.

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 kiszolgálói gazdagépnév értékét a teljes célú számításhoz vagy az SQL Warehouse-hoz.
Állítsa be a DATABRICKS_HTTP_PATHHTTP útvonal értékét általános célú számításhoz vagy SQL raktárhoz.
Á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 felhasználó-gép (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 Databricks SDK for Python 0.19.0-s vagy újabb verzióját is telepítenie kell (például úgy, hogy futtat egy pip install databricks-sdk vagy pedig python -m 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 kiszolgálói gazdagépnév értékét a teljes célú számításhoz vagy az SQL Warehouse-hoz.
Állítsa be a DATABRICKS_HTTP_PATHHTTP útvonal értékét általános célú számításhoz vagy SQL raktárhoz.

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 adatok lekérdezésére és beszúrására, metaadatok lekérdezésére, kurzorok és kapcsolatok kezelésére, fájlok kezelésére a Unity Catalogban és 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 más hitelesítési típust szeretne használni, olvassa el a Hitelesítés című témakört.

Ezek a példakódok az alábbi környezeti változókból szerzik meg a server_hostname, http_path és access_token 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.

User-Agent beállítása

Az alábbi példakód bemutatja, hogyan állíthatja be a User-Agent alkalmazás product_name a használatkövetéshez.

from databricks import sql
import os

with sql.connect(server_hostname   = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path         = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token      = os.getenv("DATABRICKS_TOKEN"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

Adatok lekérdezése

Az alábbi példakód bemutatja, hogyan hívhatja meg a Databricks SQL Connector for Pythont egy alapszintű SQL-parancs futtatásához a teljes célú számítási vagy SQL Warehouse-on. Ez a parancs a trips katalógus samples sémájának nyctaxi táblázatából adja vissza az első két 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("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
    result = cursor.fetchall()

    for row in result:
      print(row)

Lekérdezéscímkék

Fontos

A funkció privát előzetes verzióban érhető el. A hozzáférés kéréséhez lépjen kapcsolatba a fiókcsapattal.

Az alábbi példa bemutatja, hogyan csatolhat kulcs-érték címkéket az SQL-lekérdezésekhez nyomkövetési és elemzési célokra. A lekérdezéscímkék megjelennek a system.query.history táblában.

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

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

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

    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 töltse fel az adatokat a felhőbeli tárolóba, majd hajtsa végre 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 felszabadítja az erőforrásokat az Azure Databricks teljes célú számítási és Databricks SQL-raktárai számára.

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

  with connection.cursor() as cursor:

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

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

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

Naplózás konfigurálása

A Databricks SQL Connector a Python szabványos naplózási modulját használja. Az alábbi példa konfigurálja a naplózási szintet, és létrehoz egy hibakeresési naplót:

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ő trips tábla megadott számú adatsorának samples 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("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

Adott egy main.py nevű fájl, amely meghívja a get_connection_personal_access_token és select_nyctaxi_trips függvényeket:

# 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 egy SELECT utasítást tartalmaz, és ezért nem módosítja a trips tábla állapotát, ebben a példában a mockolás nem feltétlenül szükséges. A gúnyolással azonban gyorsan futtathatja a teszteket anélkül, hogy tényleges kapcsolatra kellene várnia a munkaterülettel. A tesztelési módszerek lehetővé teszik, hogy szimulált teszteket többször is futtasson olyan függvények esetében, amelyek megváltoztathatják egy tábla állapotát, mint például INSERT INTO, UPDATE és DELETE FROM.

API-referencia

Ez a szakasz a csomagHOZ tartozó API-referenciát databricks-sql-connector tartalmazza. Lásd : databricks-sql-connector a Python-csomagindexben (PyPI).

Modul

A databricks.sql csomag modulja databricks-sql-connector tartalmazza az SQL-raktárral való kapcsolat inicializálásának módszerét.

kapcsolódási módszer

Inicializál egy KAPCSOLATOT egy SQL-raktárral. Kapcsolatobjektumot ad vissza.

Paraméter	Típus	Description
`server_hostname`	`str`	Szükséges. A kiszolgáló állomásneve a teljes célú számításhoz vagy az SQL Warehouse-hoz, például `adb-1234567890123456.7.azuredatabricks.net`. A kiszolgáló állomásnevének lekéréséhez tekintse meg az Első lépések című témakör utasításait.
`http_path`	`str`	Szükséges. A teljes célú számítási vagy SQL-raktár HTTP-elérési útja, például `sql/protocolv1/o/1234567890123456/1234-567890-test123` teljes célú számításhoz vagy `/sql/1.0/warehouses/a1b234c567d8e9fa` SQL-raktárhoz. A HTTP-elérési út lekéréséhez tekintse meg az Első lépések című témakör utasításait.
`access_token`, `auth_type`, `credentials_provider`, `password`, , `username`	`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`	`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`. Példa: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Opcionális. További (kulcs, érték) párok beállítása a HTTP-fejlécekben minden RPC-kérelemhez, amelyet az ügyfél tesz. A használat általában nem állít be további HTTP-fejléceket. Alapértelmezett érték: `None`.
`catalog`	`str`	Opcionális. A kapcsolathoz használni kívánt kezdeti katalógus. Alapértelmezés szerint `None` (ebben az esetben az alapértelmezett katalógust `hive_metastore` használja a rendszer).
`schema`	`str`	Opcionális. A kapcsolathoz használandó kezdeti séma. Alapértelmezett érték `None` (ebben az esetben az alapértelmezett séma `default` lesz használva). A 2.0-s verzió óta
`use_cloud_fetch`	`bool`	Opcionális. Azt határozza meg, hogy a lekéréses kérelmeket közvetlenül a felhőobjektum-tárolóba küldi-e az adattömbök letöltéséhez. Alapértelmezett érték: `True`. Beállíthatja, hogy `False` a lekéréses kérelmeket közvetlenül az Azure Databricksnek küldje el. 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
`user_agent_entry`	`str`	Opcionális. A User-Agent bejegyzés, amelyet be kell illeszteni a HTTP-kérelem fejlécébe a használat nyomon követéséhez. Alapértelmezett érték: `PyDatabricksSqlConnector`.

`Connection` osztály

Számítási vagy SQL-raktárral létesített kapcsolatot jelöl.

Metódusok

Az Connection osztály a következő metódusokat biztosítja.

Metódus	Description
`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 `Error` hibát dobnak. Nincsenek paraméterek. Nincs visszatérési érték.
`cursor`	Egy új kurzorobjektumot ad vissza, amely lehetővé teszi az adatbázis rekordjainak bejárását. Nincsenek paraméterek.

`Cursor` osztály

Adatrekordok bejárására szolgáló mechanizmust jelöl.

Objektum létrehozásához hívja meg a Cursorcursor metódusát.

Attribútumok

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

Attribute Description

arraysize A fetchmany metódussal megadja a belső pufferméretet, és ezzel határozza meg, hogy ténylegesen hány sort hív le egyszerre a kiszolgálóról. Az alapértelmezett érték 10000. A szűk eredmények esetében (amikor az egyes sorok nem tartalmaznak sok adatot), a jobb teljesítmény érdekében növelje ezt az értéket. Olvasási-írási hozzáférés.

Attribute	Description
`arraysize`	A `fetchmany` metódussal megadja a belső pufferméretet, és ezzel határozza meg, hogy ténylegesen hány sort hív le egyszerre a kiszolgálóról. Az alapértelmezett érték `10000`. A szűk eredmények esetében (amikor az egyes sorok nem tartalmaznak sok adatot), a jobb teljesítmény érdekében növelje ezt az értéket. Olvasási-írási hozzáférés.
`description`	Python `list` tartalmaz, amely `tuple` objektumokat 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ő karakterlánc. 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. Ezeket általában 4 `None` értékként, majd egyetlen `True` értékként adja vissza. Írásvédett hozzáférés.

description

Python list tartalmaz, amely tuple objektumokat 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ő karakterlánc. 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. Ezeket általában 4 None értékként, majd egyetlen True értékként adja vissza. Írásvédett hozzáférés.

Metódusok

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

Metódus	Description
`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ó felszabadításához hívja meg a `close` metódust a `cancel` metódus meghívása 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. Paraméterek: `operation`:Szükséges. A előkészítendő és futtatandó lekérdezés vagy parancs. Típus: `str` Példa paraméter `parameters` nélkül: `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Példa a `parameters` paraméterrel (natív pozícióparaméterek használatával): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: Nem kötelező. A `operation` paraméterrel használandó paraméterek sorozata. Az alapértelmezett érték `None`. Típus: `dictionary` Nincs visszatérési érték.
`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. Paraméterek: `operation`:Szükséges. A előkészítendő és futtatandó lekérdezés vagy parancs. Típus: `str` `seq_of_parameters`:Szükséges. Számos paraméterérték-készletsorozat a `operation` paraméterhez való használatra. Típus: `list` a `dict` közül Nincs visszatérési érték.
`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`. A katalógus neve. Típus: `str` 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`. A séma neve. Típus: `str` Mező neve: `TABLE_CATALOG`. A katalógus, amelyhez a séma tartozik. Típus: `str` Paraméterek: `catalog_name`: Nem kötelező. Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `schema_name`: Nem kötelező. Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` Nincs visszatérési érték. Az 1.0-s verzió óta
`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`. A katalógus, amelyhez a tábla tartozik. Típus: `str` Mező neve: `TABLE_SCHEM`. Az a séma, amelyhez a tábla tartozik. Típus: `str` Mező neve: `TABLE_NAME`. A tábla neve. Típus: `str` Mező neve: `TABLE_TYPE`. 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). Típus: `str` Paraméterek: `catalog_name`: Nem kötelező. Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `schema_name`: Nem kötelező. Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `table_name`: Nem kötelező. Az a táblanév, amelyről információt szeretne lekérdezni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `table_types`: Nem kötelező. Az egyező táblázattípusok listája, például`TABLE`.`VIEW` Típus: `List[str]` Nincs visszatérési érték. Az 1.0-s verzió óta
`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`. Az a katalógus, amelyhez az oszlop tartozik. Típus: `str` Mező neve: `TABLE_SCHEM`. Az a séma, amelyhez az oszlop tartozik. Típus: `str` Mező neve: `TABLE_NAME`. Annak a táblának a neve, amelyhez az oszlop tartozik. Típus: `str` Mező neve: `COLUMN_NAME`. Az oszlop neve. Típus: `str` Paraméterek: `catalog_name`: Nem kötelező. Katalógusnév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `schema_name`: Nem kötelező. Sémanév, amelyről információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `table_name`: Nem kötelező. Az a táblanév, amelyről információt szeretne lekérdezni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` `column_name`: Nem kötelező. Egy oszlopnév, amelyhez információt szeretne lekérni. A `%` karaktert helyettesítő karakterként értelmezi a rendszer. Típus: `str` Nincs visszatérési érték. Az 1.0-s verzió óta
`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 az objektumok Pythonjaként `listRow` adja vissza. Kivételt dob, ha az előző `Error` metódushívás nem adott vissza adatot, vagy ha még nem történt `execute` hívás.
`fetchmany`	Lekéri a lekérdezés következő sorait. Paraméterek: `size`: Nem kötelező. A következő lekérendő sorok száma. Ha nincs megadva, a rendszer az `arraysize` attribútum értékét használja. Típus: `int`. Példa: `cursor.fetchmany(10)` A lekérdezés következő sorai közül legfeljebb `size` (vagy a `arraysize` attribútum, ha `size` nincs megadva) eredményét adja vissza Python `list`-ként, amely `Row` objektumokat tartalmaz. Ha a beolvasandó soroknál `size` kevesebb sor van hátra, a rendszer az összes többi sort visszaadja. Kivételt dob, ha az előző `Error` metódushívás nem adott vissza adatot, vagy ha még nem történt `execute` hívás.
`fetchone`	Lekéri az adathalmaz következő sorát. Nincsenek paraméterek. Az adathalmaz következő sorát adja vissza egyetlen sorozatként Python-objektumként `tuple` , vagy visszaadja `None` , ha nincs több elérhető adat. Kivételt dob, ha az előző `Error` metódushívás nem adott vissza adatot, vagy ha még nem történt `execute` 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. Kivételt dob, ha az előző `Error` metódushívás nem adott vissza adatot, vagy ha még nem történt `execute` hívás. A 2.0-s verzió óta
`fetchmany_arrow`	Lekéri a lekérdezés következő sorait PyArrow-objektumként `Table` . Paraméterek: `size`: Nem kötelező. A következő lekérendő sorok száma. Ha nincs megadva, a rendszer az `arraysize` attribútum értékét használja. Típus: `int`. Példa: `cursor.fetchmany_arrow(10)` Legfeljebb a `size` argumentum (vagy a `arraysize` attribútum, ha a `size` nincs megadva) szerinti számú sorát adja vissza egy lekérdezés következő sorai közül, Python PyArrow-objektumként a `Table`-ba. Kivételt dob, ha az előző `Error` metódushívás nem adott vissza adatot, vagy ha még nem történt `execute` hívás. A 2.0-s verzió óta

`Row` osztály

A sorosztály egy rekordszerű adatstruktúra, amely egy SQL-lekérdezés eredményében szereplő 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:

Metódusok

Metódus	Description
`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.

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`

Telemetriai gyűjtemény

A Pythonhoz készült Databricks SQL Connector telemetriai adatokat gyűjt, hogy segítsen az Azure Databricksnek a megbízhatóság javításában és a problémák elhárításában. A telemetria alapértelmezés szerint engedélyezve van, és a következő működési adatokat gyűjti:

Ügyfélkörnyezet részletei, például illesztőprogram-verzió, Python-futtatókörnyezet és operációs rendszer
Illesztőprogram-kapcsolat konfigurációi (a személyazonosításra alkalmas adatok kivételével)
Művelet késésének mérése
Végrehajtási eredményformátumok, például beágyazott JSON vagy Apache Arrow
Művelettípusok, például lekérdezések végrehajtása, metaadat-lekérdezések vagy kötetműveletek
Hibabesorolási adatok
Újrapróbálkozások száma

Fontos

Az Azure Databricks nem gyűjt lekérdezési tartalmat, lekérdezési eredményeket vagy személyes azonosításra alkalmas adatokat (PII) telemetrián keresztül.

A telemetria gyűjtés letiltásához állítsa be a enable_telemetry paramétert 0-re kapcsolat létrehozásakor.

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. IP-címek engedélyezési listájának használatával a Spark-fürtökből a vezérlősíkba történő 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 tárház a GitHubon
Adattípusok
Beépített típusok (a Python webhelyén: bool, bytearray, float, int, és str)
datetime (datetime.date és datatime.datetime vonatkozóan) a Python webhelyén
decimális (a decimal.Decimal számára) a Python webhelyén
Beépített konstansok (a NoneTypePython webhelyén)

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-10-31

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

Databricks SQL-összekötő Pythonhoz

Követelmények

Első lépések

Teljes körű számítás

SQL Warehouse

Hitelesítés

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

OAuth gép-gép közötti (M2M) hitelesítés

Microsoft Entra azonosító token hitelesítése

OAuth felhasználó-gép (U2M) hitelesítés

Példák

User-Agent beállítása

Adatok lekérdezése

Lekérdezéscímkék

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

Modul

kapcsolódási módszer

Connection osztály

Metódusok

Cursor osztály

Attribútumok

Metódusok

Row osztály

Metódusok

Típuskonverziók

Telemetriai gyűjtemény

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