Коннектор Databricks SQL для Python

Соединитель SQL Databricks для Python — это библиотека Python, которая позволяет использовать код Python для выполнения команд SQL в вычислительных ресурсах Azure Databricks и хранилищах SQL Databricks. Соединитель SQL Databricks для Python проще в настройке и использовании, чем аналогичные библиотеки Python, такие как pyodbc. Эта библиотека соответствует PEP 249 — спецификации API баз данных Python версии 2.0.

Это важно

Соединитель SQL Databricks для Python версии 3.0.0 и выше поддерживает собственное параметризованное выполнение запроса, что предотвращает внедрение SQL и может повысить производительность запросов. Предыдущие версии использовали встроенное параметризованное выполнение, которое не безопасно от внедрения SQL и имеет другие недостатки. Дополнительные сведения см. в разделе "Использование собственных параметров".

Соединитель SQL Databricks для Python также поддерживает диалект SQLAlchemy для Azure Databricks, но его необходимо установить для использования этих функций. См. статью Об использовании SQLAlchemy с Azure Databricks.

Требования

Компьютер разработки под управлением Python 3.8 и более поздних версий.
Databricks рекомендует использовать виртуальные среды Python, такие как venv, которые включены в Python. Виртуальные среды помогают обеспечить использование правильных версий Python и Соединителя SQL Databricks для Python вместе. Настройка и использование виртуальных сред выходят за рамки этой статьи. Дополнительные сведения см. в статье "Создание виртуальных сред".
Существующий универсальный вычислительный ресурс или хранилище SQL.

Начало работы

Установите коннектор SQL Databricks для Python. PyArrow является необязательной зависимостью соединителя SQL Databricks для Python и не устанавливается по умолчанию в версии 4.0.0.0 и выше соединителя. Если PyArrow не установлен, такие функции, как CloudFetch, и другие возможности Apache Arrow недоступны, что может повлиять на производительность при обработке больших объемов данных.
- Чтобы установить бережливый соединитель, используйте следующую команду:
```
pip install databricks-sql-connector
```
- Чтобы установить полный соединитель, включая PyArrow, используйте следующую команду:
```
pip install databricks-sql-connector[pyarrow]
```
Соберите следующие сведения для всех целевых вычислительных ресурсов или хранилища SQL, которые вы хотите использовать:

Вычислительные ресурсы для всех целей
- Имя узла сервера для всех целевых вычислений. Это можно получить из значения имени узла сервера на вкладке "Дополнительные параметры > JDBC/ODBC" для вычисления всех целей.
- HTTP-путь для всех целевых вычислений. Это можно получить из значения ПУТИ HTTP на вкладке "Дополнительные параметры > JDBC/ODBC" для вычислений всех целей.
Примечание.

Соединитель SQL не поддерживает подключение к вычислениям заданий.

Хранилище SQL
- Имя узла сервера хранилища SQL. Вы можете получить это из значения имени узла сервера на вкладке "Сведения о подключении" для вашего хранилища SQL.
- Путь HTTP хранилища SQL. Вы можете получить это из значения HTTP-пути на вкладке Сведения о подключении для вашего SQL-хранилища.

Проверка подлинности

Соединитель SQL Databricks для Python поддерживает следующие типы проверки подлинности Azure Databricks:

Аутентификация с использованием личного токена доступа Databricks
Аутентификация токена Microsoft Entra ID
Аутентификация OAuth для машинного взаимодействия (M2M)
Проверка подлинности OAuth между пользователем и машиной (U2M)

Соединитель SQL Databricks для Python пока не поддерживает следующие типы проверки подлинности Azure Databricks:

Аутентификация с использованием личного токена доступа Databricks

Чтобы использовать коннектор Databricks SQL для Python с аутентификацией с помощью личного маркера доступа Azure Databricks, необходимо сначала создать личный маркер доступа Azure Databricks. Для этого выполните действия, описанные в разделе "Создание личных маркеров доступа для пользователей рабочей области".

Чтобы аутентифицировать соединитель SQL Databricks для Python, используйте следующий фрагмент кода. В этом фрагменте предполагается, что вы установили следующие переменные среды:

DATABRICKS_SERVER_HOSTNAMEЗадайте значение имени узла сервера для вычислительных ресурсов общего назначения или хранилища SQL.
DATABRICKS_HTTP_PATH, установите значение как HTTP-путь для вычислений общего назначения или хранилища данных SQL.
DATABRICKS_TOKEN должен быть установлен в качестве персонального токена доступа Azure Databricks.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

