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

    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:

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:

  1. 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í .
  2. Klikněte na Vývojář.
  3. Vedle přístupových tokenů klikněte na Spravovat.
  4. Klikněte na Vygenerovat nový token.
  5. (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é).
  6. Klikněte na Vygenerovat.
  7. 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ů. Projděte si správce pracovního prostoru nebo následující témata:

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:

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

  2. 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

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 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ů.

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.

Reference rozhraní API

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 Noneje .

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 Noneje .

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