Konektor SQL Pro Databricks pro Python

Článek
01/21/2025

Konektor SQL Databricks pro Python je knihovna Pythonu, která umožňuje používat kód Pythonu ke spouštění příkazů SQL v clusterech Azure Databricks a datových skladech SQL Databricks. Konektor SQL Databricks pro Python je jednodušší nastavit a používat než podobné knihovny Pythonu, jako je pyodbc. Tato knihovna se řídí PEP 249 – Specifikace rozhraní API služby Python Database v2.0.

Poznámka:

Konektor SQL Databricks pro Python podporuje také dialekt SQLAlchemy pro Azure Databricks, ale musí být nainstalovaný pro použití těchto funkcí. Viz Použití SQLAlchemy s Azure Databricks.

Požadavky

Vývojový počítač s Pythonem >=3.8 a <=3.11.
Databricks doporučuje používat virtuální prostředí Pythonu, například prostředí, která poskytuje venv , která jsou součástí Pythonu. Virtuální prostředí pomáhají zajistit, abyste společně používali správné verze Pythonu a konektor SQL Databricks pro Python. Nastavení a používání virtuálních prostředí je mimo rozsah tohoto článku. Další informace najdete v tématu Vytváření virtuálních prostředí.
Existující cluster nebo SQL Warehouse.

Začněte

Nainstalujte konektor SQL Databricks pro Python. PyArrow je volitelná závislost konektoru Databricks SQL pro Python a ve výchozím nastavení není nainstalovaná. Pokud neinstalujete PyArrow, funkce, jako je CloudFetch a další funkce Apache Arrow, nejsou k dispozici, což může mít vliv na výkon pro velké objemy dat.
- K instalaci štíhlého konektoru použijte pip install databricks-sql-connector.
- K instalaci kompletního konektoru, včetně PyArrow, použijte pip install databricks-sql-connector[pyarrow].
Shromážděte následující informace pro cluster nebo SQL Warehouse, který chcete použít:

Cluster
- Název hostitele serveru clusteru. Hodnotu názvu hostitele serveru můžete získat na kartě Upřesnit možnosti > JDBC/ODBC pro váš cluster.
- Cesta HTTP clusteru. Můžete to získat z hodnoty cesty HTTP ve vašem clusteru, na kartěUpřesněné možnosti v sekci JDBC/ODBC.
SQL Warehouse
- Název hostitele serveru služby SQL Warehouse. Můžete to získat z hodnoty názvu hostitele na záložce Podrobnosti připojení pro vaše SQL datové úložiště.
- Cesta HTTP služby SQL Warehouse. Můžete to získat z hodnoty cesta HTTP na kartě podrobnosti o připojení pro váš SQL Warehouse.

Ověřování

Konektor SQL Databricks pro Python podporuje následující typy ověřování Azure Databricks:

Ověřování osobního přístupového tokenu Databricks
Ověřování tokenu Microsoft Entra ID
Ověřování OAuth mezi počítači (M2M)
Ověřování uživatele OAuth na počítač (U2M)

Konektor SQL Databricks pro Python zatím nepodporuje následující typy ověřování Azure Databricks:

Ověřování osobního přístupového tokenu Databricks

Pokud chcete používat konektor SQL Databricks pro Python s ověřováním osobního přístupového tokenu Azure Databricks, musíte nejprve vytvořit osobní přístupový token Azure Databricks. Postupujte podle kroků v tokenech pat přístupových tokenů Azure Databricks pro uživatele pracovního prostoru.

K ověření konektoru SQL Databricks pro Python použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

DATABRICKS_SERVER_HOSTNAMEnastavena na hodnotu názvu hostitele serveru pro váš cluster nebo SQL skladiště.
DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP cesty pro váš cluster nebo SQL warehouse.
Nastavte DATABRICKS_TOKENna osobní přístupový token Azure Databricks.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování M2M (machine-to-machine) OAuth

Konektor SQL Databricks pro Python verze 2.7.0 a vyšší podporují ověřování OAuth typu machine-to-machine (M2M). Musíte také nainstalovat sadu Databricks SDK pro Python 0.18.0 nebo vyšší (například spuštěním pip install databricks-sdk nebo python -m pip install databricks-sdk).

Pokud chcete používat konektor SQL Databricks pro Python s ověřováním OAuth M2M, musíte udělat toto:

