Łącznik SQL usługi Databricks dla języka Python

Artykuł
03/11/2025

Łącznik SQL usługi Databricks dla języka Python to biblioteka języka Python, która umożliwia uruchamianie poleceń SQL w klastrach usługi Azure Databricks i magazynach SQL usługi Databricks przy użyciu kodu języka Python. Łącznik SQL usługi Databricks dla języka Python jest łatwiejszy do skonfigurowania i użycia niż podobne biblioteki języka Python, takie jak pyodbc. Ta biblioteka jest zgodna ze specyfikacją interfejsu API bazy danych języka Python w wersji 2.0 PEP 249.

Uwaga

Łącznik SQL usługi Databricks dla języka Python obsługuje również dialekt SQLAlchemy dla usługi Azure Databricks, ale należy go zainstalować, aby korzystać z tych funkcji. Zobacz Use SQLAlchemy with Azure Databricks (Używanie usługi SQLAlchemy z usługą Azure Databricks).

Wymagania

Maszyna deweloperna z uruchomionym językiem Python >=3.8 i <=3.11.
Usługa Databricks zaleca używanie środowisk wirtualnych języka Python, takich jak te udostępniane przez venv dołączone do języka Python. Środowiska wirtualne pomagają zapewnić, że używasz poprawnych wersji języka Python i łącznika SQL usługi Databricks dla języka Python. Konfigurowanie i używanie środowisk wirtualnych wykracza poza zakres tego artykułu. Aby uzyskać więcej informacji, zobacz Tworzenie środowisk wirtualnych.
Istniejący klaster lub magazyn SQL.

Rozpocznij

Zainstaluj łącznik SQL usługi Databricks dla języka Python. PyArrow jest opcjonalną zależnością łącznika SQL usługi Databricks dla języka Python i nie jest instalowana domyślnie. Jeśli nie zainstalujesz rozwiązania PyArrow, funkcje, takie jak CloudFetch i inne funkcje narzędzia Apache Arrow, nie będą dostępne, co może mieć wpływ na wydajność dużych ilości danych.
- Aby zainstalować łącznik lean, użyj pip install databricks-sql-connector.
- Aby zainstalować kompletny łącznik, w tym PyArrow, użyj pip install databricks-sql-connector[pyarrow].
Zbierz następujące informacje dotyczące klastra lub magazynu SQL, którego chcesz użyć:

Klaster
- Nazwa hosta serwera klastra. Możesz to uzyskać z wartości Nazwa hosta serwera na zakładce Opcje zaawansowane > JDBC/ODBC dla twojego klastra.
- Ścieżka HTTP klastra. Możesz to uzyskać z wartości HTTP Path na karcie Opcje zaawansowane > JDBC/ODBC dla klastra.
SQL Warehouse
- Nazwa hosta serwera usługi SQL Warehouse. Możesz uzyskać to z wartości Nazwa hosta serwera w zakładce Szczegóły połączenia dla SQL Warehouse.
- Ścieżka HTTP magazynu SQL. Możesz to uzyskać z wartości ścieżki HTTP na karcie Szczegóły połączenia dla usługi SQL Warehouse.

Uwierzytelnianie

Łącznik SQL usługi Databricks dla języka Python obsługuje następujące typy uwierzytelniania usługi Azure Databricks:

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks
Uwierzytelnianie tokenu Microsoft Entra ID
Uwierzytelnianie OAuth między maszynami (M2M)
Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Łącznik SQL usługi Databricks dla języka Python nie obsługuje jeszcze następujących typów uwierzytelniania usługi Azure Databricks:

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Aby użyć łącznika SQL usługi Databricks dla języka Python z uwierzytelnianiem osobistego tokenu dostępu usługi Azure Databricks, musisz najpierw utworzyć osobisty token dostępu usługi Azure Databricks. W tym celu wykonaj kroki opisane w artykule Osobiste tokeny dostępu usługi Azure Databricks dla użytkowników obszaru roboczego.

Aby uwierzytelnić łącznik SQL usługi Databricks dla języka Python, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

DATABRICKS_SERVER_HOSTNAMEustaw wartość na nazwę hosta serwera dla twojego klastra lub magazynu SQL.
DATABRICKS_HTTP_PATH, ustaw wartość ścieżki HTTP dla swojego klastra lub magazynu SQL.
Ustaw element DATABRICKS_TOKEN na osobisty token dostępu usługi Azure Databricks.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie maszyny do maszyny OAuth (M2M)