Аутентификация OAuth между машинами (M2M)

Соединитель SQL Databricks для Python версии 2.7.0 и выше поддерживает проверку подлинности OAuth на компьютере (M2M). Необходимо также установить пакет SDK Databricks для Python 0.18.0 или более поздней версии (например, выполнив pip install databricks-sdk или python -m pip install databricks-sdk).

Чтобы использовать соединитель SQL Databricks для Python с проверкой подлинности OAuth M2M, необходимо выполнить следующие действия.

Создайте сервисный принципал Azure Databricks в рабочей области Azure Databricks и создайте секрет OAuth для этого сервисного принципала.

Сведения о создании субъекта-службы и его секрета OAuth см. в статье "Авторизация доступа субъекта-службы к Azure Databricks с помощью OAuth". Запишите значение UUID или идентификатора приложения принципала службы и значение секрета для OAuth-ключа принципала службы.
Предоставьте основному элементу службы доступ к универсальным вычислительным ресурсам или хранилищу данных.

Чтобы предоставить субъекту-службе доступ ко всем целевым вычислительным ресурсам или хранилищу, ознакомьтесь с разрешениями вычислений или управлением хранилищем SQL.

DATABRICKS_SERVER_HOSTNAME Задайте значение имени узла сервера для вычислительных ресурсов общего назначения или хранилища SQL.
DATABRICKS_HTTP_PATH, установите значение как HTTP-путь для вычислений общего назначения или хранилища данных SQL.
DATABRICKS_CLIENT_IDУстановите для главного объекта службы значение UUID или идентификатор приложения.
DATABRICKS_CLIENT_SECRET, установите значение секрет для OAuth секрета служебного принципала.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

Проверка подлинности токена идентификатора Microsoft Entra

Чтобы использовать соединитель Databricks SQL для Python с аутентификацией токеном Microsoft Entra ID, необходимо предоставить этому соединителю токен Microsoft Entra ID. Чтобы создать токен доступа Microsoft Entra ID, сделайте следующее:

Для пользователя Azure Databricks можно использовать Azure CLI. См. Получение токенов Microsoft Entra ID вручную.
Сведения о субъекте-службе идентификатора Microsoft Entra см. в разделе "Получение маркеров для субъектов-служб". Чтобы создать управляемый принципал службы Microsoft Entra ID, см. раздел Субъекты-службы.

Токены Microsoft Entra ID имеют срок действия по умолчанию около 1 часа. Чтобы создать новый маркер идентификатора Microsoft Entra, повторите этот процесс.

Задайте DATABRICKS_SERVER_HOSTNAME значение имени узла сервера для вычислительных ресурсов общего назначения или хранилища SQL.
Задайте DATABRICKS_HTTP_PATH значение HTTP-пути для ваших универсальных вычислительных ресурсов или хранилища SQL.
Установите DATABRICKS_TOKEN в качестве токена идентификатора Microsoft Entra ID.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

Аутентификация пользователя на машине по OAuth (U2M)

Соединитель SQL Databricks для Python версии 2.7.0 и более поздних версий поддерживает проверку подлинности OAuth на компьютере (U2M). Кроме того, необходимо установить пакет SDK Databricks для Python 0.19.0 или более поздней версии (например, запустив pip install databricks-sdk или python -m pip install databricks-sdk).

Чтобы аутентифицировать коннектор SQL Databricks для Python с помощью аутентификации OAuth U2M, используйте следующий фрагмент кода. Проверка подлинности OAuth U2M использует вход в режиме реального времени и согласие на проверку подлинности целевой учетной записи пользователя Azure Databricks. В этом фрагменте предполагается, что вы установили следующие переменные среды:

Задайте DATABRICKS_SERVER_HOSTNAME значение имени узла сервера для вычислительных ресурсов общего назначения или хранилища SQL.
Задайте DATABRICKS_HTTP_PATH значение HTTP-пути для ваших универсальных вычислительных ресурсов или хранилища SQL.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

Примеры

В следующих примерах кода показано, как использовать соединитель SQL Databricks для Python для запроса и вставки данных, запроса метаданных, управления курсорами и подключениями, управления файлами в каталоге Unity и настройки ведения журнала.

Примечание.