V pracovním prostoru Azure Databricks vytvořte instanční objekt Azure Databricks a vytvořte pro tento instanční objekt tajný klíč OAuth.

Pokud chcete vytvořit instanční objekt a jeho tajný klíč OAuth, přečtěte si téma Ověřování přístupu k Azure Databricks pomocí instančního objektu pomocí OAuth (OAuth M2M). Poznamenejte si hodnotu UUID nebo ID aplikace instančního objektu a hodnotu Secret pro tajný klíč OAuth instančního objektu.
Dejte danému instančnímu objektu přístup ke clusteru nebo skladu.

Pokud chcete instančnímu objektu udělit přístup ke clusteru nebo skladu, přečtěte si informace o oprávněních výpočetních prostředků nebo správě služby SQL Warehouse.

K ověření konektoru SQL Databricks pro Python použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

DATABRICKS_SERVER_HOSTNAME nastavena na hodnotu názvu hostitele serveru pro váš klastr nebo SQL sklad.
DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP cesty pro váš cluster nebo SQL warehouse.
DATABRICKS_CLIENT_ID, nastavte na hodnotu UUID služby nebo na hodnotu ID aplikace.
DATABRICKS_CLIENT_SECRET, nastavte na hodnotu Secret pro OAuth tajemství služebního účtu.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování tokenu Microsoft Entra ID

Pokud chcete používat konektor SQL Databricks pro Python s ověřováním tokenu ID Microsoft Entra, musíte poskytnout konektor SQL Databricks pro Python s tokenem Microsoft Entra ID. Pokud chcete vytvořit přístupový token Microsoft Entra ID, postupujte takto:

Pro uživatele Azure Databricks můžete použít Azure CLI. Viz Získání tokenů ID Microsoft Entra pro uživatele pomocí azure CLI.
Pro instanční objekt služby Microsoft Entra ID viz Získání přístupového tokenu Microsoft Entra ID pomocí Azure CLI. Informace o vytvoření spravovaného instančního objektu Microsoft Entra ID najdete v tématu Správa instančních objektů.

Tokeny MICROSOFT Entra ID mají výchozí životnost přibližně 1 hodinu. Pokud chcete vytvořit nový token ID Microsoft Entra, opakujte tento proces.

K ověření konektoru SQL Databricks pro Python použijte následující fragment kódu. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

Nastavte DATABRICKS_SERVER_HOSTNAME na hodnotu názvu hostitele serveru pro váš cluster nebo SQL Warehouse.
Nastavte DATABRICKS_HTTP_PATH na hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
Přiřaďte DATABRICKS_TOKEN k tokenu Microsoft Entra ID.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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

Ověřování uživatele OAuth na počítač (U2M)

Konektor SQL Databricks pro Python verze 2.7.0 a vyšší podporují ověřování uživatelem AAuth (U2M). Musíte také nainstalovat sadu Databricks SDK pro Python 0.19.0 nebo novější (například spuštěním pip install databricks-sdk nebo python -m pip install databricks-sdk).

K ověření konektoru SQL Databricks pro Python s ověřováním OAuth U2M použijte následující fragment kódu. Ověřování OAuth U2M používá k ověření cílového uživatelského účtu Azure Databricks přihlášení člověka v reálném čase a souhlas. Tento fragment kódu předpokládá, že jste nastavili následující proměnné prostředí:

Nastavte DATABRICKS_SERVER_HOSTNAME na hodnotu názvu hostitele serveru pro váš cluster nebo SQL Warehouse.
Nastavte DATABRICKS_HTTP_PATH na hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.

Pokud chcete nastavit proměnné prostředí, přečtěte si dokumentaci k vašemu operačnímu systému.

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říklady

Následující příklady kódu ukazují, jak pomocí konektoru Databricks SQL pro Python dotazovat a vkládat data, metadata dotazů, spravovat kurzory a připojení a konfigurovat protokolování.

Poznámka:

Následující příklady kódu ukazují, jak k ověřování použít osobní přístupový token Azure Databricks. Pokud chcete místo toho použít jiné dostupné typy ověřování Azure Databricks, přečtěte si téma Ověřování.

Tyto příklady kódu načtou hodnoty připojovacích proměnných server_hostname, http_patha access_token z těchto proměnných prostředí:

DATABRICKS_SERVER_HOSTNAME, který představuje hodnotu názvu hostitele serveru z požadavků.
DATABRICKS_HTTP_PATH, který představuje hodnotu cesty HTTP z požadavků.
DATABRICKS_TOKEN, který představuje váš přístupový token z požadavků.