Łącznik SQL usługi Databricks dla języka Python w wersji 2.7.0 lub nowszej obsługuje uwierzytelnianie między maszynami OAuth (M2M). Należy również zainstalować zestaw SDK usługi Databricks dla języka Python w wersji 0.18.0 lub nowszej (na przykład uruchamiając polecenie pip install databricks-sdk lub python -m pip install databricks-sdk).

Aby użyć łącznika SQL usługi Databricks dla języka Python z uwierzytelnianiem OAuth M2M, należy wykonać następujące czynności:

Utwórz pryncypał usługi Azure Databricks w obszarze roboczym Azure Databricks i utwórz sekret OAuth dla tego pryncypała usługi.

Aby utworzyć jednostkę usługi i jej tajny klucz OAuth, zobacz Autoryzuj nienadzorowany dostęp do zasobów Azure Databricks przy użyciu jednostki usługi z OAuth. Zanotuj wartość UUID lub Identyfikator aplikacji jednostki usługi oraz wartość Tajemnicy dla tajemnicy OAuth tej jednostki usługi.
Nadaj jednostce usługi dostęp do klastra lub magazynu.

Aby udzielić głównej jednostce usługi dostępu do klastra lub magazynu, zobacz Uprawnienia obliczeniowe lub Zarządzanie usługą SQL Warehouse.

Aby uwierzytelnić łącznik SQL usługi Databricks dla języka Python, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

DATABRICKS_SERVER_HOSTNAME ustawione na wartość nazwy hosta serwera dla klastra lub magazynu SQL."
DATABRICKS_HTTP_PATH, ustaw wartość jako ścieżka HTTP dla klastra lub magazynu SQL.
DATABRICKS_CLIENT_IDustaw na UUID jednostki usługi lub na wartość identyfikatora aplikacji .
DATABRICKS_CLIENT_SECRET, ustaw na wartość Secret dla sekretu OAuth podmiotu usługi.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie tokenu Microsoft Entra ID

Aby użyć łącznika SQL usługi Databricks dla języka Python z uwierzytelnianiem tokenu Microsoft Entra ID, należy podać łącznik SQL usługi Databricks dla języka Python przy użyciu tokenu identyfikatora Entra firmy Microsoft. Aby utworzyć token dostępu microsoft Entra ID, wykonaj następujące czynności:

W przypadku użytkownika usługi Azure Databricks możesz użyć Azure CLI. Zobacz Uzyskiwanie tokenów Microsoft Entra ID dla użytkowników za pomocą Azure CLI.
Aby uzyskać głównego użytkownika usługi Microsoft Entra ID, zobacz Uzyskiwanie tokenu dostępu Microsoft Entra ID za pomocą Azure CLI. Aby utworzyć główną jednostkę usługi zarządzaną w identyfikatorze Microsoft Entra ID, zobacz Zarządzanie głównymi jednostkami usługi.

Tokeny identyfikatora Entra firmy Microsoft mają domyślny okres istnienia około 1 godziny. Aby utworzyć nowy token identyfikatora Entra firmy Microsoft, powtórz ten proces.

Aby uwierzytelnić łącznik SQL usługi Databricks dla języka Python, użyj następującego fragmentu kodu. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

Ustaw DATABRICKS_SERVER_HOSTNAME na nazwę hosta serwera dla klastra lub magazynu SQL.
Ustaw DATABRICKS_HTTP_PATH na wartość ścieżki HTTP dla twojego klastra lub magazynu SQL.
Ustaw wartość DATABRICKS_TOKEN na token Microsoft Entra ID.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Łącznik SQL usługi Databricks dla języka Python w wersji 2.7.0 lub nowszej obsługuje uwierzytelnianie OAuth od użytkownika do maszyny (U2M). Należy również zainstalować zestaw SDK usługi Databricks dla języka Python w wersji 0.19.0 lub nowszej (na przykład uruchamiając polecenie pip install databricks-sdk lub python -m pip install databricks-sdk).

Aby uwierzytelnić łącznik SQL usługi Databricks dla języka Python przy użyciu uwierzytelniania OAuth U2M, użyj następującego fragmentu kodu. Uwierzytelnianie OAuth U2M wykorzystuje logowanie użytkownika w czasie rzeczywistym i wyrażenie zgody do uwierzytelniania docelowego konta użytkownika Azure Databricks. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

