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

Biblioteka Databricks SQL Connector dla Pythona to biblioteka języka Python, która pozwala na użycie kodu Python do wykonywania poleceń SQL na wszechstronnym środowisku obliczeniowym Azure Databricks oraz magazynach SQL Databricks. Łą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.

Ważne

Łącznik SQL usługi Databricks dla języka Python w wersji 3.0.0 lub nowszej obsługuje natywne sparametryzowane wykonywanie zapytań, co uniemożliwia wstrzyknięcie kodu SQL i może zwiększyć wydajność zapytań. Poprzednie wersje korzystały z wykonywania poleceń SQL z parametrami inline, co nie zapewnia ochrony przed wstrzyknięciem SQL i wiąże się z innymi wadami. Aby uzyskać więcej informacji, zobacz Using Native Parameters (Używanie parametrów natywnych).

Łą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 językiem Python w wersji 3.8 lub nowszej.
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ące uniwersalne zasoby obliczeniowe lub magazyn SQL.

Wprowadzenie

Zainstaluj łącznik SQL usługi Databricks dla języka Python. PyArrow to opcjonalna zależność łącznika SQL usługi Databricks dla języka Python i nie jest instalowana domyślnie w wersji 4.0.0 lub nowszej łącznika. Jeśli PyArrow nie jest zainstalowana, funkcje, takie jak CloudFetch i inne funkcje narzędzia Apache Arrow, nie są 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 uniwersalnych zasobów obliczeniowych lub magazynu SQL, których chcesz użyć.

Obliczenia ogólnego przeznaczenia
- Nazwa hosta serwera obliczeniowego wielofunkcyjnego. Tę wartość można pobrać z wartości Nazwa hosta serwera na karcie Opcje > zaawansowane JDBC/ODBC dla wszystkich celów obliczeniowych.
- Ścieżka HTTP zasobów obliczeniowych wielozadaniowych. Możesz to uzyskać z wartości ścieżki HTTP na karcie Opcje > zaawansowane JDBC/ODBC dla obliczeń wszystkich celów.
Uwaga

Łącznik SQL nie obsługuje nawiązywania połączenia z obliczeniami zadań.

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 temacie Tworzenie osobistych tokenów dostępu 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ść Nazwa hosta serwera dla zasobów obliczeniowych ogólnego przeznaczenia lub usługi SQL Warehouse.
DATABRICKS_HTTP_PATH, ustaw wartość ścieżki HTTP dla zasobów obliczeniowych ogólnego przeznaczenia lub usługi SQL Warehouse.
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 wpis tajny OAuth, zobacz Autoryzowanie dostępu jednostki usługi do usługi Azure Databricks przy użyciu protokołu OAuth. Zanotuj wartość UUID lub Identyfikator aplikacji dla jednostki usługowej oraz wartość Tajna jako tajne OAuth dla tej jednostki.
Nadaj jednostce usługi dostęp do zasobów obliczeniowych ogólnego zastosowania lub magazynu danych.

Aby udzielić jednostce usługi dostępu do zasobów obliczeniowych lub magazynu ogólnego przeznaczenia, 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 ustaw wartość Nazwa hosta serwera dla zasobów obliczeniowych ogólnego przeznaczenia lub usługi SQL Warehouse.
DATABRICKS_HTTP_PATH, ustaw wartość ścieżki HTTP dla zasobów obliczeniowych ogólnego przeznaczenia lub usługi SQL Warehouse.
DATABRICKS_CLIENT_ID, przypisz do wartości UUID jednostki głównej usługi lub Identyfikator aplikacji.
DATABRICKS_CLIENT_SECRET, ustaw wartość tajnego klucza dla tajnego klucza OAuth głównego obiektu 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 Pobieranie ręczne tokenów Microsoft Entra ID.
Aby zapoznać się z jednostką usługi Microsoft Entra ID, zobacz Uzyskiwanie tokenów dla jednostek usługi. Aby utworzyć zarządzaną jednostkę usługi Microsoft Entra ID, zapoznaj się z 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 wartość Nazwa hosta serwera dla serwera ogólnego przeznaczenia lub magazynu SQL.
Ustaw DATABRICKS_HTTP_PATH na wartość ścieżki HTTP dla zasobów obliczeniowych ogólnego przeznaczenia 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 wartość Nazwa hosta serwera dla serwera ogólnego przeznaczenia lub magazynu SQL.
Ustaw DATABRICKS_HTTP_PATH na wartość ścieżki HTTP dla zasobów obliczeniowych ogólnego przeznaczenia 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ć Databricks SQL Connector dla języka Python do wykonywania zapytań i wstawiania danych, zapytań o metadane, zarządzania kursorami i połączeniami, zarządzania plikami w Unity Catalog i konfigurowania rejestrowania.