K načtení těchto hodnot proměnných připojení můžete použít jiné přístupy. Použití proměnných prostředí je jen jedním z mnoha přístupů.

Dotazování dat
Vložte data
Metadata dotazů
Správa kurzorů a připojení
Správa souborů ve svazcích katalogu Unity
Konfigurace protokolování

Zadávání dotazů na data

Následující příklad kódu ukazuje, jak volat Konektor SQL Databricks pro Python ke spuštění základního příkazu SQL v clusteru nebo SQL Warehouse. Tento příkaz vrátí první dva řádky z tabulky trips ve schématu samples katalogu nyctaxi.

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)

Vložení dat

Následující příklad ukazuje, jak vložit malé objemy dat (tisíce řádků):

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)

U velkých objemů dat byste nejprve měli nahrát data do cloudového úložiště a pak spustit příkaz COPY INTO.

Metadata dotazů

Existují vyhrazené metody pro načítání metadat. Následující příklad načte metadata o sloupcích v ukázkové tabulce:

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

Správa kurzorů a připojení

Osvědčeným postupem je zavřít všechna připojení a kurzory, které se už nepoužívají. Tím se uvolní prostředky v clusterech Azure Databricks a skladech SQL Databricks.

Ke správě prostředků můžete použít správce kontextu ( with syntaxi použitou v předchozích příkladech) nebo explicitně volat 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()

Správa souborů ve svazcích katalogu Unity

Konektor SQL Databricks umožňuje zapisovat místní soubory do katalogu Unity svazky, stahovat soubory ze svazků a odstraňovat soubory ze svazků, jak je znázorněno v následujícím příkladu:

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

Konfigurace protokolování

Konektor SQL Databricks používá standardní modul protokolování Pythonu. Úroveň protokolování můžete nakonfigurovat podobně jako v následujícím příkladu:

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

Testování

K otestování kódu použijte testovací architektury Pythonu, jako je pytest. K otestování kódu za simulovaných podmínek bez volání koncových bodů rozhraní REST API Služby Azure Databricks nebo změny stavu účtů nebo pracovních prostorů Azure Databricks můžete použít knihovny napodobování Pythonu, jako je unittest.mock.

Například vzhledem k následujícímu souboru s názvem helpers.py obsahující funkci get_connection_personal_access_token, která k vrácení připojení k pracovnímu prostoru Azure Databricks používá osobní přístupový token Azure Databricks, a select_nyctaxi_trips funkci, která pomocí připojení získá zadaný počet řádků dat z tabulky trips ve schématu samples katalogu nyctaxi:

# 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

A vzhledem k následujícímu souboru, main.py který volá get_connection_personal_access_token funkce a select_nyctaxi_trips funkce:

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

Následující soubor s názvem test_helpers.py testuje, zda select_nyctaxi_trips funkce vrátí očekávanou odpověď. Místo vytvoření skutečného připojení k cílovému pracovnímu prostoru tento test napodobí Connection objekt. Test také napodobí některá data, která odpovídají schématu a hodnotám, které jsou ve skutečných datech. Test vrátí napodobená data prostřednictvím napodobeného připojení a pak zkontroluje, jestli jedna z hodnot napodobených řádků dat odpovídá očekávané hodnotě.

# 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

Protože funkce select_nyctaxi_trips obsahuje příkaz SELECT a tím pádem nemění stav tabulky trips, není v tomto příkladu simulace zcela povinná. Napodobování ale umožňuje rychle spouštět testy bez čekání na skutečné připojení k pracovnímu prostoru. Mockování také umožňuje provádět simulované testy opakovaně pro funkce, které mohou změnit stav tabulky, jako například INSERT INTO, UPDATEa DELETE FROM.

Balíček

databricks-sql-connector

Použití: pip install databricks-sql-connector

Viz také databricks-sql-connector v indexu balíčků Pythonu (PyPI).

Modul

databricks.sql

Použití: from databricks import sql

Třídy

Vybrané třídy zahrnují následující:

Třídy
`Connection` Relace výpočetního prostředku Azure Databricks
`Cursor` Mechanismus pro procházení datových záznamů
`Row` Řádek dat ve výsledku dotazu SQL

Třída `Connection`

