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

Artykuł
11/16/2024

Łą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 zawiera również dialekt SQLAlchemy dla usługi Azure Databricks. 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 Warehouse.

Rozpocznij

Zainstaluj łącznik SQL Usługi Databricks dla biblioteki języka Python na komputerze deweloperskim, uruchamiając polecenie pip install databricks-sql-connector lub python -m pip install databricks-sql-connector.
Zbierz następujące informacje dotyczące klastra lub magazynu SQL, którego chcesz użyć:

Klaster
- Nazwa hosta serwera klastra. Można to uzyskać z wartości Nazwa hosta serwera na karcie Opcje > zaawansowane JDBC/ODBC dla klastra.
- Ścieżka HTTP klastra. Możesz to uzyskać z wartości ścieżki HTTP na karcie Opcje > zaawansowane JDBC/ODBC dla klastra.
SQL Warehouse
- Nazwa hosta serwera usługi SQL Warehouse. Tę wartość można pobrać z wartości Nazwa hosta serwera na karcie Szczegóły połączenia dla usługi SQL Warehouse.
- Ścieżka HTTP usługi SQL Warehouse. Możesz to uzyskać z wartości ścieżka 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 identyfikatora entra firmy Microsoft
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ść Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
DATABRICKS_HTTP_PATH, ustaw wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
DATABRICKS_TOKEN, ustaw 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 jednostkę usługi Azure Databricks w obszarze roboczym usługi Azure Databricks i utwórz wpis tajny OAuth dla tej jednostki usługi.

Aby utworzyć jednostkę usługi i jej wpis tajny OAuth, zobacz Uwierzytelnianie dostępu do usługi Azure Databricks przy użyciu jednostki usługi przy użyciu protokołu OAuth (OAuth M2M). Zanotuj wartość UUID lub Identyfikator aplikacji jednostki usługi oraz wartość wpisu tajnego dla wpisu tajnego OAuth jednostki usługi.
Nadaj jednostce usługi dostęp do klastra lub magazynu.

