Sdílet prostřednictvím

Konektor SQL pro Databricks pro Python

Konektor SQL Databricks pro Python je knihovna Pythonu, která umožňuje používat kód Pythonu ke spouštění příkazů SQL na výpočetních prostředcích Azure Databricks pro všechny účely 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.

Důležité

Konektor SQL Databricks pro Python verze 3.0.0 a vyšší podporuje nativní parametrizované spouštění dotazů, které brání injektáži SQL a může zlepšit výkon dotazů. Předchozí verze používaly vložené parametrizované spouštění, což není bezpečné před injektáží SQL a má další nevýhody. Další informace naleznete v tématu Použití nativních parametrů.

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

Požadavky

  • Vývojový počítač s Pythonem 3.8 a novějším
  • 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í výpočetní prostředky pro všechny účely nebo SQL Warehouse.

Začínáme

  1. Nainstalujte konektor SQL Databricks pro Python. PyArrow je volitelná závislost konektoru SQL Databricks pro Python a není ve výchozím nastavení nainstalovaná ve verzi 4.0.0 a vyšší konektoru. Pokud není nainstalovaný 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]

  2. Shromážděte následující informace o univerzálním výpočetním prostředku nebo SQL úložišti, které hodláte použít.

    Univerzální výpočet

    • Název hostitele serveru univerzálního výpočetního systému. Můžete to najít z hodnoty Název hostitele serveru na kartě Upřesnit možnosti > JDBC/ODBC pro univerzální výpočty.
    • Cesta HTTP výpočetních prostředků pro všechny účely. Můžete to získat z hodnoty HTTP Path na kartě Pokročilé možnosti > JDBC/ODBC pro obecné výpočetní úlohy.

    Poznámka:

    Konektor SQL nepodporuje připojení k výpočtům úloh.

    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ě.
    • HTTP cesta databázového úložiště SQL. Můžete to získat z hodnoty HTTP cesta 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:

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 pokynů v tématu Vytvoření osobních přístupových tokenů 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_HOSTNAMEnastavte hodnotu Název hostitele serveru pro váš všestranný výpočetní prostředek nebo SQL sklad.
  • DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP cesty pro univerzální výpočetní zdroje nebo SQL sklad.
  • Nastavte DATABRICKS_TOKEN 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 (stroj-stroj) OAuth

Konektor Databricks SQL pro Python ve verzích 2.7.0 a vyšších podporuje machine-to-machine (M2M) ověřování prostřednictvím OAuth. 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:

  1. 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 Autorizace přístupu instančního objektu k Azure Databricks pomocí OAuth. Poznamenejte si hodnotu UUID nebo ID aplikace instančního objektu a hodnotu Secret pro tajný klíč OAuth instančního objektu.

  2. Poskytněte servisnímu hlavnímu objektu přístup k vašim univerzálním výpočetním prostředkům nebo skladišti.

    Pokud chcete servisnímu účtu udělit přístup k všeobecně použitelnému výpočetnímu prostředí nebo skladu, viz Oprávnění k výpočetním prostředkům nebo Správa 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 nastavte hodnotu Název hostitele serveru pro výpočetní prostředky pro všechny účely nebo SQL Warehouse.
  • DATABRICKS_HTTP_PATH, nastavte hodnotu HTTP cesty pro univerzální výpočetní zdroje nebo SQL sklad.
  • DATABRICKS_CLIENT_ID, nastavte na hodnotu UUID nebo ID aplikace instančního objektu.
  • DATABRICKS_CLIENT_SECRET, nastavte hodnotu na Secret pro heslo OAuth instančního objektu služby.

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:

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 serverového hostitele pro univerzální výpočetní prostředky nebo SQL Warehouse.
  • Nastavte DATABRICKS_HTTP_PATH na hodnotu cesty HTTP pro univerzální výpočetní zdroje 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:
# ...

Autentizace uživatele OAuth na stroj (U2M)

Konektor Databricks SQL pro Python verze 2.7.0 a vyšší podporuje autentizaci OAuth uživatele k zařízení (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á přihlášení uživatele v reálném čase a jeho souhlas k ověření cílového uživatelského účtu Azure Databricks. 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 serverového hostitele pro univerzální výpočetní prostředky nebo SQL Warehouse.
  • Nastavte DATABRICKS_HTTP_PATH na hodnotu cesty HTTP pro univerzální výpočetní zdroje 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í, spravovat soubory v katalogu Unity 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 použít jiný typ ověřování, 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 serveru dle požadavků.
  • DATABRICKS_HTTP_PATH, který představuje hodnotu HTTP path z požadavků.
  • DATABRICKS_TOKEN, který představuje váš přístupový token z požadavků.

Nastavení User-Agent

Následující příklad kódu ukazuje, jak nastavit User-Agent aplikace product_name pro sledování využití.

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)

