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


Соединитель Databricks SQL для Python

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

Примечание.

Соединитель SQL Databricks для Python также включает диалект SQLAlchemy для Azure Databricks. См. статью Об использовании SQLAlchemy с Azure Databricks.

Требования

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

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

  • Установите соединитель SQL Databricks для Python на компьютере разработки, выполнив или python -m pip install databricks-sql-connector.pip install databricks-sql-connector

  • Соберите следующие сведения о кластере или хранилище SQL, которое вы хотите использовать:

    Кластер

    Хранилище SQL

    • Имя узла сервера хранилища SQL. Его можно получить из значения Имя узла сервера на вкладке Сведения о подключении для хранилища SQL.
    • Путь HTTP хранилища SQL. Его можно получить из значения Путь HTTP на вкладке Сведения о подключении для хранилища SQL.

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

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

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

Проверка подлинности маркера личного доступа Databricks

Чтобы использовать соединитель SQL Databricks для Python с проверкой подлинности маркера личного доступа Azure Databricks, необходимо сначала создать личный маркер доступа Azure Databricks, как показано ниже.

  1. В рабочей области Azure Databricks щелкните имя пользователя Azure Databricks в верхней строке и выберите "Параметры " в раскрывающемся списке.
  2. Щелкните "Разработчик".
  3. Рядом с маркерами доступа нажмите кнопку "Управление".
  4. Щелкните Generate new token (Создание нового маркера).
  5. (Необязательно) Введите комментарий, который поможет определить этот маркер в будущем и изменить время существования маркера по умолчанию в течение 90 дней. Чтобы создать маркер без времени существования (не рекомендуется), оставьте поле время существования (дни) пустым (пустым).
  6. Щелкните Создать.
  7. Скопируйте отображаемый маркер в безопасное расположение и нажмите кнопку "Готово".

Примечание.

Не забудьте сохранить скопированный маркер в безопасном расположении. Не делитесь скопированным маркером с другими пользователями. Если вы потеряете скопированный маркер, вы не сможете повторно создать тот же маркер. Вместо этого необходимо повторить эту процедуру, чтобы создать новый маркер. Если вы потеряете скопированный маркер или считаете, что маркер скомпрометирован, 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:
# ...

Проверка подлинности на компьютере (M2M) OAuth

Соединитель 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, необходимо выполнить следующие действия.

  1. Создайте субъект-службу Azure Databricks в рабочей области Azure Databricks и создайте секрет OAuth для этого субъекта-службы.

    Чтобы создать субъект-службу и секрет OAuth, ознакомьтесь с проверкой подлинности доступа к Azure Databricks с помощью субъекта-службы с помощью OAuth (OAuth M2M). Запишите значение UUID или идентификатора приложения субъекта-службы и значение секрета для секрета OAuth субъекта-службы.

  2. Предоставьте субъекту-службе доступ к кластеру или хранилищу.

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

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

  • 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, необходимо предоставить соединитель SQL Databricks для Python с маркером идентификатора Microsoft Entra ID. Чтобы создать маркер доступа идентификатора Microsoft Entra, сделайте следующее:

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

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

  • Задайте 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:
# ...

Примеры

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

Примечание.

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

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

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

Вы можете использовать другие подходы для получения значений этих переменных подключения. Переменные среды — лишь один из них.

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

В следующем примере кода показано, как вызвать соединитель 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)

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

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

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)

Что касается больших объемов данных, сначала необходимо передать данные в облачное хранилище, а затем выполнить команду 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 и хранилищах 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

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

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

Настройка журнала