В следующих примерах кода показано, как использовать личный маркер доступа Azure Databricks для проверки подлинности. Сведения об использовании другого типа проверки подлинности см. в разделе "Проверка подлинности".

В этих примерах кода значения переменных подключения server_hostname, http_pathи access_token извлекаются из соответствующих переменных среды.

DATABRICKS_SERVER_HOSTNAME, которая предоставляет значение Имени узла сервера в соответствии с требованиями.
DATABRICKS_HTTP_PATH, который представляет значение Пути HTTP в соответствии с требованиями.
DATABRICKS_TOKEN, которая представляет ваш токен доступа из требований.

Комплект User-Agent

Следующий пример кода демонстрирует, как настроить приложение User-Agent 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)

Запрос данных

В следующем примере кода показано, как вызвать соединитель SQL Databricks для Python для выполнения базовой команды SQL на всех целевых вычислительных ресурсах или хранилище SQL. Эта команда возвращает первые две строки из таблицы trips в схеме samples каталога 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)

Теги запросов

Это важно

Эта функция доступна в закрытой предварительной версии. Чтобы запросить доступ, обратитесь в вашу команду поддержки аккаунтов.

В следующем примере показано, как прикрепить теги key-value к запросам SQL для отслеживания и анализа. Теги запросов отображаются в system.query.history таблице.

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)

Вставка данных

В следующем примере показано, как вставить небольшие объемы данных (тысячи строк):

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)

Для больших объемов данных необходимо сначала передать данные в облачное хранилище, а затем выполнить команду COPY INTO.

Метаданные запроса

Есть специальные методы для извлечения метаданных. В следующем примере извлекаются метаданные о столбцах в примере таблицы:

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

Управление курсорами и подключениями

Рекомендуется закрыть все подключения и курсоры, которые больше не используются. Это освобождает ресурсы в вычислительных ресурсах Azure Databricks all-purpose и хранилищах SQL Databricks.

Вы можете применить диспетчер контекста (синтаксис with, используемый в предыдущих примерах) для управления ресурсами или явно вызвать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()

Управление файлами в томах каталога Unity

Соединитель SQL Databricks позволяет записывать локальные файлы в каталог Unity тома, загружать файлы из томов и удалять файлы из томов, как показано в следующем примере:

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

Конфигурировать журнал

Соединитель SQL Databricks использует стандартный модуль ведения журнала Python. В следующем примере настраивается уровень ведения журнала и создается журнал отладки:

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

Тестирование

Чтобы протестировать код, используйте платформы тестов Python, такие как pytest. Чтобы протестировать код в имитированных условиях без вызова конечных точек REST API Azure Databricks или изменения состояния учетных записей Или рабочих областей Azure Databricks, можно использовать библиотеки макетирования Python, такие как unittest.mock.

Например, учитывая следующий файл с именем helpers.py, содержащий функцию get_connection_personal_access_token, которая использует личный маркер доступа Azure Databricks для возврата подключения к рабочей области Azure Databricks, а также функцию select_nyctaxi_trips, использующую это подключение для получения указанного количества строк данных из таблицы trips в схеме samples каталога nyctaxi:

# helpers.py

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

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

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

И учитывая следующий файл с именем main.py, который вызывает функции get_connection_personal_access_token и 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)

Следующий файл с именем test_helpers.py проверяет, возвращает ли select_nyctaxi_trips функция ожидаемый ответ. Вместо создания реального подключения к целевой рабочей области этот тест макетирует Connection объект. Тест также макетирует некоторые данные, соответствующие схеме и значениям, которые находятся в реальных данных. Тест возвращает мокаемые данные через мокаемое подключение, а затем проверяет, соответствует ли одно из значений строк мокаемых данных ожидаемому значению.

# 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 содержит инструкцию SELECT и поэтому не изменяет состояние таблицы trips, использование mock-объектов не является абсолютно необходимым в этом примере. Однако мокирование позволяет быстро проводить ваши тесты, не ожидая реального подключения к рабочей области. Кроме того, макетирование позволяет выполнять имитированные тесты несколько раз для функций, которые могут изменить состояние таблицы, например INSERT INTO, UPDATEи DELETE FROM.

Справочник по API

В этом разделе содержится справочник по API для databricks-sql-connector пакета. См. databricks-sql-connector в каталоге пакетов Python (PyPI).

Модуль

Модуль databricks.sqldatabricks-sql-connector пакета содержит метод инициализации подключения к хранилищу SQL.