Ustaw DATABRICKS_SERVER_HOSTNAME na Nazwę hosta serwera swojego klastra lub magazynu SQL.
Ustaw DATABRICKS_HTTP_PATH na wartość Ścieżki HTTP dla klastra lub magazynu SQL.

Aby ustawić zmienne środowiskowe, zapoznaj się z dokumentacją systemu operacyjnego.

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

Przykłady

W poniższych przykładach kodu pokazano, jak używać łącznika SQL Usługi Databricks dla języka Python do wykonywania zapytań o dane, wykonywania zapytań o metadane, zarządzania kursorami i połączeniami oraz konfigurowania rejestrowania.

Uwaga

W poniższych przykładach kodu pokazano, jak używać osobistego tokenu dostępu usługi Azure Databricks do uwierzytelniania. Aby zamiast tego użyć innych dostępnych typów uwierzytelniania usługi Azure Databricks, zobacz Uwierzytelnianie.

Ten przykład kodu pobiera wartości zmiennych połączenia server_hostname, http_pathi access_token z następujących zmiennych środowiskowych:

DATABRICKS_SERVER_HOSTNAME, który reprezentuje wartość nazwa hosta serwera z wymagań.
DATABRICKS_HTTP_PATH, który reprezentuje wartość ścieżki HTTP z wymagań.
DATABRICKS_TOKEN, który reprezentuje twój token dostępu zgodnie z wymaganiami.

Możesz użyć innych metod pobierania tych wartości zmiennych połączenia. Używanie zmiennych środowiskowych jest tylko jednym z wielu podejść.

ustaw agenta użytkownika
Wykonywanie zapytań o dane
Wstaw dane
Metadane zapytania
Zarządzanie kursorami i połączeniami
Zarządzanie plikami w zasobach Unity Catalog
Konfigurowanie rejestrowania

Zestaw User-Agent

W poniższym przykładzie kodu pokazano, jak ustawić aplikację User-Agent do śledzenia użycia product_name.

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)

Pobieranie danych

W poniższym przykładzie kodu pokazano, jak wywołać łącznik SQL usługi Databricks dla języka Python w celu uruchomienia podstawowego polecenia SQL w klastrze lub usłudze SQL Warehouse. To polecenie zwraca dwa pierwsze wiersze z tabeli trips w schemacie 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)

Wstawianie danych

W poniższym przykładzie pokazano, jak wstawić małe ilości danych (tysiące wierszy):

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)

W przypadku dużych ilości danych należy najpierw przekazać dane do magazynu w chmurze, a następnie wykonać polecenie COPY INTO.

Metadane zapytania

Istnieją dedykowane metody pobierania metadanych. Poniższy przykład pobiera metadane dotyczące kolumn w przykładowej tabeli:

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

Zarządzanie kursorami i połączeniami

Najlepszym rozwiązaniem jest zamknięcie wszystkich połączeń i kursorów, które nie są już używane. Spowoduje to zwolnienie zasobów w klastrach usługi Azure Databricks i magazynach SQL Usługi Databricks.

Do zarządzania zasobami można użyć menedżera kontekstu ( with składni używanej w poprzednich przykładach) lub jawnego wywołania metody 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()

Zarządzanie plikami w woluminach Katalogu Unity

Łącznik SQL usługi Databricks umożliwia zapisywanie plików lokalnych w Unity Catalog woluminów, pobieranie plików z woluminów i usuwanie plików z woluminów, jak pokazano w poniższym przykładzie:

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

Konfigurowanie rejestrowania

Łącznik SQL usługi Databricks używa standardowego modułu rejestrowania języka Python. Możesz skonfigurować poziom rejestrowania podobny do następującego:

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

Testowanie

Aby przetestować kod, użyj platform testowych języka Python, takich jak pytest. Aby przetestować kod w symulowanych warunkach bez wywoływania punktów końcowych interfejsu API REST usługi Azure Databricks lub zmieniania stanu kont lub obszarów roboczych usługi Azure Databricks, możesz użyć bibliotek pozorowania języka Python, takich jak unittest.mock.