Соединитель Databricks SQL использует стандартный модуль ведения журнала 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(f"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 таблицы, макетирование не является абсолютно обязательным в этом примере. Однако макетирование позволяет быстро выполнять тесты, не ожидая фактического подключения к рабочей области. Кроме того, макетирование позволяет выполнять имитированные тесты несколько раз для функций, которые могут изменить состояние таблицы, например INSERT INTO, UPDATEи DELETE FROM.

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

Пакет

databricks-sql-connector

Использование: pip install databricks-sql-connector

См. также databricks-sql-connector в индексе пакета Python (PyPI).

Модуль

databricks.sql

Использование: from databricks import sql

Классы

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

Классы
Connection

Сеанс для вычислительного ресурса Azure Databricks.
Cursor

Механизм обхода записей данных.
Row

Строка данных в результатах SQL-запроса.

Класс Connection

Чтобы создать Connection объект, вызовите databricks.sql.connect метод со следующими параметрами:

Параметры
server_hostname

Тип: str

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

Этот параметр является обязательным.

Пример: adb-1234567890123456.7.azuredatabricks.net
http_path

Тип: str

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

Этот параметр является обязательным.

Пример:
sql/protocolv1/o/1234567890123456/1234-567890-test123 для кластера.
/sql/1.0/warehouses/a1b234c567d8e9fa для хранилища SQL.
access_token, auth_type

Тип: 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.

Это необязательный параметр.

Начиная с версии 2.0
catalog

Тип: str

Исходный каталог для соединения. По умолчанию задано значение None. В этом случае используется каталог по умолчанию (обычно это hive_metastore).

Это необязательный параметр.

Начиная с версии 2.0
schema

Тип: str

Начальная схема для соединения. По умолчанию задано значение None. В этом случае используется схема по умолчанию default.

Это необязательный параметр.

Начиная с версии 2.0
use_cloud_fetch

Тип: bool

True чтобы отправлять запросы на получение непосредственно в хранилище объектов облака, чтобы скачать блоки данных. False (по умолчанию) для отправки запросов непосредственно в Azure Databricks.

Если use_cloud_fetch задано True значение, но сетевой доступ заблокирован, запросы на получение завершаются ошибкой.

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

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

Методы
close

Закрывает соединение с базой данных и освобождает все связанные ресурсы на сервере. При любых дополнительных вызовах этого соединения создается Error.

Без параметров.

Нет возвращаемого значения.
cursor

Возвращает новый Cursor объект, который включает обход записей в базе данных.

Без параметров.

Класс Cursor

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

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

Атрибуты
arraysize

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

Доступ для чтения и записи.
description

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

- name: имя столбца;
- type_code: строка, представляющая тип столбца. Например, целочисленный столбец будет иметь код типа int.

Оставшиеся пять элементов каждого объекта tuple с семью элементами не реализуются, и их значения не определяются. Обычно они возвращаются как 4
None значения, за которым следует одно True значение.

Доступ только для чтения.

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

Методы
cancel

Прерывает выполнение любого запроса к базе данных или команды, запущенной курсором. Чтобы освободить связанные ресурсы на сервере, вызовите
close метод после вызова cancel метода.

Без параметров.

Нет возвращаемого значения.
close

Закрывает курсор и освобождает связанные ресурсы на сервере. Закрытие уже закрытого курсора может вызвать ошибку.

Без параметров.

Нет возвращаемого значения.
execute

Подготавливает, а затем выполняет запрос к базе данных или соответствующую команду.

Нет возвращаемого значения.

Параметры:

operation

Тип: str

Запрос или команда для подготовки и последующего выполнения.

Этот параметр является обязательным.

Пример без параметра parameters:


cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'
)

Пример с параметром parameters:


cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',
{ 'pickup_zip': '10019' }
)

parameters

Тип: словарь

Последовательность параметров для использования с параметром operation.

Это необязательный параметр. Значение по умолчанию — None.
executemany

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

Нет возвращаемого значения.

Параметры:

operation

Тип: str

Запрос или команда для подготовки и последующего выполнения.

Этот параметр является обязательным.

seq_of_parameters

Тип: list для dict.

Последовательность множества наборов значений параметров для использования с
параметром operation.

Этот параметр является обязательным.
catalogs

Выполнение запроса метаданных о каталогах. Фактические результаты следует извлекать с помощью fetchmany или fetchall.