Uwaga

W poniższych przykładach kodu pokazano, jak używać osobistego tokenu dostępu usługi Azure Databricks do uwierzytelniania. Aby użyć innego typu uwierzytelniania, 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.

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 środowisku obliczeniowym ogólnego przeznaczenia lub w 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)

Tagi zapytań

Ważne

Ta funkcja jest dostępna w prywatnej wersji zapoznawczej. Aby zażądać dostępu, skontaktuj się z zespołem ds. kont.

W poniższym przykładzie pokazano, jak dołączyć tagi klucz-wartość do zapytań SQL na potrzeby śledzenia i analizy. Tagi zapytań są wyświetlane w system.query.history 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"),
    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)

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

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

    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. Umożliwia to zwalnianie zasobów w usłudze 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_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'"
    )

Konfigurowanie rejestrowania

Łącznik SQL usługi Databricks używa standardowego modułu rejestrowania języka Python. Poniższy przykład umożliwia skonfigurowanie poziomu rejestrowania i wygenerowanie dziennika debugowania:

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 korzystającej z połączenia w celu uzyskania ustalonej liczby wierszy danych z tabeli trips w schemacie wykazu samplesnyctaxi.

# 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

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 dane próbne za pośrednictwem udawanego połączenia, a następnie sprawdza, czy jedna z wartości wierszy danych próbnych jest zgodna z oczekiwaną 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 wyśmiewanie umożliwia szybkie przeprowadzanie testów bez oczekiwania na nawiązanie rzeczywistego połączenia 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

Ta sekcja zawiera dokumentację API dla pakietu databricks-sql-connector. Zobacz databricks-sql-connector w indeksie pakietów języka Python (PyPI).

Moduł

Moduł databricks.sqldatabricks-sql-connector pakietu zawiera metodę inicjalizacji połączenia z magazynem SQL.

metoda connect

Inicjuje połączenie z usługą SQL Warehouse. Zwraca obiekt Connection.

Parameter	Typ	Description
`server_hostname`	`str`	To jest wymagane. Nazwa hosta serwera dla obliczeń ogólnego przeznaczenia lub magazynu SQL, na przykład `adb-1234567890123456.7.azuredatabricks.net`. Aby uzyskać nazwę hosta serwera, zobacz instrukcje w temacie Wprowadzenie.
`http_path`	`str`	To jest wymagane. Ścieżka HTTP wszystkich celów obliczeniowych lub usługi SQL Warehouse, na przykład `sql/protocolv1/o/1234567890123456/1234-567890-test123` dla obliczeń wszystkich celów lub `/sql/1.0/warehouses/a1b234c567d8e9fa` dla usługi SQL Warehouse. Aby uzyskać ścieżkę HTTP, zobacz instrukcje w temacie Wprowadzenie.
`access_token`, , `auth_type`, `credentials_provider`, , `passwordusername`	`str`	Informacje o ustawieniach uwierzytelniania usługi Azure Databricks. Aby uzyskać szczegółowe informacje, zobacz Uwierzytelnianie.
`session_configuration`	`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`. Przykład: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Opcjonalny. Dodatkowe pary (klucz, wartość) ustawiane w nagłówkach HTTP przy każdym żądaniu RPC wykonywanym przez klienta. Typowe użycie nie spowoduje ustawienia dodatkowych nagłówków HTTP. Wartość domyślna to `None`.
`catalog`	`str`	Opcjonalny. Początkowy katalog do użycia dla połączenia. Wartość domyślna to `None` (w tym przypadku domyślny katalog `hive_metastore` będzie zazwyczaj używany).
`schema`	`str`	Opcjonalny. Początkowy schemat do użycia dla połączenia. Ustawia się na `None` (w takim przypadku zostanie użyty domyślny schemat `default`). Od wersji 2.0
`use_cloud_fetch`	`bool`	Opcjonalny. Czy wysyłać żądania pobierania bezpośrednio do magazynu obiektów w chmurze w celu pobrania fragmentów danych. Wartość domyślna to `True`. Ustaw wartość na `False`, aby wysyłać żądania pobierania bezpośrednio do 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
`user_agent_entry`	`str`	Opcjonalny. Wpis User-Agent do uwzględnienia w nagłówku żądania HTTP na potrzeby śledzenia użycia. Wartość domyślna to `PyDatabricksSqlConnector`.