Метод соединения

Инициализирует подключение к хранилищу SQL. Возвращает объект соединения.

Параметр	Тип	Description
`server_hostname`	`str`	Обязательное. Например, имя хоста сервера для универсальных вычислительных ресурсов или хранилища SQL `adb-1234567890123456.7.azuredatabricks.net`. Чтобы получить имя узла сервера, ознакомьтесь с инструкциями в разделе "Начало работы".
`http_path`	`str`	Обязательное. HTTP-путь для всех целевых вычислений или хранилища SQL, например `sql/protocolv1/o/1234567890123456/1234-567890-test123` для вычислений всех целей или `/sql/1.0/warehouses/a1b234c567d8e9fa` хранилища SQL. Чтобы получить путь HTTP, см. инструкции в разделе "Начало работы".
`access_token`, `auth_type`, , `credentials_provider`, `passwordusername`	`str`	Сведения о параметрах проверки подлинности Azure Databricks. Дополнительные сведения см. в разделе "Проверка подлинности".
`session_configuration`	`dict[str, Any]`	Словарь параметров конфигурации сеанса Spark. Настройка конфигурации эквивалентна использованию команды SQL `SET key=val`. Выполните команду SQL `SET -v`, чтобы получить полный список доступных конфигураций. По умолчанию — `None`. Пример: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Необязательно. Дополнительные пары (ключ, значение) для задания заголовков HTTP в каждом запросе RPC, который выполняет клиент. Обычное использование не будет задавать дополнительные заголовки HTTP. По умолчанию — `None`.
`catalog`	`str`	Необязательно. Исходный каталог, используемый для подключения. По умолчанию `None` (в этом случае будет использоваться каталог по умолчанию, обычно `hive_metastore`).
`schema`	`str`	Необязательно. Начальная схема, используемая для подключения. По умолчанию используется `None` (в этом случае будет использована схема `default`). Начиная с версии 2.0
`use_cloud_fetch`	`bool`	Необязательно. Следует ли отправлять запросы на получение непосредственно в облачное хранилище объектов, чтобы скачать фрагменты данных. По умолчанию — `True`. Установите значение `False`, чтобы отправить запросы на получение непосредственно в Azure Databricks. Если `use_cloud_fetch` установлено на `True`, но сетевой доступ заблокирован, запросы на получение не будут выполнены. Начиная с версии 2.8
`user_agent_entry`	`str`	Необязательно. Элемент User-Agent, который следует включить в заголовок HTTP-запроса для отслеживания использования. По умолчанию — `PyDatabricksSqlConnector`.

`Connection` класс

Представляет подключение к вычислительным ресурсам или хранилищу SQL.

Методы

Класс Connection предоставляет следующие методы.

Метод	Description
`close`	Закрывает соединение с базой данных и освобождает все связанные ресурсы на сервере. При любых дополнительных вызовах этого соединения будет выброшено `Error`. Нет параметров. Отсутствие возвращаемого значения.
`cursor`	Возвращает новый объект Cursor , который включает обход записей в базе данных. Нет параметров.

`Cursor` класс

Представляет механизм обхода записей данных.

Чтобы создать Cursor объект, вызовите cursor метод класса Connection.

Атрибуты

К выбранным Cursor атрибутам относятся следующие:

Свойство Description

arraysize Используется с методом fetchmany , указывает внутренний размер буфера, который также указывает, сколько строк фактически извлекается из сервера за раз. Значение по умолчанию — 10000. Для сокращения результатов (чтобы каждая строка результатов не содержала большого объема данных) следует увеличить это значение с целью повышения производительности. Доступ для чтения и записи.

Свойство	Description
`arraysize`	Используется с методом `fetchmany` , указывает внутренний размер буфера, который также указывает, сколько строк фактически извлекается из сервера за раз. Значение по умолчанию — `10000`. Для сокращения результатов (чтобы каждая строка результатов не содержала большого объема данных) следует увеличить это значение с целью повышения производительности. Доступ для чтения и записи.
`description`	Содержит `list` Python объектов `tuple`. Каждый из этих объектов `tuple` содержит 7 значений, при этом первые 2 элемента каждого объекта `tuple` содержат сведения, описывающие один столбец результатов следующим образом: `name`: имя столбца. `type_code`: строка, представляющая тип столбца. Например, целый столбец будет иметь код типа `int`. Остальные 5 элементов каждого 7-элементного `tuple` объекта не реализованы, а их значения не определены. Обычно они возвращаются в виде 4 `None` значений, за которым следует одно `True` значение. Доступ только для чтения.