Chcete-li vytvořit objekt Connection, zavolejte metodu databricks.sql.connect s následujícími parametry:

Parametry
`server_hostname` Typ: `str` Název hostitele serveru pro cluster nebo SQL Warehouse. Pokud chcete získat název hostitele serveru, přečtěte si pokyny uvedené výše v tomto článku. Tento parametr je povinný. Příklad: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Typ: `str` Cesta HTTP clusteru nebo SQL Warehouse. Pokud chcete získat cestu HTTP, přečtěte si pokyny uvedené výše v tomto článku. Tento parametr je povinný. Příklad: `sql/protocolv1/o/1234567890123456/1234-567890-test123` pro cluster. `/sql/1.0/warehouses/a1b234c567d8e9fa` pro SQL Warehouse.
`access_token`, `auth_type` Typ: `str` Informace o nastavení ověřování Azure Databricks Podrobnosti najdete v tématu Ověřování.
`session_configuration` Typ: `dict[str, Any]` Slovník parametrů konfigurace relace Sparku. Nastavení konfigurace je ekvivalentní použití `SET key=val` příkazu SQL. Spuštěním příkazu SQL `SET -v` získejte úplný seznam dostupných konfigurací. Výchozí hodnota `None`je . Tento parametr je volitelný. Příklad: `{"spark.sql.variable.substitute": True}`
`http_headers` Typ: `List[Tuple[str, str]]]` Další dvojice (klíč, hodnota), které se mají nastavit do hlaviček HTTP u každého požadavku RPC, který klient provede. V typickém použití se nenastaví žádné další hlavičky HTTP. Výchozí hodnota `None`je . Tento parametr je volitelný. Od verze 2.0
`catalog` Typ: `str` Počáteční katalog, který se má použít pro připojení. Výchozí hodnota je `None` (v takovém případě se použije výchozí katalog, obvykle `hive_metastore`). Tento parametr je volitelný. Od verze 2.0
`schema` Typ: `str` Počáteční schéma, které se má použít pro připojení. Výchozí hodnota je `None` (v takovém případě se použije výchozí schéma `default`). Tento parametr je volitelný. Od verze 2.0
`use_cloud_fetch` Typ: `bool` `True` pro odesílání žádostí o načtení přímo do cloudového úložiště objektů za účelem stahování bloků dat. `False` (výchozí) pro odesílání žádostí o načtení přímo do Azure Databricks. Pokud je `use_cloud_fetch` nastavená na `True` ale přístup k síti je zablokovaný, požadavky na načtení selžou. Od verze 2.8

Vybrané Connection metody zahrnují následující:

Metody
`close` Zavře připojení k databázi a uvolní všechny přidružené prostředky na serveru. Jakékoli další volání tohoto připojení vyvolá výjimku `Error`. Žádné parametry. Žádná návratová hodnota.
`cursor` Vrátí nový `Cursor` objekt, který umožňuje procházení záznamů v databázi. Žádné parametry.

Třída `Cursor`

Chcete-li vytvořit Cursor objekt, zavolejte metodu Connectioncursor třídy.

Mezi vybrané Cursor atributy patří:

Atributy

Atributy
`arraysize` Používá se s metodou `fetchmany` , určuje velikost interní vyrovnávací paměti, což je také to, kolik řádků se skutečně načte ze serveru najednou. Výchozí hodnota je `10000`. Pro úzké výsledky (výsledky, ve kterých každý řádek neobsahuje velké množství dat), byste tuto hodnotu měli zvýšit pro lepší výkon. Přístup pro čtení i zápis.
`description` Obsahuje Python `list` objektů `tuple` . Každý z těchto `tuple` objektů obsahuje 7 hodnot, přičemž prvních 2 položek každého objektu `tuple` obsahující informace popisující jeden výsledný sloupec následujícím způsobem: - `name`: Název sloupce. - `type_code`: Řetězec představující typ sloupce. Například celočíselný sloupec bude mít typový kód `int`. Zbývajících 5 položek každého 7 položek `tuple` objektu nejsou implementovány a jejich hodnoty nejsou definovány. Obvykle se vrátí jako 4. Hodnoty `None` následované jednou hodnotou `True`. Přístup jen pro čtení.

arraysize

Používá se s metodou fetchmany , určuje velikost interní vyrovnávací paměti, což je také to, kolik řádků se skutečně načte ze serveru najednou. Výchozí hodnota je 10000. Pro úzké výsledky (výsledky, ve kterých každý řádek neobsahuje velké množství dat), byste tuto hodnotu měli zvýšit pro lepší výkon.