`Connection` klasa

Reprezentuje połączenie z zasobami obliczeniowymi lub magazynem SQL.

Metody

Klasa Connection udostępnia następujące metody.

Metoda	Description
`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 obiekt Kursor , który umożliwia przechodzenie przez rekordy w bazie danych. Brak parametrów.

`Cursor` klasa

Reprezentuje mechanizm umożliwiający przeglądanie rekordów danych.

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

Atrybuty

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

Attribute Description

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.

Attribute	Description
`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. Zazwyczaj są zwracane jako 4 `None` wartości, po których następuje pojedyncza `True` wartość. Dostęp tylko do odczytu.

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. Zazwyczaj są zwracane jako 4 None wartości, po których następuje pojedyncza True wartość. Dostęp tylko do odczytu.

Metody

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

Metoda	Description
`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` po metodzie `cancel`. 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. Parametry: `operation`: Wymagane. Zapytanie lub polecenie do przygotowania, a następnie uruchomienia. Typ: `str` przykład bez parametru `parameters` : `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Przykład z parametrem `parameters` (przy użyciu natywnych parametrów pozycyjnych): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: opcjonalne. Sekwencja parametrów do użycia z parametrem `operation`. Wartość domyślna to `None`. Typ: `dictionary` Brak wartości zwracanej.
`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. Parametry: `operation`: Wymagane. Zapytanie lub polecenie do przygotowania, a następnie uruchomienia. Typ: `str` `seq_of_parameters`: Wymagane. Sekwencja wielu zestawów wartości parametrów do użycia z parametrem `operation` . Typ: `list` z `dict` Brak wartości zwracanej.
`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`. Nazwa wykazu. Typ: `str` 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`. Nazwa schematu. Typ: `str` Nazwa pola: `TABLE_CATALOG`. Wykaz, do którego należy schemat. Typ: `str` Parametry: `catalog_name`: opcjonalne. Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `schema_name`: opcjonalne. Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` Brak wartości zwracanej. Od wersji 1.0
`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`. Katalog, do którego należy tabela. Typ: `str` Nazwa pola: `TABLE_SCHEM`. Schemat, do którego należy tabela. Typ: `str` Nazwa pola: `TABLE_NAME`. Nazwa tabeli. Typ: `str` Nazwa pola: `TABLE_TYPE`. 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). Typ: `str` Parametry: `catalog_name`: opcjonalne. Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `schema_name`: opcjonalne. Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `table_name`: opcjonalne. Nazwa tabeli, o której mają zostać pobrane informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `table_types`: opcjonalne. Lista typów tabel, które mają być zgodne, na przykład `TABLE` lub `VIEW`. Typ: `List[str]` Brak wartości zwracanej. Od wersji 1.0
`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`. Wykaz, do którego należy kolumna. Typ: `str` Nazwa pola: `TABLE_SCHEM`. Schemat, do którego należy kolumna. Typ: `str` Nazwa pola: `TABLE_NAME`. Nazwa tabeli, do której należy kolumna. Typ: `str` Nazwa pola: `COLUMN_NAME`. Nazwa kolumny. Typ: `str` Parametry: `catalog_name`: opcjonalne. Nazwa katalogu, z której można pobrać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `schema_name`: opcjonalne. Nazwa schematu, o którym chcesz uzyskać informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `table_name`: opcjonalne. Nazwa tabeli, o której mają zostać pobrane informacje. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` `column_name`: opcjonalne. Nazwa kolumny, której informacje mają być pobierane. Znak `%` jest interpretowany jako symbol wieloznaczny. Typ: `str` Brak wartości zwracanej. Od wersji 1.0
`fetchall`	Pobiera wszystkie (lub wszystkie pozostałe) wiersze zapytania. Brak parametrów. Zwraca wszystkie (lub wszystkie pozostałe) wiersze zapytania w postaci obiektu Python `listRow`. 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. Parametry: `size`: opcjonalne. Liczba kolejnych wierszy do pobrania. Jeśli nie zostanie określony, zostanie użyta wartość atrybutu `arraysize` . Typ: `int`. Przykład: `cursor.fetchmany(10)` Zwraca do `size` (lub atrybut `arraysize`, jeśli `size` nie zostanie określony) następnych wierszy zapytania jako obiekty `list` w Pythonie. Jeśli do pobrania pozostało mniej niż `size` wierszy, zostaną zwrócone wszystkie pozostałe. Zgłasza `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub nie wykonano jeszcze żadnego wywołania `execute`.
`fetchone`	Pobiera następny wiersz zestawu danych. Brak parametrów. Zwraca następny wiersz zestawu danych jako pojedynczą sekwencję jako obiekt języka Python `tuple` 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 nie wykonano jeszcze żadnego wywołania `execute`.
`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. Zgłasza `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub nie wykonano jeszcze żadnego wywołania `execute`. Od wersji 2.0
`fetchmany_arrow`	Pobiera następne wiersze zapytania jako obiekt PyArrow `Table` . Parametry: `size`: opcjonalne. Liczba kolejnych wierszy do pobrania. Jeśli nie zostanie określony, zostanie użyta wartość atrybutu `arraysize` . Typ: `int`. Przykład: `cursor.fetchmany_arrow(10)` Zwraca do argumentu `size` (lub atrybutu `arraysize`, jeśli `size` nie jest określony) następnych wierszy zapytania jako obiekt PyArrow `Table` języka Python. Zgłasza `Error`, jeśli poprzednie wywołanie metody `execute` nie zwróciło żadnych danych lub nie wykonano jeszcze żadnego wywołania `execute`. Od wersji 2.0