Dotaz na data

Následující příklad kódu ukazuje, jak zavolat konektor Databricks SQL pro Python ke spuštění základního příkazu SQL na univerzálních výpočetních prostředcích nebo ve skladu SQL. 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)

Značky dotazů

Důležité

Tato funkce je ve verzi Private Preview. Pokud chcete požádat o přístup, obraťte se na svůj tým účtů.

Následující příklad ukazuje, jak připojit značky klíč-hodnota k dotazům SQL pro účely sledování a analýzy. Značky dotazů se zobrazí v system.query.history 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"),
    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)

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

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

    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 ve všech účelových výpočetních prostředcích 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_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'"
    )

Konfigurujte protokolování

Konektor SQL Databricks používá standardní modul protokolování Pythonu. Následující příklad nakonfiguruje úroveň protokolování a vygeneruje protokol ladění:

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("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á funkce get_connection_personal_access_token a select_nyctaxi_trips:

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

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

V tomto příkladu, protože funkce select_nyctaxi_trips obsahuje příkaz SELECT a tím pádem nemění stav tabulky trips, není mockování zcela povinné. Ale napodobování umožňuje rychle spouštět testy bez nutnosti čekání na reálné 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.

Reference rozhraní API

Tato část obsahuje referenční informace k rozhraní API pro databricks-sql-connector balíček. Viz databricks-sql-connector v indexu balíčků Pythonu (PyPI).

Modul

Modul databricks.sqldatabricks-sql-connector balíčku obsahuje metodu inicializace připojení k SQL Warehouse.

metoda connect

Inicializuje připojení k SQL Warehouse. Vrátí objekt Connection.

Parameter Typ Description
server_hostname str Povinné. Název hostitele serveru pro všestranné výpočetní prostředky nebo SQL Warehouse, například adb-1234567890123456.7.azuredatabricks.net.
Pokud chcete získat název hostitele serveru, přečtěte si pokyny v části Začínáme.
http_path str Povinné. Cesta HTTP víceučelového výpočetního prostředku nebo SQL skladiště, například sql/protocolv1/o/1234567890123456/1234-567890-test123 slouží pro víceučelové výpočetní prostředky nebo /sql/1.0/warehouses/a1b234c567d8e9fa pro SQL skladiště.
Pokud chcete získat cestu HTTP, přečtěte si pokyny v části Začínáme.
access_token, auth_type, credentials_provider, , passwordusername str Informace o nastavení ověřování Azure Databricks Podrobnosti najdete v tématu Ověřování.
session_configuration 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 je None.
Příklad: {"spark.sql.variable.substitute": True}
http_headers List[Tuple[str, str]]] Optional. 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 je None.
catalog str Optional. 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).
schema str Optional. 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).
Od verze 2.0
use_cloud_fetch bool Optional. Určuje, jestli se mají odesílat požadavky na načtení přímo do cloudového úložiště objektů za účelem stahování bloků dat. Výchozí hodnota je True. Nastavte na False, abyste odesílali požadavky na načítání 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
user_agent_entry str Optional. Položka User-Agent, kterou je třeba zahrnout do hlavičky požadavku HTTP pro sledování využití. Výchozí hodnota je PyDatabricksSqlConnector.

Connection třída

Představuje připojení k výpočetním zdrojům nebo k úložišti SQL.

Metody

Třída Connection poskytuje následující metody.

Metoda Description
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ý objekt Kurzor , který umožňuje procházení záznamů v databázi.
Žádné parametry.

Cursor třída

Představuje mechanismus pro procházení datových záznamů.

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

Atributy

Mezi vybrané Cursor atributy patří:

Vlastnost Description
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 None hodnoty následované jednou True hodnotou. Přístup jen pro čtení.

Metody

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