Přístup pro čtení i zápis.

description

Obsahuje Python list objektů tuple . Každý z těchto tuple objektů obsahuje 7 hodnot, přičemž prvních 2 položek každého objektu tuple obsahující informace popisující jeden výsledný sloupec následujícím způsobem:

- name: Název sloupce.
- type_code: Řetězec představující typ sloupce. Například celočíselný sloupec bude mít typový kód int.

Zbývajících 5 položek každého 7 položek tuple objektu nejsou implementovány a jejich hodnoty nejsou definovány. Obvykle se vrátí jako 4.
Hodnoty None následované jednou hodnotou True.

Přístup jen pro čtení.

Vybrané Cursor metody zahrnují následující:

Metody
`cancel` Přeruší spuštění jakéhokoli databázového dotazu nebo příkazu, který kurzor spustil. Chcete-li uvolnit přidružené prostředky na serveru, zavolejte tlačítko `close` metoda po volání `cancel` metody. Žádné parametry. Žádná návratová hodnota.
`close` Zavře kurzor a uvolní přidružené prostředky na serveru. Zavření již uzavřeného kurzoru může vyvolat chybu. Žádné parametry. Žádná návratová hodnota.
`execute` Připraví a potom spustí databázový dotaz nebo příkaz. Žádná návratová hodnota. Parametry: `operation` Typ: `str` Dotaz nebo příkaz k přípravě a následnému spuštění Tento parametr je povinný. Příklad bez parametru `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Příklad s parametrem `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Typ: slovník Posloupnost parametrů, které se mají použít s parametrem `operation`. Tento parametr je volitelný. Výchozí hodnota je `None`.
`executemany` Připraví a potom spustí databázový dotaz nebo příkaz pomocí všech sekvencí parametrů v argumentu `seq_of_parameters` . Zachová se pouze konečná sada výsledků. Žádná návratová hodnota. Parametry: `operation` Typ: `str` Dotaz nebo příkaz k přípravě a následnému spuštění Tento parametr je povinný. `seq_of_parameters` Typ: `listdict` Posloupnost sad mnoha hodnot parametrů, které mají být použity s `operation` parametr. Tento parametr je povinný.
`catalogs` Spusťte dotaz metadat o katalogech. Skutečné výsledky by se pak měly načíst pomocí `fetchmany` nebo `fetchall`. Mezi důležitá pole v sadě výsledků patří: - Název pole: `TABLE_CAT`. Typ: `str`. Název katalogu. Žádné parametry. Žádná návratová hodnota. Od verze 1.0
`schemas` Spusťte dotaz metadat o schématech. Skutečné výsledky by se pak měly načíst pomocí `fetchmany` nebo `fetchall`. Mezi důležitá pole v sadě výsledků patří: - Název pole: `TABLE_SCHEM`. Typ: `str`. Název schématu. - Název pole: `TABLE_CATALOG`. Typ: `str`. Katalog, do kterého schéma patří. Žádná návratová hodnota. Od verze 1.0 Parametry: `catalog_name` Typ: `str` Název katalogu, ze kterého se načítají informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu, o kterém se mají načíst informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný.
`tables` Spusťte dotaz metadat o tabulkách a zobrazeních. Skutečné výsledky by se pak měly načíst pomocí `fetchmany` nebo `fetchall`. Mezi důležitá pole v sadě výsledků patří: - Název pole: `TABLE_CAT`. Typ: `str`. Katalog, do kterého tabulka patří. - Název pole: `TABLE_SCHEM`. Typ: `str`. Schéma, do kterého tabulka patří. - Název pole: `TABLE_NAME`. Typ: `str`. Název tabulky. - Název pole: `TABLE_TYPE`. Typ: `str`. Druh relace, například `VIEW` nebo `TABLE` (platí pro Databricks Runtime 10.4 LTS a vyšší a také pro Databricks SQL; předchozí verze Databricks Runtime vrací prázdný řetězec). Žádná návratová hodnota. Od verze 1.0 Parametry `catalog_name` Typ: `str` Název katalogu, ze kterého se načítají informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu, o kterém se mají načíst informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `table_name` Typ: `str` Název tabulky pro načtení informací. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `table_types` Typ: `List[str]` Seznam typů tabulek, které se mají shodovat, například `TABLE` nebo `VIEW`. Tento parametr je volitelný.
`columns` Spusťte dotaz metadat o sloupcích. Skutečné výsledky by se pak měly načíst pomocí `fetchmany` nebo `fetchall`. Mezi důležitá pole v sadě výsledků patří: - Název pole: `TABLE_CAT`. Typ: `str`. Katalog, do kterého sloupec patří. - Název pole: `TABLE_SCHEM`. Typ: `str`. Schéma, do kterého sloupec patří. - Název pole: `TABLE_NAME`. Typ: `str`. Název tabulky, do které sloupec patří. - Název pole: `COLUMN_NAME`. Typ: `str`. Název sloupce. Žádná návratová hodnota. Od verze 1.0 Parametry: `catalog_name` Typ: `str` Název katalogu, ze kterého se načítají informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu, o kterém se mají načíst informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `table_name` Typ: `str` Název tabulky pro načtení informací. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `column_name` Typ: `str` Název sloupce, ze kterého se mají načíst informace. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný.
`fetchall` Získá všechny (nebo všechny zbývající) řádky dotazu. Žádné parametry. Vrátí všechny (nebo všechny zbývající) řádky dotazu jako Python `list` . `Row` objekty. Vyvolá chybu `Error` , pokud předchozí volání `execute` metody nevrátilo žádná data nebo žádné `execute` volání ještě nebylo provedeno.
`fetchmany` Získá další řádky dotazu. Vrátí až ( `size` nebo `arraysize` atribut, pokud `size` není zadán) dalších řádků dotazu jako Python `list` objektů `Row` . Pokud zbývá načíst méně řádků, `size` vrátí se všechny zbývající řádky. Vyvolá chybu `Error` , pokud předchozí volání `execute` metody nevrátilo žádná data nebo žádné `execute` volání ještě nebylo provedeno. Parametry: `size` Typ: `int` Počet dalších řádků, které chcete získat. Tento parametr je volitelný. Pokud není zadán, použije se hodnota atributu `arraysize` . Příklad: `cursor.fetchmany(10)`
`fetchone` Získá další řádek datové sady. Žádné parametry. Vrátí další řádek datové sady jako jednu sekvenci jako Python. `tuple` nebo vrátí `None` , pokud už nejsou k dispozici žádná data. Vyvolá chybu `Error` , pokud předchozí volání `execute` metody nevrátilo žádná data nebo žádné `execute` volání ještě nebylo provedeno.
`fetchall_arrow` Získá všechny (nebo všechny zbývající) řádky dotazu, jako PyArrow `Table` objekt. Dotazy vracející velmi velké objemy dat by měly místo toho použít `fetchmany_arrow` ke snížení spotřeby paměti. Žádné parametry. Vrátí všechny (nebo všechny zbývající) řádky dotazu jako tabulku PyArrow. Vyvolá chybu `Error` , pokud předchozí volání `execute` metody nevrátilo žádná data nebo žádné `execute` volání ještě nebylo provedeno. Od verze 2.0
`fetchmany_arrow` Získá další řádky dotazu jako PyArrow `Table` objektu. Vrátí až do argumentu `size` (nebo `arraysize` atributu, pokud `size` není zadán) dalších řádků dotazu jako pythonový PyArrow. `Table` objekt. Vyvolá chybu `Error` , pokud předchozí volání `execute` metody nevrátilo žádná data nebo žádné `execute` volání ještě nebylo provedeno. Od verze 2.0 Parametry: `size` Typ: `int` Počet dalších řádků, které chcete získat. Tento parametr je volitelný. Pokud není zadán, použije se hodnota atributu `arraysize` . Příklad: `cursor.fetchmany_arrow(10)`