Aby udzielić 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 ustaw wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
DATABRICKS_HTTP_PATH, ustaw wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
DATABRICKS_CLIENT_ID, ustaw wartość UUID jednostki usługi lub Identyfikator aplikacji.
DATABRICKS_CLIENT_SECRET, ustaw wartość wpisu tajnego dla wpisu tajnego OAuth jednostki 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 identyfikatora entra firmy Microsoft

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ć interfejsu wiersza polecenia platformy Azure. Zobacz Uzyskiwanie tokenów identyfikatora entra firmy Microsoft dla użytkowników przy użyciu interfejsu wiersza polecenia platformy Azure.
Aby uzyskać jednostkę usługi Microsoft Entra ID, zobacz Uzyskiwanie tokenu dostępu identyfikatora Entra firmy Microsoft za pomocą interfejsu wiersza polecenia platformy Azure. Aby utworzyć jednostkę usługi zarządzanej identyfikatora entra firmy Microsoft, zobacz Zarządzanie 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 wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
Ustaw DATABRICKS_HTTP_PATH wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.
Ustaw DATABRICKS_TOKEN wartość tokenu 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 między użytkownikami protokołu OAuth (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 używa logowania człowieka w czasie rzeczywistym i zgody na uwierzytelnianie docelowego konta użytkownika usługi Azure Databricks. W tym fragmencie kodu założono, że ustawiono następujące zmienne środowiskowe:

Ustaw DATABRICKS_SERVER_HOSTNAME wartość Nazwa hosta serwera dla klastra lub usługi SQL Warehouse.
Ustaw DATABRICKS_HTTP_PATH wartość ścieżka HTTP dla klastra lub usługi SQL Warehouse.

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ładowy kod pobiera wartości server_hostnamezmiennych zmiennych środowiskowych , http_pathi access_token połączenia 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 token dostępu z wymagań.

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

Wykonywanie zapytań o dane
Wstawianie danych
Metadane zapytania
Zarządzanie kursorami i połączeniami
Zarządzanie plikami w woluminach wykazu aparatu Unity
Konfigurowanie rejestrowania

Zapytania o dane

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 trips tabeli w schemacie samples wykazu 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 wykazu aparatu Unity

Łącznik SQL usługi Databricks umożliwia zapisywanie plików lokalnych w woluminach wykazu aparatu Unity, 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ącej get_connection_personal_access_token funkcję, 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 select_nyctaxi_trips funkcji korzystającej z połączenia w celu uzyskania określonej liczby wierszy danych z trips tabeli w samples schemacie wykazu 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 get_connection_personal_access_token funkcje 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 wyśmiewa Connection obiekt. Test wyśmiewa również niektóre dane zgodne ze schematem i wartościami, które znajdują się w rzeczywistych danych. Test zwraca wyśmiewane dane za pośrednictwem pozorowanego połączenia, a następnie sprawdza, czy jedna z wyśmiewanych wartości wierszy danych 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

select_nyctaxi_trips Ponieważ funkcja zawiera instrukcję SELECT i dlatego nie zmienia stanu trips tabeli, 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.

Odwołanie do interfejsu 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, wywołaj metodę Connection 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 `SET -v` SQL, 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 wykaz do użycia dla połączenia. Wartość domyślna to `None` (w tym przypadku domyślny wykaz, 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. Wartość domyślna to `None` (w tym 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 wartość `True` , ale dostęp do sieci jest zablokowany, żądania pobierania 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 Connection metodę Cursor 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 `list` `tuple` obiektów. Każdy z tych `tuple` obiektów zawiera 7 wartości z pierwszymi 2 elementami każdego `tuple` obiektu 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 `int`typu . Pozostałe 5 elementów każdego obiektu 7-item `tuple` nie jest zaimplementowanych, a ich wartości nie są zdefiniowane. Zazwyczaj będą zwracane jako 4 `None` wartości, po których następuje pojedyncza `True` wartość. 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 list tuple obiektów. Każdy z tych tuple obiektów zawiera 7 wartości z pierwszymi 2 elementami każdego tuple obiektu 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 inttypu .

Pozostałe 5 elementów każdego obiektu 7-item tuple nie jest zaimplementowanych, a ich wartości nie są zdefiniowane. Zazwyczaj będą zwracane jako 4
None wartości, po których następuje pojedyncza True wartość.

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 `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 wykazu do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu do pobrania informacji o. 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`. Wykaz, 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 wykazu do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `table_name` Typ: `str` Nazwa tabeli do pobrania informacji o. Znak `%` jest interpretowany jako symbol 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 wykazu do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `schema_name` Typ: `str` Nazwa schematu do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `table_name` Typ: `str` Nazwa tabeli do pobrania informacji o. Znak `%` jest interpretowany jako symbol wieloznaczny. Ten parametr jest opcjonalny. `column_name` Typ: `str` Nazwa kolumny do pobrania informacji o. 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 język Python `list` `Row` Obiektów. Zgłasza błąd `Error` , jeśli poprzednie wywołanie `execute` metody nie zwróciło żadnych danych lub nie `execute` zostało jeszcze wykonane żadne wywołanie.
`fetchmany` Pobiera następne wiersze zapytania. Zwraca wartość do `size` (lub `arraysize` atrybut, jeśli `size` nie zostanie określony) następnych wierszy zapytania jako python `list` `Row` obiektów. Jeśli pozostało mniej niż `size` wiersze do pobrania, zostaną zwrócone wszystkie pozostałe wiersze. Zgłasza błąd `Error` , jeśli poprzednie wywołanie `execute` metody nie zwróciło żadnych danych lub nie `execute` zostało jeszcze wykonane żadne wywołanie. 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 pojedynczą sekwencję jako język Python `tuple` obiekt lub zwraca `None` , jeśli nie ma więcej dostępnych danych. Zgłasza błąd `Error` , jeśli poprzednie wywołanie `execute` metody nie zwróciło żadnych danych lub nie `execute` zostało jeszcze wykonane żadne wywołanie.
`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 błąd `Error` , jeśli poprzednie wywołanie `execute` metody nie zwróciło żadnych danych lub nie `execute` zostało jeszcze wykonane żadne wywołanie. Od wersji 2.0
`fetchmany_arrow` Pobiera następne wiersze zapytania jako obiekt PyArrow `Table` . Zwraca wartość do argumentu `size` (lub `arraysize` atrybutu, jeśli `size` nie zostanie określony) następnych wierszy zapytania jako PyArrow języka Python `Table` sprzeciwiać się. Zgłasza błąd `Error` , jeśli poprzednie wywołanie `execute` metody nie zwróciło żadnych danych lub nie `execute` zostało jeszcze wykonane żadne wywołanie. 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 "my_column" pola 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 reprezentację słownika wiersza, który jest indeksowany 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. Zwracane zduplikowane pole nie jest zdefiniowane.

Brak parametrów.

dict Zwraca wartość pola. |

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 na temat znajdowania nazwy hosta serwera, zobacz Pobieranie 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:

Łącznik SQL usługi Databricks dla repozytorium języka Python w usłudze GitHub
Typy danych
Wbudowane typy (dla bool, , bytearrayfloat, inti str) w witrynie internetowej 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 identyfikatora entra firmy Microsoft

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Przykłady

Zapytania o dane

Wstawianie danych

Metadane zapytania

Zarządzanie kursorami i połączeniami

Zarządzanie plikami w woluminach wykazu aparatu Unity

Konfigurowanie rejestrowania

Testowanie

Odwołanie do interfejsu 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 identyfikatora entra firmy Microsoft

Uwierzytelnianie typu użytkownik-komputer (U2M) OAuth

Przykłady

Zapytania o dane

Wstawianie danych

Metadane zapytania

Zarządzanie kursorami i połączeniami

Zarządzanie plikami w woluminach wykazu aparatu Unity

Konfigurowanie rejestrowania

Testowanie

Odwołanie do interfejsu 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