description

Содержит list Python объектов tuple. Каждый из этих объектов tuple содержит 7 значений, при этом первые 2 элемента каждого объекта tuple содержат сведения, описывающие один столбец результатов следующим образом:

name: имя столбца.
type_code: строка, представляющая тип столбца. Например, целый столбец будет иметь код типа int. Остальные 5 элементов каждого 7-элементного tuple объекта не реализованы, а их значения не определены. Обычно они возвращаются в виде 4 None значений, за которым следует одно True значение. Доступ только для чтения.

Методы

Выбранные Cursor методы включают следующие:

Метод	Description
`cancel`	Прерывает выполнение любого запроса к базе данных или команды, запущенной курсором. Чтобы освободить связанные ресурсы на сервере, вызовите `close` метод после вызова `cancel` метода. Нет параметров. Отсутствие возвращаемого значения.
`close`	Закрывает курсор и освобождает связанные ресурсы на сервере. Закрытие уже закрытого курсора может вызвать ошибку. Нет параметров. Отсутствие возвращаемого значения.
`execute`	Подготавливает, а затем выполняет запрос к базе данных или соответствующую команду. Параметры: `operation`:Обязательно. Запрос или команда для подготовки и последующего выполнения. Тип: пример без `str` параметра: `parameters` `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` Пример с параметром `parameters` (с использованием собственных позиционных параметров): `cursor.execute('SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip = ? LIMIT ?', ['10019', 2])` `parameters`: необязательный параметр. Последовательность параметров, используемых с параметром `operation`. Значение по умолчанию — `None`. Тип: `dictionary` Отсутствие возвращаемого значения.
`executemany`	Подготавливает, а затем выполняет запрос к базе данных или команду, используя все последовательности параметров в `seq_of_parameters` аргументе. Сохраняется только окончательный результирующий набор. Параметры: `operation`:Обязательно. Запрос или команда для подготовки и последующего выполнения. Тип: `str` `seq_of_parameters`:Обязательно. Последовательность многих наборов значений параметров, используемых с параметром `operation` . Тип: `list` для `dict`. Отсутствие возвращаемого значения.
`catalogs`	Выполните запрос метаданных о каталогах. Фактические результаты следует извлекать с помощью `fetchmany` или `fetchall`. Важные поля в результирующем наборе: Имя поля: `TABLE_CAT`. Имя каталога. Тип: `str` Нет параметров. Отсутствие возвращаемого значения. Начиная с версии 1.0
`schemas`	Выполнение запроса метаданных о схемах. Фактические результаты следует извлекать с помощью `fetchmany` или `fetchall`. Важные поля в результирующем наборе: Имя поля: `TABLE_SCHEM`. Имя схемы. Тип: `str` Имя поля: `TABLE_CATALOG`. Каталог, к которому принадлежит схема. Тип: `str` Параметры: `catalog_name`: необязательный параметр. Имя каталога, о котором нужно получить сведения. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `schema_name`: необязательный параметр. Имя схемы, о которой нужно получить информацию. Символ `%` интерпретируется как подстановочный знак. Тип: `str` Отсутствие возвращаемого значения. Начиная с версии 1.0
`tables`	Выполнение запроса метаданных о таблицах и представлениях. Фактические результаты следует извлекать с помощью `fetchmany` или `fetchall`. Важные поля в результирующем наборе: Имя поля: `TABLE_CAT`. Каталог, к которому принадлежит таблица. Тип: `str` Имя поля: `TABLE_SCHEM`. Схема, к которой принадлежит таблица. Тип: `str` Имя поля: `TABLE_NAME`. Имя таблицы. Тип: `str` Имя поля: `TABLE_TYPE`. Тип отношения, например `VIEW` или `TABLE` (относится к Databricks Runtime 10.4 LTS и выше, а также к Databricks SQL; предыдущие версии Databricks Runtime возвращают пустую строку). Тип: `str` Параметры: `catalog_name`: необязательный параметр. Имя каталога, о котором нужно получить сведения. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `schema_name`: необязательный параметр. Имя схемы, о которой нужно получить информацию. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `table_name`: необязательный параметр. Название таблицы для получения информации. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `table_types`: необязательный параметр. Список типов таблиц для сопоставления, например `TABLE` или `VIEW`. Тип: `List[str]` Отсутствие возвращаемого значения. Начиная с версии 1.0
`columns`	Выполните запрос метаданных о столбцах. Фактические результаты следует извлекать с помощью `fetchmany` или `fetchall`. Важные поля в результирующем наборе: Имя поля: `TABLE_CAT`. Каталог, к которому принадлежит столбец. Тип: `str` Имя поля: `TABLE_SCHEM`. Схема, к которой принадлежит столбец. Тип: `str` Имя поля: `TABLE_NAME`. Имя таблицы, к которой принадлежит столбец. Тип: `str` Имя поля: `COLUMN_NAME`. Имя столбца. Тип: `str` Параметры: `catalog_name`: необязательный параметр. Имя каталога, о котором нужно получить сведения. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `schema_name`: необязательный параметр. Имя схемы, о которой нужно получить информацию. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `table_name`: необязательный параметр. Название таблицы для получения информации. Символ `%` интерпретируется как подстановочный знак. Тип: `str` `column_name`: необязательный параметр. Имя столбца для получения сведений. Символ `%` интерпретируется как подстановочный знак. Тип: `str` Отсутствие возвращаемого значения. Начиная с версии 1.0
`fetchall`	Возвращает все (или все оставшиеся) строки запроса. Нет параметров. Возвращает все (или все оставшиеся) строки запроса в виде Python `listRow` объектов. Вызывает исключение `Error`, если предыдущий вызов метода `execute` не вернул никаких данных или вызов `execute` еще не был выполнен.
`fetchmany`	Возвращает следующие строки запроса. Параметры: `size`: необязательный параметр. Количество строк, которые нужно получить дальше. Если значение не указано, используется значение атрибута `arraysize`. Тип: `int`. Пример: `cursor.fetchmany(10)` Возвращает до `size` (или атрибут `arraysize`, если `size` не указано) следующих строк запроса в виде Python `list` из объектов `Row`. Если строк для извлечения осталось меньше, чем `size`, будут возвращены все оставшиеся строки. Вызывает исключение `Error`, если предыдущий вызов метода `execute` не вернул никаких данных или вызов `execute` еще не был выполнен.
`fetchone`	Возвращает следующую строку набора данных. Нет параметров. Возвращает следующую строку набора данных в виде одной последовательности в виде объекта Python `tuple` или возвращается `None` , если нет дополнительных доступных данных. Вызывает исключение `Error`, если предыдущий вызов метода `execute` не вернул никаких данных или вызов `execute` еще не был выполнен.
`fetchall_arrow`	Возвращает все (или все оставшиеся) строки запроса в виде объекта PyArrow `Table`. Для запросов, возвращающих очень большие объемы данных, вместо него следует использовать `fetchmany_arrow`, чтобы уменьшить потребление памяти. Нет параметров. Возвращает все (или все оставшиеся) строки запроса в виде таблицы PyArrow. Вызывает исключение `Error`, если предыдущий вызов метода `execute` не вернул никаких данных или вызов `execute` еще не был выполнен. Начиная с версии 2.0
`fetchmany_arrow`	Возвращает следующие строки запроса в виде объекта PyArrow `Table`. Параметры: `size`: необязательный параметр. Количество строк, которые нужно получить дальше. Если значение не указано, используется значение атрибута `arraysize`. Тип: `int`. Пример: `cursor.fetchmany_arrow(10)` Возвращает до `size` аргумента (или `arraysize` атрибута, если `size` не указан) следующих строк запроса в виде объекта PyArrow `Table` для Python. Вызывает исключение `Error`, если предыдущий вызов метода `execute` не вернул никаких данных или вызов `execute` еще не был выполнен. Начиная с версии 2.0