Třída `Row`

Třída řádku je datová struktura podobná řazené kolekci členů, která představuje jeden řádek výsledku. Pokud řádek obsahuje sloupec s názvem "my_column", můžete přistupovat k poli "my_column"row prostřednictvím row.my_column. Pro přístup k polím můžete použít také číselné indikáty, například row[0]. Pokud název sloupce není povolen jako název metody atributu (například začíná číslicí), můžete k poli přistupovat jako row["1_my_column"].

Od verze 1.0

Mezi vybrané Row metody patří:

| asDict

Vrátí slovníkovou reprezentaci řádku, která je indexována názvy polí. Pokud existují duplicitní názvy polí, vrátí se ve slovníku jedno z duplicitních polí (ale jenom jedno). Které duplicitní pole se vrátí, není definováno.

Žádné parametry.

Vrátí pole dict . |

Převody typů

Následující tabulka mapuje datové typy Apache Spark SQL na jejich ekvivalenty datového typu Pythonu.

Datový typ Apache Spark SQL	Datový typ Pythonu
`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`

Řešení problému

`tokenAuthWrapperInvalidAccessToken: Invalid access token` zpráva

Problém: Při spuštění kódu se zobrazí zpráva podobná Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Možná příčina: Předaná access_token hodnota není platným tokenem pat azure Databricks.