Metoda Description
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 metodu close po volání metody cancel.
Žá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.
Parametry:
  • operation:Požadovaný. Dotaz nebo příkaz k přípravě a následnému spuštění Typ: str Příklad bez parametru parameters : cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2') Příklad s parametrem parameters (pomocí nativních pozičních parametrů): cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])
  • parameters: Volitelné. Posloupnost parametrů, které se mají použít s parametrem operation. Výchozí hodnota je None. Typ: dictionary

Žádná návratová hodnota.
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ů.
Parametry:
  • operation:Požadovaný. Dotaz nebo příkaz k přípravě a následnému spuštění Typ: str
  • seq_of_parameters:Požadovaný. Řada mnoha sad hodnot parametrů, které se mají použít s parametrem operation. Typ: listdict

Žádná návratová hodnota.
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. Název katalogu. Typ: str

Žá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. Název schématu. Typ: str
  • Název pole: TABLE_CATALOG. Katalog, do kterého schéma patří. Typ: str

Parametry:
  • catalog_name: Volitelné. Název katalogu, ze kterého se načítají informace. Znak % se interpretuje jako zástupný znak. Typ: str
  • schema_name: Volitelné. Název schématu, o kterém se mají načíst informace. Znak % se interpretuje jako zástupný znak. Typ: str

Žádná návratová hodnota.
Od verze 1.0
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. Katalog, do kterého tabulka patří. Typ: str
  • Název pole: TABLE_SCHEM. Schéma, do kterého tabulka patří. Typ: str
  • Název pole: TABLE_NAME. Název tabulky. Typ: str
  • Název pole: TABLE_TYPE. 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). Typ: str

Parametry:
  • catalog_name: Volitelné. Název katalogu, ze kterého se načítají informace. Znak % se interpretuje jako zástupný znak. Typ: str
  • schema_name: Volitelné. Název schématu, o kterém se mají načíst informace. Znak % se interpretuje jako zástupný znak. Typ: str
  • table_name: Volitelné. Název tabulky pro načtení informací. Znak % se interpretuje jako zástupný znak. Typ: str
  • table_types: Volitelné. Seznam typů tabulek, které se mají shodovat, například TABLE nebo VIEW. Typ: List[str]

Žádná návratová hodnota.
Od verze 1.0
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. Katalog, do kterého sloupec patří. Typ: str
  • Název pole: TABLE_SCHEM. Schéma, do kterého sloupec patří. Typ: str
  • Název pole: TABLE_NAME. Název tabulky, do které sloupec patří. Typ: str
  • Název pole: COLUMN_NAME. Název sloupce. Typ: str

Parametry:
  • catalog_name: Volitelné. Název katalogu, ze kterého se načítají informace. Znak % se interpretuje jako zástupný znak. Typ: str
  • schema_name: Volitelné. Název schématu, o kterém se mají načíst informace. Znak % se interpretuje jako zástupný znak. Typ: str
  • table_name: Volitelné. Název tabulky pro načtení informací. Znak % se interpretuje jako zástupný znak. Typ: str
  • column_name: Volitelné. Název sloupce, ze kterého se mají načíst informace. Znak % se interpretuje jako zástupný znak. Typ: str

Žádná návratová hodnota.
Od verze 1.0
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 objektů Row .
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.
Parametry:
  • size: Volitelné. Počet dalších řádků, které chcete získat. Pokud není zadán, použije se hodnota atributu arraysize . Typ: int. Příklad: cursor.fetchmany(10)

Vrátí až size (nebo atribut arraysize, pokud není zadán size) dalších řádků dotazu jako objekty list v Pythonu Row.
Pokud zbývá načíst méně než size řádků, 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.
fetchone Získá další řádek datové sady.
Žádné parametry.
Vrátí další řádek datové sady jako jednu sekvenci jako objekt Pythonu tuple nebo vrátí None , pokud už nejsou k dispozici žádná další 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 objekt PyArrow Table.
Parametry:
  • size: Volitelné. Počet dalších řádků, které chcete získat. Pokud není zadán, použije se hodnota atributu arraysize . Typ: int. Příklad: cursor.fetchmany_arrow(10)

Vrátí až k argumentu size (nebo k atributu arraysize, pokud size není zadán) následující řádky dotazu jako objekt PyArrow v Pythonu Table.
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

Row třída

Třída řádku je datová struktura podobná řazené kolekci členů, která představuje jednotlivý řádek výsledků ve výsledku dotazu SQL. 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ří:

Metody

Metoda Description
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.

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á hodnota není platným osobním přístupovým tokenem 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:

  • Last updated on