`Row` класс

Класс строк представляет собой структуру данных, похожую на кортеж, которая представляет отдельную строку результатов в результатах SQL-запроса. Если строка содержит столбец с именем "my_column", вы можете получить доступ к полю "my_column"row через row.my_column. Кроме того, для доступа к полям вы можете использовать числовые индексы, например row[0]. Если имя столбца не допускается в качестве имени метода атрибута (например, начинается с цифры), вы можете получить доступ к полю как row["1_my_column"].

Начиная с версии 1.0

К выбранным Row методам относятся:

Методы

Метод	Description
`asDict`	Возвращает представление словаря строки, которая индексируется по именам полей. Если имена полей дублируются, одно из них (но только одно) будет возвращено в словаре. Возвращаемое дублирующееся поле не определяется.

Преобразование типов

В следующей таблице сопоставляется типы данных Apache Spark SQL с эквивалентами их типов данных Python.

Тип данных Apache Spark SQL	Типы данных 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`

Сбор данных телеметрии

Соединитель SQL Databricks для Python собирает данные телеметрии, чтобы помочь Azure Databricks повысить надежность и устранить неполадки. Данные телеметрии включены по умолчанию и собирают следующие операционные данные:

Сведения о клиентской среде, такие как версия драйвера, среда выполнения Python и операционная система
Конфигурации подключения драйвера (за исключением личных сведений)
Измерения задержки операций
Форматы результатов выполнения, такие как встроенный формат JSON или Apache Arrow
Типы операций, включая выполнение запросов, запросы метаданных или операции с томами
Данные классификации ошибок
Количество повторных попыток

Это важно

Azure Databricks не собирает содержимое запроса, результаты запроса или какие-либо личные данные (PII) с помощью телеметрии.

Чтобы отключить сбор данных телеметрии, задайте значение enable_telemetry для параметра 0 при создании подключения.

Устранение неполадок

Сообщение `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Проблема. При выполнении кода отображается примерно такое сообщение: Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