`Row` klasa

Klasa wierszy jest strukturą danych przypominającą krotkę, która reprezentuje pojedynczy wiersz wyników w wyniku zapytania SQL. 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ą:

Metody

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

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`

Zbieranie danych telemetrycznych

Łącznik SQL usługi Databricks dla języka Python zbiera dane telemetryczne, aby pomóc usłudze Azure Databricks poprawić niezawodność i rozwiązać problemy. Telemetria jest domyślnie włączona i zbiera następujące dane operacyjne:

Szczegóły środowiska klienta, takie jak wersja sterownika, środowisko uruchomieniowe języka Python i system operacyjny
Konfiguracje połączeń sterowników (z wyłączeniem wszelkich danych osobowych)
Pomiary opóźnień operacji
Formaty wyników wykonywania, takie jak śródliniowy kod JSON lub Apache Arrow
Typy operacji, takie jak wykonywanie zapytań, zapytania metadanych lub operacje woluminu
Dane klasyfikacji błędów
Liczba ponownych prób

Ważne

Usługa Azure Databricks nie zbiera zawartości zapytań, wyników zapytań ani żadnych danych osobowych (PII) za pośrednictwem danych telemetrycznych.

Aby wyłączyć zbieranie danych telemetrycznych, ustaw enable_telemetry parametr na 0 wartość podczas tworzenia połączenia.

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 (dla datetime.date i datatime.datetime) na stronie internetowej Pythona
liczba dziesiętna (dla decimal.Decimal) na stronie Pythona
Wbudowane stałe (dla NoneType) w witrynie internetowej języka Python

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-31

Udostępnij za pomocą

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

Wymagania

Wprowadzenie

Obliczenia ogólnego przeznaczenia

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

Tagi zapytań

Wstawianie danych

Metadane zapytania

Zarządzanie kursorami i połączeniami

Zarządzanie plikami w woluminach Katalogu Unity

Konfigurowanie rejestrowania

Testowanie

Dokumentacja API

Moduł

metoda connect

Connection klasa

Metody

Cursor klasa

Atrybuty

Metody

Row klasa

Metody

Konwersje typu

Zbieranie danych telemetrycznych

Rozwiązywanie problemów

tokenAuthWrapperInvalidAccessToken: Invalid access token Komunikat

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

IpAclError Komunikat

Dodatkowe zasoby

Sprzężenie zwrotne

Dodatkowe zasoby

`Connection` klasa

`Cursor` klasa

`Row` klasa

`tokenAuthWrapperInvalidAccessToken: Invalid access token` Komunikat

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

`IpAclError` Komunikat