Na przykład, biorąc pod uwagę następujący plik o nazwie helpers.py zawierający funkcję get_connection_personal_access_token, która używa osobistego tokenu dostępu usługi Azure Databricks w celu zwrócenia połączenia z obszarem roboczym usługi Azure Databricks, oraz funkcji select_nyctaxi_trips, która używa połączenia w celu uzyskania określonej liczby wierszy danych z tabeli trips w schemacie samples katalogu nyctaxi:

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
  result: List[Row] = cursor.fetchall()
  return result

I biorąc pod uwagę następujący plik o nazwie main.py, który wywołuje funkcje get_connection_personal_access_token i 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)

Poniższy plik o nazwie test_helpers.py testuje, czy select_nyctaxi_trips funkcja zwraca oczekiwaną odpowiedź. Zamiast tworzyć rzeczywiste połączenie z docelowym obszarem roboczym, ten test symuluje obiekt Connection. Test wyśmiewa również niektóre dane zgodne ze schematem i wartościami, które znajdują się w rzeczywistych danych. Test zwraca symulowane dane za pośrednictwem symulowanego połączenia, a następnie sprawdza, czy jedna z wartości wiersza danych pasuje do oczekiwanej wartości.

# 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

Ponieważ funkcja select_nyctaxi_trips zawiera instrukcję SELECT i dlatego nie zmienia stanu tabeli trips, pozorowanie nie jest absolutnie wymagane w tym przykładzie. Jednak pozorowanie umożliwia szybkie uruchamianie testów bez oczekiwania na rzeczywiste połączenie z obszarem roboczym. Ponadto wyśmiewanie umożliwia wielokrotne uruchamianie symulowanych testów dla funkcji, które mogą zmienić stan tabeli, takie jak INSERT INTO, UPDATEi DELETE FROM.

Dokumentacja API

Pakiet
Moduł
Klasy
Klasa Connection
Klasa Cursor
Klasa Row
Konwersje typów

Pakiet

databricks-sql-connector

Użycie: pip install databricks-sql-connector

Zobacz również łącznik databricks-sql-connector w indeksie pakietów języka Python (PyPI).

Moduł

databricks.sql

Użycie: from databricks import sql

Klasy

Wybrane klasy obejmują następujące elementy:

Klasy
`Connection` Sesja zasobu obliczeniowego usługi Azure Databricks.
`Cursor` Mechanizm przechodzenia przez rekordy danych.
`Row` Wiersz danych w wyniku zapytania SQL.

Klasa `Connection`

Aby utworzyć obiekt Connection, wywołaj metodę databricks.sql.connect przy użyciu następujących parametrów:

Parametry
`server_hostname` Typ: `str` Nazwa hosta serwera dla klastra lub usługi SQL Warehouse. Aby uzyskać nazwę hosta serwera, zobacz instrukcje opisane wcześniej w tym artykule. Ten parametr jest wymagany. Przykład: `adb-1234567890123456.7.azuredatabricks.net`
`http_path` Typ: `str` Ścieżka HTTP klastra lub usługi SQL Warehouse. Aby uzyskać ścieżkę HTTP, zobacz instrukcje opisane wcześniej w tym artykule. Ten parametr jest wymagany. Przykład: `sql/protocolv1/o/1234567890123456/1234-567890-test123` dla klastra. `/sql/1.0/warehouses/a1b234c567d8e9fa` dla usługi SQL Warehouse.
`access_token`, `auth_type` Typ: `str` Informacje o ustawieniach uwierzytelniania usługi Azure Databricks. Aby uzyskać szczegółowe informacje, zobacz Uwierzytelnianie.
`session_configuration` Typ: `dict[str, Any]` Słownik parametrów konfiguracji sesji platformy Spark. Ustawienie konfiguracji jest równoważne użyciu `SET key=val` polecenia SQL. Uruchom polecenie SQL `SET -v`, aby uzyskać pełną listę dostępnych konfiguracji. Wartość domyślna to `None`. Ten parametr jest opcjonalny. Przykład: `{"spark.sql.variable.substitute": True}`
`http_headers` Typ: `List[Tuple[str, str]]]` Dodatkowe pary (klucz, wartość) ustawiane w nagłówkach HTTP na każdym żądaniu RPC, które wykonuje klient. Typowe użycie nie spowoduje ustawienia dodatkowych nagłówków HTTP. Wartość domyślna to `None`. Ten parametr jest opcjonalny. Od wersji 2.0
`catalog` Typ: `str` Początkowy katalog do użycia dla połączenia. Wartość domyślna to `None` (w tym przypadku domyślny katalog, zazwyczaj `hive_metastore`, będzie używany). Ten parametr jest opcjonalny. Od wersji 2.0
`schema` Typ: `str` Początkowy schemat do użycia dla połączenia. Ustawia się na `None` (w takim przypadku zostanie użyty domyślny schemat `default`). Ten parametr jest opcjonalny. Od wersji 2.0
`use_cloud_fetch` Typ: `bool` `True` w celu wysyłania żądań pobierania bezpośrednio do magazynu obiektów w chmurze w celu pobrania fragmentów danych. `False` (ustawienie domyślne) do wysyłania żądań pobierania bezpośrednio do usługi Azure Databricks. Jeśli `use_cloud_fetch` jest ustawiona na `True` ale dostęp sieciowy jest zablokowany, pobieranie żądań zakończy się niepowodzeniem. Od wersji 2.8