Doporučená oprava: Zkontrolujte, jestli je předaná access_token hodnota správná, a zkuste to znovu.

`gaierror(8, 'nodename nor servname provided, or not known')` zpráva

Problém: Při spuštění kódu se zobrazí zpráva podobná Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Možná příčina: Předaná server_hostname hodnota není správný název hostitele.

Doporučená oprava: Zkontrolujte, jestli je předaná server_hostname hodnota správná, a zkuste to znovu.

Další informace o vyhledání názvu hostitele serveru najdete v tématu Získání podrobností o připojení pro výpočetní prostředek Azure Databricks.

`IpAclError` zpráva

Problém: Při spuštění kódu se při pokusu o použití konektoru v poznámkovém bloku Azure Databricks zobrazí zpráva Error during request to server: IpAclValidation .

Možná příčina: Pro pracovní prostor Azure Databricks je povolený seznam povolených IP adres. U výpisu povolených IP adres nejsou ve výchozím nastavení povolená připojení z clusterů Sparku k řídicí rovině.

Doporučená oprava: Požádejte správce, aby do seznamu povolených IP adres přidal podsíť výpočetní roviny.

Další materiály

Další informace naleznete v tématu:

Úložiště Databricks SQL Connector pro Python na GitHubu
Datové typy
Předdefinované typy (pro bool, bytearrayfloat, int, astr) na webu Pythonu
datetime (for datetime.date ) datatime.datetimena webu Pythonu
decimal (for decimal.Decimal) na webu Pythonu
Předdefinované konstanty (for NoneType) na webu Pythonu

Sdílet prostřednictvím

Konektor SQL Pro Databricks pro Python

Požadavky

Začněte

Cluster

SQL Warehouse

Ověřování

Ověřování osobního přístupového tokenu Databricks

Ověřování M2M (machine-to-machine) OAuth

Ověřování tokenu Microsoft Entra ID

Ověřování uživatele OAuth na počítač (U2M)

Příklady

Zadávání dotazů na data

Vložení dat

Metadata dotazů

Správa kurzorů a připojení

Správa souborů ve svazcích katalogu Unity

Konfigurace protokolování

Testování

Reference rozhraní API

Balíček

Modul

Třídy

Třída `Connection`

Třída `Cursor`

Třída `Row`

Převody typů

Řešení problému

`tokenAuthWrapperInvalidAccessToken: Invalid access token` zpráva

`gaierror(8, 'nodename nor servname provided, or not known')` zpráva

`IpAclError` zpráva

Další materiály

Váš názor

Další materiály

Sdílet prostřednictvím

Konektor SQL Pro Databricks pro Python

Požadavky

Začněte

Cluster

SQL Warehouse

Ověřování

Ověřování osobního přístupového tokenu Databricks

Ověřování M2M (machine-to-machine) OAuth

Ověřování tokenu Microsoft Entra ID

Ověřování uživatele OAuth na počítač (U2M)

Příklady

Zadávání dotazů na data

Vložení dat

Metadata dotazů

Správa kurzorů a připojení

Správa souborů ve svazcích katalogu Unity

Konfigurace protokolování

Testování

Reference rozhraní API

Balíček

Modul

Třídy

Třída Connection

Třída Cursor

Třída Row

Převody typů

Řešení problému

tokenAuthWrapperInvalidAccessToken: Invalid access token zpráva

gaierror(8, 'nodename nor servname provided, or not known') zpráva

IpAclError zpráva

Další materiály

Váš názor

Další materiály

Třída `Connection`

Třída `Cursor`

Třída `Row`

`tokenAuthWrapperInvalidAccessToken: Invalid access token` zpráva

`gaierror(8, 'nodename nor servname provided, or not known')` zpráva

`IpAclError` zpráva