Возможная причина. Значение, переданное в access_token, не является допустимым личным маркером доступа Azure Databricks.

Рекомендуемое исправление. Проверьте правильность значения, переданного в access_token, и повторите попытку.

Сообщение `gaierror(8, 'nodename nor servname provided, or not known')`

Проблема. При выполнении кода отображается примерно такое сообщение: Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

Возможная причина. Значение, передаваемое в server_hostname, не является правильным именем узла.

Рекомендуемое исправление. Проверьте правильность значения, переданного в server_hostname, и повторите попытку.

Дополнительные сведения о поиске имени узла сервера см. в статье Получение сведений о подключении для вычислительного ресурса Azure Databricks.

Сообщение `IpAclError`

Проблема: При выполнении кода отображается сообщение Error during request to server: IpAclValidation, когда вы пытаетесь использовать коннектор в записной книжке Azure Databricks.

Возможная причина: возможно, для рабочей области Azure Databricks включен доступ на основе списка разрешенных IP-адресов. При наличии списка разрешенных IP-адресов подключения из кластеров Spark обратно к плоскости управления по умолчанию запрещены.

рекомендуемое исправление. Попросите администратора добавить подсеть уровня вычислений в список разрешенных IP-адресов.

Дополнительные ресурсы

Дополнительные сведения см. в разделе:

Соединитель SQL Databricks для Python на сайте GitHub
Типы данных
Встроенные типы (для bool, bytearray, float, int и str) на веб-сайте Python.
Дата и время (для datetime.date и datatime.datetime) на веб-сайте Python.
Десятичное число (для decimal.Decimal) на веб-сайте Python.
Встроенные константы (для NoneType) на веб-сайте Python.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-16

Поделиться через

Коннектор Databricks SQL для Python

Требования

Начало работы

Вычислительные ресурсы для всех целей

Хранилище SQL

Проверка подлинности

Аутентификация с использованием личного токена доступа Databricks

Аутентификация OAuth между машинами (M2M)

Проверка подлинности токена идентификатора Microsoft Entra

Аутентификация пользователя на машине по OAuth (U2M)

Примеры

Комплект User-Agent

Запрос данных

Теги запросов

Вставка данных

Метаданные запроса

Управление курсорами и подключениями

Управление файлами в томах каталога Unity

Конфигурировать журнал

Тестирование

Справочник по API

Модуль

Метод соединения

Connection класс

Методы

Cursor класс

Атрибуты

Методы

Row класс

Методы

Преобразование типов

Сбор данных телеметрии

Устранение неполадок

Сообщение tokenAuthWrapperInvalidAccessToken: Invalid access token

Сообщение gaierror(8, 'nodename nor servname provided, or not known')

Сообщение IpAclError

Дополнительные ресурсы

Обратная связь

Дополнительные ресурсы

`Connection` класс

`Cursor` класс

`Row` класс

Сообщение `tokenAuthWrapperInvalidAccessToken: Invalid access token`

Сообщение `gaierror(8, 'nodename nor servname provided, or not known')`

Сообщение `IpAclError`