Wybrane Connection metody obejmują następujące elementy:

Metody
`close` Zamyka połączenie z bazą danych i zwalnia wszystkie skojarzone zasoby na serwerze. Wszelkie dodatkowe wywołania tego połączenia będą zgłaszać błąd `Error`. Brak parametrów. Brak wartości zwracanej.
`cursor` Zwraca nowy `Cursor` obiekt, który umożliwia przechodzenie przez rekordy w bazie danych. Brak parametrów.

Klasa `Cursor`

Aby utworzyć obiekt, wywołaj Cursor metodę Connection klasycursor.

Wybrane Cursor atrybuty obejmują następujące elementy:

Atrybuty

Atrybuty
`arraysize` Używany z `fetchmany` metodą określa rozmiar buforu wewnętrznego, czyli liczbę wierszy pobieranych z serwera naraz. Domyślna wartość to `10000`. Aby uzyskać wąskie wyniki (wyniki, w których każdy wiersz nie zawiera dużej ilości danych), należy zwiększyć tę wartość w celu uzyskania lepszej wydajności. Dostęp do odczytu i zapisu.
`description` Zawiera język Python `listtuple` obiektów. Każdy z tych obiektów `tuple` zawiera 7 wartości z pierwszymi 2 elementami każdego obiektu `tuple` zawierającymi informacje opisujące jedną kolumnę wyników w następujący sposób: `name`: nazwa kolumny. `type_code`: ciąg reprezentujący typ kolumny. Na przykład kolumna całkowita będzie mieć kod typu `int`. Pozostałe 5 elementów każdego obiektu `tuple` z 7 elementami nie zostało zaimplementowanych, a ich wartości nie zostały zdefiniowane. Zwykle będą zwracane jako 4 `None` wartości, po których następuje pojedyncza wartość `True`. Dostęp tylko do odczytu.

arraysize
Używany z fetchmany metodą określa rozmiar buforu wewnętrznego, czyli liczbę wierszy pobieranych z serwera naraz. Domyślna wartość to 10000. Aby uzyskać wąskie wyniki (wyniki, w których każdy wiersz nie zawiera dużej ilości danych), należy zwiększyć tę wartość w celu uzyskania lepszej wydajności.
Dostęp do odczytu i zapisu.

description
Zawiera język Python listtuple obiektów. Każdy z tych obiektów tuple zawiera 7 wartości z pierwszymi 2 elementami każdego obiektu tuple zawierającymi informacje opisujące jedną kolumnę wyników w następujący sposób:

name: nazwa kolumny.
type_code: ciąg reprezentujący typ kolumny. Na przykład kolumna całkowita będzie mieć kod typu int.

Pozostałe 5 elementów każdego obiektu tuple z 7 elementami nie zostało zaimplementowanych, a ich wartości nie zostały zdefiniowane. Zwykle będą zwracane jako 4
None wartości, po których następuje pojedyncza wartość True.
Dostęp tylko do odczytu.

Wybrane Cursor metody obejmują następujące elementy:

Metody
`cancel` Przerywa uruchamianie dowolnego zapytania bazy danych lub polecenia, które zostało uruchomione kursora. Aby zwolnić skojarzone zasoby na serwerze, wywołaj metodę `close` metoda po wywołaniu `cancel` metody . Brak parametrów. Brak wartości zwracanej.
`close` Zamyka kursor i zwalnia skojarzone zasoby na serwerze. Zamknięcie już zamkniętego kursora może spowodować wystąpienie błędu. Brak parametrów. Brak wartości zwracanej.
`execute` Przygotowuje, a następnie uruchamia zapytanie bazy danych lub polecenie. Brak wartości zwracanej. Parametry: `operation` Typ: `str` Zapytanie lub polecenie do przygotowania, a następnie uruchomienia. Ten parametr jest wymagany. Przykład bez parametru `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'` `)` Przykład z parametrem `parameters` : `cursor.execute(` `'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',` `{ 'pickup_zip': '10019' }` `)` `parameters` Typ: słownik Sekwencja parametrów do użycia z parametrem `operation`. Ten parametr jest opcjonalny. Wartość domyślna to `None`.
`executemany` Przygotowuje, a następnie uruchamia zapytanie bazy danych lub polecenie przy użyciu wszystkich sekwencji parametrów w argumencie `seq_of_parameters` . Zachowano tylko końcowy zestaw wyników. Brak wartości zwracanej. Parametry: `operation` Typ: `str` Zapytanie lub polecenie do przygotowania, a następnie uruchomienia. Ten parametr jest wymagany. `seq_of_parameters` Typ: `list` z `dict` Sekwencja wielu zestawów wartości parametrów do użycia z określonymi zastosowaniami. `operation` parametr. Ten parametr jest wymagany.
`catalogs` Wykonaj zapytanie o metadane dotyczące wykazów. Rzeczywiste wyniki powinny być następnie pobierane przy użyciu metody `fetchmany` lub `fetchall`. Ważne pola w zestawie wyników obejmują: Nazwa pola: `TABLE_CAT`. Typ: `str`. Nazwa wykazu. Brak parametrów. Brak wartości zwracanej. Od wersji 1.0
`schemas` Wykonaj zapytanie o metadane dotyczące schematów. Rzeczywiste wyniki powinny być następnie pobierane przy użyciu metody `fetchmany` lub `fetchall`. Ważne pola w zestawie wyników obejmują: Nazwa pola: `TABLE_SCHEM`. Typ: `str`. Nazwa schematu. Nazwa pola: `TABLE_CATALOG`. Typ: `str`. Wykaz, do którego należy schemat. Brak wartości zwracanej. Od wersji 1.0 Parametry: `catalog_name` Typ: `str` Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny.
`tables` Wykonaj zapytanie o metadane dotyczące tabel i widoków. Rzeczywiste wyniki powinny być następnie pobierane przy użyciu metody `fetchmany` lub `fetchall`. Ważne pola w zestawie wyników obejmują: Nazwa pola: `TABLE_CAT`. Typ: `str`. Katalog, do którego należy tabela. Nazwa pola: `TABLE_SCHEM`. Typ: `str`. Schemat, do którego należy tabela. Nazwa pola: `TABLE_NAME`. Typ: `str`. Nazwa tabeli. Nazwa pola: `TABLE_TYPE`. Typ: `str`. Rodzaj relacji, na przykład `VIEW` lub `TABLE` (dotyczy środowiska Databricks Runtime 10.4 LTS i nowszego, a także do usługi Databricks SQL; wcześniejsze wersje środowiska Databricks Runtime zwracają pusty ciąg). Brak wartości zwracanej. Od wersji 1.0 Parametry `catalog_name` Typ: `str` Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako znak wieloznaczny. Ten parametr jest opcjonalny. `table_name` Typ: `str` Nazwa tabeli, o której mają zostać pobrane informacje. Znak `%` jest interpretowany jako znak wieloznaczny. Ten parametr jest opcjonalny. `table_types` Typ: `List[str]` Lista typów tabel, które mają być zgodne, na przykład `TABLE` lub `VIEW`. Ten parametr jest opcjonalny.
`columns` Wykonaj zapytanie o metadane dotyczące kolumn. Rzeczywiste wyniki powinny być następnie pobierane przy użyciu metody `fetchmany` lub `fetchall`. Ważne pola w zestawie wyników obejmują: Nazwa pola: `TABLE_CAT`. Typ: `str`. Wykaz, do którego należy kolumna. Nazwa pola: `TABLE_SCHEM`. Typ: `str`. Schemat, do którego należy kolumna. Nazwa pola: `TABLE_NAME`. Typ: `str`. Nazwa tabeli, do której należy kolumna. Nazwa pola: `COLUMN_NAME`. Typ: `str`. Nazwa kolumny. Brak wartości zwracanej. Od wersji 1.0 Parametry: `catalog_name` Typ: `str` Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `table_name` Typ: `str` Nazwa tabeli, o której mają zostać pobrane informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `column_name` Typ: `str` Nazwa kolumny, której informacje mają być pobierane. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny.
`fetchall` Pobiera wszystkie (lub wszystkie pozostałe) wiersze zapytania. Brak parametrów. Zwraca wszystkie (lub wszystkie pozostałe) wiersze zapytania jako strukturę Python `list` `Row` obiektów. Zgłasza `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub nie wykonano jeszcze żadnego wywołania `execute`.
`fetchmany` Pobiera następne wiersze zapytania. Zwraca do `size` (lub atrybut `arraysize`, jeśli `size` nie zostanie określony) następnych wierszy zapytania jako obiekty `Row` w Pythonie. Jeśli do pobrania pozostało mniej niż `size` wierszy, zostaną zwrócone wszystkie pozostałe. Zgłasza błąd `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub żadne wywołanie `execute` nie zostało jeszcze wykonane. Parametry: `size` Typ: `int` Liczba następnych wierszy do pobrania. Ten parametr jest opcjonalny. Jeśli nie zostanie określony, zostanie użyta wartość atrybutu `arraysize` . Przykład: `cursor.fetchmany(10)`
`fetchone` Pobiera następny wiersz zestawu danych. Brak parametrów. Zwraca następny wiersz zestawu danych jako pojedyncza sekwencja w Pythonie. `tuple` obiekt lub zwraca `None` , jeśli nie ma więcej dostępnych danych. Zgłasza `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub żadne wywołanie `execute` nie zostało jeszcze wykonane.
`fetchall_arrow` Pobiera wszystkie (lub wszystkie pozostałe) wiersze zapytania jako obiekt PyArrow `Table` . Zapytania zwracające bardzo duże ilości danych powinny zamiast tego służyć `fetchmany_arrow` do zmniejszenia zużycia pamięci. Brak parametrów. Zwraca wszystkie (lub wszystkie pozostałe) wiersze zapytania jako tabelę PyArrow. Rzuca wyjątek `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub metoda `execute` nie została jeszcze wywołana. Od wersji 2.0
`fetchmany_arrow` Pobiera następne wiersze zapytania jako obiekt PyArrow `Table` . Zwraca do argumentu `size` (lub atrybutu `arraysize`, jeśli `size` nie jest określony) kolejne wiersze zapytania jako PyArrow w Pythonie. `Table` obiekt. Zgłasza `Error`, jeśli poprzednie wywołanie `execute` nie zwróciło żadnych danych lub nie wykonano jeszcze żadnego wywołania `execute`. Od wersji 2.0 Parametry: `size` Typ: `int` Liczba następnych wierszy do pobrania. Ten parametr jest opcjonalny. Jeśli nie zostanie określony, zostanie użyta wartość atrybutu `arraysize` . Przykład: `cursor.fetchmany_arrow(10)`