К важным полям в результирующем наборе относятся:

— имя поля: TABLE_CAT. Введите str. Имя каталога.

Без параметров.

Нет возвращаемого значения.

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

Выполнение запроса метаданных о схемах. Фактические результаты следует извлекать с помощью fetchmany или fetchall.

К важным полям в результирующем наборе относятся:

— имя поля: TABLE_SCHEM. Введите str. Имя схемы.
— имя поля: TABLE_CATALOG. Введите str. Каталог, к которому относится схема.

Нет возвращаемого значения.

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

Параметры:

catalog_name

Тип: str

Имя каталога, о котором извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

schema_name

Тип: str

Имя схемы, о которой извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.
tables

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

К важным полям в результирующем наборе относятся:

— имя поля: TABLE_CAT. Введите str. Каталог, к которому относится таблица.
— имя поля: TABLE_SCHEM. Введите str. Схема, к которой относится таблица.
— имя поля: TABLE_NAME. Введите str. Название таблицы.
— имя поля: TABLE_TYPE. Введите str. Тип отношения, например VIEW или TABLE (относится к Databricks Runtime 10.4 LTS и выше, а также к Databricks SQL; предыдущие версии Databricks Runtime возвращают пустую строку).

Нет возвращаемого значения.

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

Параметры

catalog_name

Тип: str

Имя каталога, о котором извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

schema_name

Тип: str

Имя схемы, о которой извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

table_name

Тип: str

Имя таблицы, о которой извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

table_types

Тип: List[str]

Список типов таблиц для сопоставления, например TABLE или VIEW.

Это необязательный параметр.
columns

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

К важным полям в результирующем наборе относятся:

— имя поля: TABLE_CAT. Введите str. Каталог, к которому относится столбец.
— имя поля: TABLE_SCHEM. Введите str. Схема, к которой относится столбец.
— имя поля: TABLE_NAME. Введите str. Имя таблицы, к которой относится столбец.
— имя поля: COLUMN_NAME. Введите str. Имя столбца.

Нет возвращаемого значения.

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

Параметры:

catalog_name

Тип: str

Имя каталога, о котором извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

schema_name

Тип: str

Имя схемы, о которой извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

table_name

Тип: str

Имя таблицы, о которой извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.

column_name

Тип: str

Имя столбца, о котором извлекаются сведения. Символ % интерпретируется как подстановочный знак.

Это необязательный параметр.
fetchall

Возвращает все (или все оставшиеся) строки запроса.

Без параметров.

Возвращает все (или все оставшиеся) строки запроса в виде Python list
Row Объектов.

Вызывает, если предыдущий Error вызов execute метода не вернул никаких данных или вызов еще не execute был выполнен.
fetchmany

Возвращает следующие строки запроса.

Возвращает до size (или arraysize атрибута, если size не указано) следующих строк запроса в виде Python list Row объектов.

Если строк для извлечения меньше, чем определено size, будут возвращены все оставшиеся строки.

Вызывает, если предыдущий Error вызов execute метода не вернул никаких данных или вызов еще не execute был выполнен.

Параметры:

size

Тип: int

Число следующих строк для получения.

Это необязательный параметр. Если значение не указано, используется значение атрибута arraysize.

Пример: cursor.fetchmany(10)
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 атрибута, если size не указано) следующих строк запроса в качестве Python PyArrow
Объект Table.

Вызывает, если предыдущий Error вызов execute метода не вернул никаких данных или вызов еще не execute был выполнен.

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

Параметры:

size

Тип: int

Число следующих строк для получения.

Это необязательный параметр. Если значение не указано, используется значение атрибута arraysize.

Пример: cursor.fetchmany_arrow(10)

Класс Row

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

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

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

| asDict

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

Без параметров.

Возвращает dict полей. |

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

В следующей таблице типы данных 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

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

Сообщение 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.

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

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

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

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