Konektor SQL Pro Databricks pro Python

Článek
06/28/2024

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 obsahuje také dialekt SQLAlchemy pro Azure Databricks. 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áme

Nainstalujte konektor SQL Databricks pro knihovnu Pythonu na vývojovém počítači spuštěním pip install databricks-sql-connector nebo python -m pip install databricks-sql-connector.
Shromážděte následující informace pro cluster nebo SQL Warehouse, který chcete použít:

Cluster
- Název hostitele serveru clusteru. Můžete to získat z hodnoty Název hostitele serveru na kartě Upřesnit možnosti > JDBC/ODBC pro váš cluster.
- Cesta HTTP clusteru. Můžete to získat z hodnoty CESTA HTTP na kartě Upřesnit možnosti > JDBC/ODBC pro váš cluster.
SQL Warehouse
- Název hostitele serveru služby SQL Warehouse. Můžete to získat z hodnoty Název hostitele serveru na kartě Podrobnosti připojení pro váš SQL Warehouse.
- Cesta HTTP služby SQL Warehouse. Můžete to získat z hodnoty CESTA HTTP na kartě Podrobnosti 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 (dříve Azure Active Directory)
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 tokenů pat Azure Databricks, musíte nejprve vytvořit token pat azure Databricks, a to následujícím způsobem:

V pracovním prostoru Azure Databricks klikněte na své uživatelské jméno Azure Databricks v horním panelu a pak v rozevíracím seznamu vyberte Nastavení .
Klikněte na Vývojář.
Vedle přístupových tokenů klikněte na Spravovat.
Klikněte na Vygenerovat nový token.
(Volitelné) Zadejte komentář, který vám pomůže identifikovat tento token v budoucnu a změnit výchozí životnost tokenu na 90 dnů. Pokud chcete vytvořit token bez životnosti (nedoporučuje se), nechte pole Životnost (dny) prázdné (prázdné).
Klikněte na Vygenerovat.
Zkopírujte zobrazený token do zabezpečeného umístění a klikněte na tlačítko Hotovo.

Poznámka:

Nezapomeňte zkopírovaný token uložit do zabezpečeného umístění. Nesdílejte svůj zkopírovaný token s ostatními. Pokud ztratíte zkopírovaný token, nemůžete tento úplně stejný token znovu vygenerovat. Místo toho musíte tento postup zopakovat, abyste vytvořili nový token. Pokud ztratíte zkopírovaný token nebo se domníváte, že došlo k ohrožení zabezpečení tokenu, databricks důrazně doporučuje tento token okamžitě odstranit z pracovního prostoru kliknutím na ikonu koše (Odvolat) vedle tokenu na stránce Přístupové tokeny .

Pokud v pracovním prostoru nemůžete vytvářet nebo používat tokeny, může to být proto, že správce pracovního prostoru zakázal tokeny nebo vám neudělil oprávnění k vytváření nebo používání tokenů. Obraťte se na správce pracovního prostoru nebo následující:

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_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
DATABRICKS_TOKEN, nastavte na 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 Použití instančního objektu k ověření pomocí Azure Databricks. 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_HOSTNAMEna hodnotu Název hostitele serveru pro váš cluster nebo SQL Warehouse.
DATABRICKS_HTTP_PATH, nastavte hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
DATABRICKS_CLIENT_ID, nastavte na hodnotu UUID nebo ID aplikace instančního objektu.
DATABRICKS_CLIENT_SECRET, nastavte na hodnotu Secret pro tajný klíč OAuth instančního objektu.

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 (dříve Azure Active Directory)

Pokud chcete používat konektor SQL Databricks pro Python s ověřováním tokenu Microsoft Entra ID (dříve Azure Active Directory), musíte konektor SQL Databricks pro Python zadat pomocí tokenu 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ů Microsoft Entra ID (dříve Azure Active Directory) pro uživatele pomocí Azure CLI.
Instanční objekt Microsoft Entra ID najdete v tématu 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 hodnotu název hostitele serveru pro váš cluster nebo SQL Warehouse.
Nastavte DATABRICKS_HTTP_PATH hodnotu cesty HTTP pro váš cluster nebo SQL Warehouse.
Nastavte DATABRICKS_TOKEN token 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 hodnotu název hostitele serveru pro váš cluster nebo SQL Warehouse.
Nastavte DATABRICKS_HTTP_PATH 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í.

Tento příklad kódu načte server_hostnamehttp_pathhodnoty jejich a access_token připojovací proměnné 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žení dat
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 trips tabulky 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 svazků katalogu Unity, 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ím get_connection_personal_access_token funkci, která používá osobní přístupový token Azure Databricks k vrácení připojení k pracovnímu prostoru Azure Databricks, a select_nyctaxi_trips funkci, která pomocí připojení získá zadaný počet řádků dat z trips tabulky ve samples schématu 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

Vzhledem k tomu, že select_nyctaxi_trips funkce obsahuje SELECT příkaz, a proto nemění stav trips tabulky, není v tomto příkladu napodobování zcela vyžadováno. Napodobování ale umožňuje rychle spouštět testy bez čekání na skutečné připojení k pracovnímu prostoru. Také napodobení umožňuje spustit simulované testy vícekrát pro funkce, které mohou změnit stav tabulky, 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 Connection objekt, 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 `SET -v` SQL 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ší páry (klíč, hodnota) nastavené v hlavičce HTTP na každém požadavku RPC, který klient provede. Typické použití 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 `use_cloud_fetch` je nastavená hodnota `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 cursor Connection 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 `tuple` objektu obsahuje 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 objektu 7 položek `tuple` není implementováno a jejich hodnoty nejsou definovány. Obvykle se vrátí jako 4. `None` hodnoty následované jednou `True` hodnotou. 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 tuple objektu obsahuje 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 objektu 7 položek tuple není implementováno a jejich hodnoty nejsou definovány. Obvykle se vrátí jako 4.
None hodnoty následované jednou True hodnotou.

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 mnoha sad hodnot parametrů, které se mají použít 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 pro načtení informací. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu pro načtení informací. 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 pro načtení informací. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu pro načtení informací. 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 pro načtení informací. Znak `%` se interpretuje jako zástupný znak. Tento parametr je volitelný. `schema_name` Typ: `str` Název schématu pro načtení informací. 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 pro načtení informací. 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 získat přístup k "my_column" poli row via 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íť roviny výpočetních prostředků.

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, floatbytearray, 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áme

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 (dříve Azure Active Directory)

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

Váš názor

Další materiály

Sdílet prostřednictvím

Konektor SQL Pro Databricks pro Python

Požadavky

Začínáme

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 (dříve Azure Active Directory)

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

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