Klasa `Row`

Klasa wierszy jest strukturą danych przypominającą krotkę, która reprezentuje pojedynczy wiersz wyników. Jeśli wiersz zawiera kolumnę o nazwie "my_column", możesz uzyskać dostęp do pola "my_column"row za pośrednictwem row.my_column. Do uzyskiwania dostępu do pól można również użyć liczbowych danych, na przykład row[0]. Jeśli nazwa kolumny nie jest dozwolona jako nazwa metody atrybutu (na przykład zaczyna się od cyfry), możesz uzyskać dostęp do pola jako row["1_my_column"].

Od wersji 1.0

Wybrane Row metody obejmują:

| asDict

Zwraca słownikową reprezentację wiersza, indeksowaną według nazw pól. Jeśli istnieją zduplikowane nazwy pól, jedno z zduplikowanych pól (ale tylko jedno) zostanie zwrócone w słowniku. Które zduplikowane pole jest zwracane, nie jest zdefiniowane.

Brak parametrów.

Zwraca zbiór pól. |

Konwersje typu

Poniższa tabela mapuje typy danych Apache Spark SQL na odpowiedniki typów danych języka Python.

Typ danych Apache Spark SQL	Typ danych języka Python
`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`

Rozwiązywanie problemów

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Komunikat

Problem: Po uruchomieniu kodu zostanie wyświetlony komunikat podobny do Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Możliwa przyczyna: Przekazana wartość access_token nie jest prawidłowym osobistym tokenem dostępu usługi Azure Databricks.

Zalecana poprawka: sprawdź, czy przekazana access_token wartość jest poprawna i spróbuj ponownie.

`gaierror(8, 'nodename nor servname provided, or not known')` Komunikat

Problem: Po uruchomieniu kodu zostanie wyświetlony komunikat podobny do Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Możliwa przyczyna: Przekazana wartość server_hostname nie jest poprawną nazwą hosta.

Zalecana poprawka: sprawdź, czy przekazana server_hostname wartość jest poprawna i spróbuj ponownie.

Aby uzyskać więcej informacji o tym, jak znaleźć nazwę hosta serwera, zobacz Uzyskiwanie szczegółów połączenia dla zasobu obliczeniowego usługi Azure Databricks.

`IpAclError` Komunikat

Problem: Po uruchomieniu kodu podczas próby użycia łącznika w notesie usługi Azure Databricks zostanie wyświetlony komunikat Error during request to server: IpAclValidation .

Możliwa przyczyna: może być włączona lista dozwolonych adresów IP dla obszaru roboczego usługi Azure Databricks. Dzięki wyświetlaniu listy dozwolonych adresów IP połączenia z klastrów Spark z powrotem do płaszczyzny sterowania są domyślnie niedozwolone.

Zalecana poprawka: poproś administratora o dodanie podsieci płaszczyzny obliczeniowej do listy dozwolonych adresów IP.

Dodatkowe zasoby

Aby uzyskać więcej informacji, zobacz:

Repozytorium Databricks SQL Connector for Python na GitHub
Typy danych
Wbudowane typy (dla bool, bytearray, float, int i str) na stronie języka Python
datetime (for datetime.date i datatime.datetime) w witrynie internetowej języka Python
liczba dziesiętna (dla decimal.Decimal) w witrynie internetowej języka Python
Wbudowane stałe (dla NoneType) w witrynie internetowej języka Python

Udostępnij za pośrednictwem

Łącznik SQL usługi Databricks dla języka Python

Wymagania

Rozpocznij

Klaster

SQL Warehouse

Uwierzytelnianie

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Uwierzytelnianie maszyny do maszyny OAuth (M2M)

Uwierzytelnianie tokenu Microsoft Entra ID

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Przykłady

Zestaw User-Agent

Pobieranie danych

Wstawianie danych

Metadane zapytania

Zarządzanie kursorami i połączeniami

Zarządzanie plikami w woluminach Katalogu Unity

Konfigurowanie rejestrowania

Testowanie

Dokumentacja API

Pakiet

Moduł

Klasy

Klasa `Connection`

Klasa `Cursor`

Klasa `Row`

Konwersje typu

Rozwiązywanie problemów

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Komunikat

`gaierror(8, 'nodename nor servname provided, or not known')` Komunikat

`IpAclError` Komunikat

Dodatkowe zasoby

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Łącznik SQL usługi Databricks dla języka Python

Wymagania

Rozpocznij

Klaster

SQL Warehouse

Uwierzytelnianie

Uwierzytelnianie osobistego tokenu dostępu usługi Databricks

Uwierzytelnianie maszyny do maszyny OAuth (M2M)

Uwierzytelnianie tokenu Microsoft Entra ID

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Przykłady

Zestaw User-Agent

Pobieranie danych

Wstawianie danych

Metadane zapytania

Zarządzanie kursorami i połączeniami

Zarządzanie plikami w woluminach Katalogu Unity

Konfigurowanie rejestrowania

Testowanie

Dokumentacja API

Pakiet

Moduł

Klasy

Klasa Connection

Klasa Cursor

Klasa Row

Konwersje typu

Rozwiązywanie problemów

tokenAuthWrapperInvalidAccessToken: Invalid access token Komunikat

gaierror(8, 'nodename nor servname provided, or not known') Komunikat

IpAclError Komunikat

Dodatkowe zasoby

Opinia

Dodatkowe zasoby

Klasa `Connection`

Klasa `Cursor`

Klasa `Row`

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Komunikat

`gaierror(8, 'nodename nor servname provided, or not known')` Komunikat

`IpAclError` Komunikat