Пользовательские функции SQL и Python (UDF) в Unity Catalog

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

Зарегистрированные в Unity Catalog функции Python (UDFs) отличаются по области и поддержке от функций PySpark UDFs, привязанных к записной книжке или сеансу SparkSession. См. определяемые пользователем скалярные функции Python (UDF).

Чтобы зарегистрировать пользовательские функции (UDF), написанные на Scala или Java, в Unity Catalog, см. статью Пользовательские функции (UDF) на Scala и Java в Unity Catalog.

Чтобы узнать, какие рабочие нагрузки и таблицы отсылают к UDF в Unity Catalog до его изменения, смотрите раздел «View UDF lineage».

Полное справочное руководство по языку SQL см. в разделе CREATE FUNCTION (SQL, Python, Scala и Java).

Требования

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

  • Чтобы использовать код Python в определяемых пользователем функциях (UDF), зарегистрированных в Unity Catalog, необходимо использовать бессерверное или профессиональное хранилище SQL или кластер под управлением Databricks Runtime 13.3 LTS или более поздней версии.
  • Если представление содержит Python UDF из Unity Catalog, оно завершается сбоем в классических хранилищах SQL.
  • Поддержка экземпляра ARM для кластеров с поддержкой каталога Unity Scala доступна в Databricks Runtime 15.2 и более поздних версиях.

Scalar и Batch Unity Catalog Python UDF обычно доступны для всех поддерживаемых вычислительных типов.

Требования к функциям Python UDF

Требования различаются в зависимости от особенности. Databricks Runtime 19 и окружение версии 6 не являются общими требованиями для Unity Catalog Python UDF.

Для сессионных UDF PySpark на серверных ноутбуках или задачах требования среды относятся к сессионной среде. Для UDF на Python, определяемых с помощью SQL, они ссылаются на environment_version в предложении ENVIRONMENT каждой функции. Изменение среды сессии не меняет окружение существующей функции Unity Catalog. Например, сессия, использующая окружение версии 6, может вызвать функцию Unity Catalog, определённую с версией окружения 5.

Функция Требования
ENVIRONMENT Клаузы и пользовательские зависимости Serverless-ноутбуки и задачи; SQL-хранилища Pro или serverless; Databricks Runtime 16.2 и выше на классических вычислениях. На классических вычислениях с Databricks Runtime 16.2 по 18.1 должна environment_version быть 'None'.
Пакетная обработка пользовательских функций Python в Unity Catalog бессерверные вычисления; SQL-хранилища Pro и бессерверные SQL-хранилища; Databricks Runtime 16.3 и выше в классической среде вычислений
Названный обработчик для скалярного Python UDF Databricks Runtime 18.1 и выше на классических вычислениях. Для бессерверных вычислительных ресурсов, а также для SQL-хранилищ Pro и serverless явно задайте для UDF параметр environment_version как 6 или выше.
Учетные данные сервиса в скалярном Python UDF Databricks Runtime 18.1 и выше на классических вычислениях. Для бессерверных вычислительных ресурсов, а также для SQL-хранилищ Pro и serverless явно задайте для UDF параметр environment_version как 6 или выше. Классические вычисления не требуют версии окружения 6. Для бессерверных хранилищ SQL также включите публичную предварительную версию сетевой функции для изолированных рабочих нагрузок.
Учетные данные службы в Batch Unity Catalog Python UDF Бессерверные вычисления; SQL-хранилища Pro и Serverless; Databricks Runtime 16.3 и выше на классических вычислительных ресурсах. Версия среды 6 не требуется. Для бессерверных хранилищ SQL также включите публичную предварительную версию сетевой функции для изолированных рабочих нагрузок.
Секреты в скалярном или пакетном Unity Catalog Python UDF Явно установите environment_version на 6 или выше; бессерверные вычисления; SQL-хранилища Pro и Serverless; Databricks Runtime 19 или выше со стандартным режимом доступа в классической среде вычислений. Прямой вызов не поддерживается для вычислительных ресурсов с выделенным режимом доступа.
Совместимое TIMESTAMP с PySpark поведение ввода Databricks Runtime 18.1 и выше на классических вычислениях. Для бессерверных вычислительных ресурсов, а также для SQL-хранилищ Pro и serverless явно задайте для UDF параметр environment_version как 6 или выше.
Более пяти вызовов UDF в одном запросе Databricks Runtime 18.1 и выше на классических вычислениях. Для бессерверных вычислений, а также для SQL-хранилищ Pro и Serverless явно задайте для каждой UDF значение environment_version как 6 или выше.

Существующие UDF и функции, доступные в рамках общедоступной предварительной версии, продолжают работать в соответствующих более ранних версиях среды выполнения.

Версия среды также определяет, нужен ли вызывающим прямой доступ к зависимостям, хранящимся в томе Unity Catalog. См. раздел «Разрешения зависимостей в томах каталога Unity».

Версии среды на классических вычислениях

В классических вычислениях environment_version установка значения, отличного от 'None' Databricks Runtime 18.2 или выше. В Databricks Runtime 16.2–18.1 устанавливайте environment_version = 'None' всякий момент, когда вы используете предложение ENVIRONMENT . Значение 'None' использует стандартную среду Python.

В Databricks Runtime 18.2 и выше, для предсказуемого поведения, Azure Databricks рекомендует явно устанавливать фиксированное environment_version значение в каждом определении Python UDF в каталоге Unity. Выберите версию, которая соответствует требованиям функций UDF и следует следующим рекомендациям по совместимости:

Версия Databricks Runtime Максимальная рекомендуемая версия среды
18.2 по 18.x 5
19.x 6

Создание пользовательских функций SQL и Python в Unity Catalog

Чтобы создать UDF SQL или Python в Unity Catalog, пользователям необходимы разрешения USAGE и CREATE для схемы, а также разрешение USAGE для каталога. Дополнительные сведения см. в каталоге Unity .

Чтобы запустить UDF, требуется, чтобы пользователи имели разрешение EXECUTE на UDF. Пользователям также требуется разрешение USAGE на схему и каталог.

Чтобы создать и зарегистрировать UDF в схеме каталога Unity, имя функции должно соответствовать формату catalog.schema.function_name. Кроме того, можно выбрать правильный каталог и схему в редакторе SQL. В этом случае перед именем функции не должно быть catalog.schema:

Создание UDF с предварительно выбранным каталогом и схемой.

В следующем примере регистрируется новая функция в my_schema схеме в каталоге my_catalog :

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight DOUBLE, height DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
SELECT weight / (height * height);

Пользовательские функции Python в Unity Catalog используют операторы, заключённые между двойными знаками доллара ($$). Необходимо указать сопоставление типов данных. В следующем примере регистрируется пользовательская функция (UDF), которая вычисляет индекс массы тела.

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
return weight_kg / (height_m ** 2)
$$;

Теперь эту функцию каталога Unity можно использовать в запросах SQL или коде PySpark:

SELECT person_id, my_catalog.my_schema.calculate_bmi(weight_kg, height_m) AS bmi
FROM person_data;

Примеры фильтров строк и примеры маски столбцов см. в дополнительных примерах UDF.

Используйте именованный обработчик в скалярном Python UDF

В классических вычислениях именованные обработчики требуют Databricks Runtime 18.1 или выше. Для бессерверных вычислительных ресурсов, а также для SQL-хранилищ Pro и serverless явно задайте для UDF параметр environment_version как 6 или выше. В следующем примере используется окружение версии 6. В классических вычислениях с Databricks Runtime 18.1 опустите этот ENVIRONMENT пункт. В более поздних версиях выполнения следуйте рекомендациям по совместимости , если включите этот пункт.

Используйте конструкцию HANDLER, чтобы указать функцию Python в теле UDF в качестве точки входа. Именованный обработчик принимает аргументы UDF и возвращает значение, соответствующее объявленному типу возврата. Код вне обработчика выполняется, когда каждая среда Python инициализирует UDF, до того, как обработчик обрабатывает входные данные. Используйте этот код для одноразовой инициализации, которую можно повторно применять между вызовами обработчиков.

Следующий пример инициализирует greeting_prefix перед определением greet_handler — функции, которая обрабатывает входные данные UDF:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
HANDLER 'greet_handler'
ENVIRONMENT (
  environment_version = '6'
)
AS $$
# Runs once when each Python environment initializes the UDF.
greeting_prefix = "Hello"

def greet_handler(name):
    return f"{greeting_prefix}, {name}!"
$$;

Используйте секреты в Python UDF

Scalar и Batch Unity Catalog Python UDF могут получать доступ к секретам, объявленным в этом SECRETS пункте. В определении UDF значение environment_version должно быть явно установлено на 6 или выше. Секрет Unity Catalog использует трехчастное имя (catalog.schema.secret) и отличается от секрета Azure Databricks на уровне рабочего пространства. Сведения о поддержке вычислений, разрешениях и исключении для маски столбца при использовании выделенных вычислительных ресурсов см. в разделе Требования к UDF и разрешения.

Чтобы получить доступ к секрету в UDF:

  1. Добавьте трёхсоставное имя секрета в предложение SECRETS в определении UDF. UDF может извлекать только секреты, объявленные в этом пункте.
  2. В теле UDF вызовите databricks.secrets.get() с каталогом, схемой и именем секрета.

Следующий скалярный пример UDF использует секрет Unity Catalog в качестве ключа подписи для аутентификационного кода (HMAC) на основе хеша. Используйте ту же конструкцию SECRETS с PARAMETER STYLE PANDAS для доступа к объявленным секретам в обработчике пакетной UDF.

CREATE OR REPLACE FUNCTION main.default.sign_value(value STRING)
RETURNS STRING
LANGUAGE PYTHON
SECRETS (main.default.hmac_key)
ENVIRONMENT (
  environment_version = '6'
)
AS $$
import hashlib
import hmac
from databricks.secrets import get

key = get(catalog="main", schema="default", key="hmac_key")
return hmac.new(key.encode(), value.encode(), hashlib.sha256).hexdigest()
$$;

Предупреждение

Не возвращайте секретные значения из функции UDF. Секретная редакция помогает снизить случайное обнаружение ошибок и журналов, но не мешает коду UDF раскрывать секретный материал в результатах запросов.

Расширение UDF с использованием пользовательских зависимостей

Примечание.

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

Вы можете расширить возможности Python UDF в Unity Catalog за пределами среды Databricks Runtime, определив пользовательские зависимости для внешних библиотек.

Требования

Пользовательские зависимости для определяемых пользователем функций (UDF) каталога Unity поддерживаются на следующих типах вычислительных ресурсов:

  • Бессерверные записные книжки и задания
  • Классические универсальные вычислительные ресурсы с использованием Databricks Runtime версии 16.2 и выше
  • Pro или бессерверное хранилище SQL

Источники зависимостей

Установите зависимости из следующих источников:

Примечание.

Если рабочая область ограничивает бессерверный сетевой доступ, необходимо настроить правила безопасности сети, чтобы разрешить общедоступные URL-адреса. См. «Настройка правил исходящего трафика».

Разрешения для зависимостей в томах Unity Catalog

Создатель функции должен иметь READ VOLUME на исходном томе, чтобы добавить зависимость из этого тома в UDF.

Для UDF, в определении которой явно задано значение environment_version как 6 или выше, вызывающей стороне требуется EXECUTE для UDF, но не требуется READ VOLUME на исходном томе. Если определение UDF не включает environment_version, задаёт его как None или задаёт более раннюю версию, вызывающие компоненты также должны иметь READ VOLUME на исходном томе.

Определение зависимостей

Используйте раздел ENVIRONMENT определения UDF, чтобы указать зависимости:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.mixed_process(data STRING)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  dependencies = '["simplejson==3.19.3", "/Volumes/my_catalog/my_schema/my_volume/packages/custom_package-1.0.0.whl", "https://my-bucket.s3.amazonaws.com/packages/special_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]',
  environment_version = '6'
)
AS $$
import simplejson as json
import custom_package
return json.dumps(custom_package.process(data))
$$;

В разделе ENVIRONMENT содержатся следующие поля:

Поле Описание Тип Пример использования
dependencies Список зависимостей, разделенных запятыми для установки. Каждая запись — это строка, которая соответствует формату файла требований pip . STRING dependencies = '["simplejson==3.19.3", "/Volumes/catalog/schema/volume/packages/my_package-1.0.0.whl"]'
dependencies = '["https://my-bucket.s3.amazonaws.com/packages/my_package-2.0.0.whl?Expires=2043167927&Signature=abcd"]'
environment_version Указывает версию среды для запуска UDF. Это поле требуется всякий раз, когда оговорка ENVIRONMENT присутствует. Версия с фиксированной средой запускает UDF с определенной версией Python и набором предварительно установленных пакетов независимо от версии Python и пакетов в базовой среде Databricks Runtime.
Поддерживаемые значения — версия среды 3 или выше, например '6', или строка 'None'. Значение 'None' выбирает стандартную среду Python. В классических вычислениях установка environment_version на значение, отличное от 'None', требует Databricks Runtime 18.2 или выше. В Databricks Runtime с 16.2 по 18.1 поддерживается только 'None' режим. Если поддерживаются фиксированные версии среды, явно выбирайте одну из них для предсказуемого поведения.
При использовании бессерверных вычислений, а также Pro и бессерверных хранилищ SQL для некоторых функций требуется явно указанная версия среды. Установите environment_version до требуемой или более поздней версии в каждом определении UDF. Опущение всего условия ENVIRONMENT или установка environment_version = 'None' не активируют эти функции. См. требования к функциям Python UDF.
Для совместимости классических вычислительных версий см. раздел «Версии среды на классических вычислениях». Список доступных версий см. в разделе Версии среды.		 STRING environment_version = '6'

Использовать функции, определяемые пользователем (UDF) каталога Unity в PySpark

from pyspark.sql.functions import expr

result = df.withColumn("bmi", expr("my_catalog.my_schema.calculate_bmi(weight_kg, height_m)"))
display(result)

Обновление UDF, относящегося к области сеанса

Примечание.

Синтаксис и семантика для пользовательских функций UDF на Python в каталоге Unity отличаются от пользовательских функций UDF на Python, зарегистрированных в SparkSession. См. определяемые пользователем скалярные функции — Python.

Учитывая следующую сессионную UDF в записной книжке Azure Databricks:

from pyspark.sql.functions import udf
from pyspark.sql.types import StringType

@udf(StringType())
def greet(name):
    return f"Hello, {name}!"

# Using the session-based UDF
result = df.withColumn("greeting", greet("name"))
result.show()

Чтобы зарегистрировать эту функцию в качестве функции каталога Unity, используйте инструкцию SQL CREATE FUNCTION, как показано в следующем примере:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.greet(name STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
return f"Hello, {name}!"
$$

Предоставление общего доступа к определяемым пользователем функциям в каталоге Unity

Элементы управления доступом, применяемые к каталогу, схеме или базе данных, где регистрируется UDF, управляют его разрешениями. Дополнительные сведения см. в разделе "Управление привилегиями" в каталоге Unity .

Используйте SQL Azure Databricks или пользовательский интерфейс рабочей области Azure Databricks, чтобы предоставить разрешения пользователю или группе (рекомендуется).

Разрешения в пользовательском интерфейсе рабочей области

  1. Найдите каталог и схему, в которой хранится UDF, и выберите UDF.
  2. Найдите параметр "Разрешения" в параметрах UDF. Добавьте пользователей или группы и укажите тип доступа, который они должны иметь, например EXECUTE или MANAGE.

Разрешения в пользовательском интерфейсе рабочей области

Разрешения с помощью Azure Databricks SQL

В следующем примере пользователь предоставляет пользователю разрешение EXECUTE на функцию:

GRANT EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi TO `user@example.com`;

Чтобы удалить разрешения, используйте команду REVOKE, как показано в следующем примере:

REVOKE EXECUTE ON FUNCTION my_catalog.my_schema.calculate_bmi FROM `user@example.com`;

Изоляция среды

Примечание.

Для общих изоляционных сред требуется Databricks Runtime 18.1 и выше. В более ранних версиях все пользовательские функции определения Python в Unity Catalog выполняются в строгом режиме изоляции.

Определяемые пользователем UDFS каталога Unity с тем же владельцем и сеансом могут совместно использовать среду изоляции по умолчанию. Это повышает производительность и сокращает использование памяти, уменьшая количество отдельных сред, которые необходимо запустить.

Строгая изоляция

Чтобы убедиться, что UDF всегда выполняется в собственной, полностью изолированной среде, добавьте STRICT ISOLATION предложение характеристик.

Большинству определяемых пользователем функций не требуется строгая изоляция. Стандартные UDF обработки данных используют общую среду изоляции по умолчанию и с меньшим потреблением памяти выполняются быстрее.

Добавьте характеристическую конструкцию в определяемые пользователем функции STRICT ISOLATION, которые:

  • Выполнение входных данных как кода с помощью функций eval(), exec() или аналогичных.
  • Запись файлов в локальную файловую систему.
  • Изменение глобальных переменных или состояния системы.
  • Доступ или изменение переменных среды.

В следующем коде показан пример UDF, который должен выполняться с помощью STRICT ISOLATION. Этот UDF выполняет произвольный Python код, поэтому может изменить состояние системы, получить доступ к переменным среды или записать в локальную файловую систему. Использование условия STRICT ISOLATION помогает предотвратить помехи или утечки данных в пользовательских определенных функциях (UDF).

CREATE OR REPLACE TEMPORARY FUNCTION run_python_snippet(python_code STRING)
RETURNS STRING
LANGUAGE PYTHON
STRICT ISOLATION
AS $$
import sys
from io import StringIO

# Capture standard output and error streams
captured_output = StringIO()
captured_errors = StringIO()
sys.stdout = captured_output
sys.stderr = captured_errors

try:
    # Execute the user-provided Python code in an empty namespace
    exec(python_code, {})
except SyntaxError:
    # Retry with escaped characters decoded (for cases like "\n")
    def decode_code(raw_code):
        return raw_code.encode('utf-8').decode('unicode_escape')
    python_code = decode_code(python_code)
    exec(python_code, {})

# Return everything printed to stdout and stderr
return captured_output.getvalue() + captured_errors.getvalue()
$$

Задайте DETERMINISTIC, если функция выдает последовательные результаты

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

По умолчанию Azure Databricks считает пакетные UDF Python в Unity Catalog недетерминированными, если вы явно не укажете иное. Примеры недетерминированных функций включают создание случайных значений, доступ к текущим времени или датам или вызовы внешних API.

См. CREATE FUNCTION (SQL, Python, Scala и Java)

Пользовательские функции для инструментов агента

ИИ-агенты могут использовать пользовательские функции (UDF) в Unity Catalog в качестве инструментов для выполнения задач и запуска пользовательской логики.

См. статью "Создание средств агента с помощью функций каталога Unity".

Пользовательские определенные функции (UDFs) для доступа к внешним API

Вы можете использовать функции, определяемые пользователем, для доступа к внешним API из SQL. В следующем примере библиотека Python requests используется для выполнения HTTP-запроса.

Примечание.

Пользовательские функции Python разрешают сетевой трафик TCP/UDP через порты 80, 443 и 53 при использовании бессерверных вычислений или вычислений, настроенных в стандартном режиме доступа.

CREATE FUNCTION my_catalog.my_schema.get_food_calories(food_name STRING)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
import requests

api_url = f"https://example-food-api.com/nutrition?food={food_name}"
response = requests.get(api_url)

if response.status_code == 200:
   data = response.json()
   # Assume the API returns a JSON object with a 'calories' field
   calories = data.get('calories', 0)
   return calories
else:
   return None  # API request failed

$$;

Определяемые пользователем функции для обеспечения безопасности и соответствия требованиям

Используйте пользовательские функции Python для реализации кастомной токенизации, маскирования данных, редакции данных или шифрования.

В следующем примере идентификатор адреса электронной почты маскируется при сохранении длины и домена:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.mask_email(email STRING)
RETURNS STRING
LANGUAGE PYTHON
DETERMINISTIC
AS $$
parts = email.split('@', 1)
if len(parts) == 2:
  username, domain = parts
else:
  return None
masked_username = username[0] + '*' * (len(username) - 2) + username[-1]
return f"{masked_username}@{domain}"
$$

В следующем примере применяется этот UDF в определении динамического представления:

-- First, create the view
CREATE OR REPLACE VIEW my_catalog.my_schema.masked_customer_view AS
SELECT
  id,
  name,
  my_catalog.my_schema.mask_email(email) AS masked_email
FROM my_catalog.my_schema.customer_data;

-- Now you can query the view
SELECT * FROM my_catalog.my_schema.masked_customer_view;

+---+------------+------------------------+------------------------+
| id|        name|                   email|           masked_email |
+---+------------+------------------------+------------------------+
|  1|    John Doe|   john.doe@example.com |  j*******e@example.com |
|  2| Alice Smith|alice.smith@company.com |a**********h@company.com|
|  3|   Bob Jones|    bob.jones@email.org |   b********s@email.org |
+---+------------+------------------------+------------------------+

Лучшие практики

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

Для хранения и управления, определяемые командой функции используйте выделенную схему в командном каталоге.

Databricks рекомендует включить в документ UDF следующие сведения:

  • Номер текущей версии
  • Журнал изменений для отслеживания изменений в разных версиях
  • Назначение, параметры и возвращаемое значение UDF
  • Пример использования UDF

В следующем примере показана UDF, которая соответствует лучшим практикам.

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
COMMENT "Calculates Body Mass Index (BMI) from weight and height."
LANGUAGE PYTHON
DETERMINISTIC
AS $$
 """
Parameters:
calculate_bmi (version 1.2):
- weight_kg (float): Weight of the individual in kilograms.
- height_m (float): Height of the individual in meters.

Returns:
- float: The calculated BMI.

Example Usage:

SELECT calculate_bmi(weight, height) AS bmi FROM person_data;

Change Log:
- 1.0: Initial version.
- 1.1: Improved error handling for zero or negative height values.
- 1.2: Optimized calculation for performance.

 Note: BMI is calculated as weight in kilograms divided by the square of height in meters.
 """
if height_m <= 0:
 return None  # Avoid division by zero and ensure height is positive
return weight_kg / (height_m ** 2)
$$;

Поведение метки времени в часовых поясах для входных данных, обрабатываемых построчно

Входное значение поступает в Python UDF, обрабатывающую по одной строке за раз, как значение TIMESTAMPdatetime без часового пояса в UTC. На классических вычислениях это поведение требует Databricks Runtime 18.1 и выше. Для бессерверных вычислительных ресурсов, а также для SQL-хранилищ Pro и serverless явно задайте для UDF параметр environment_version как 6 или выше. datetime Объект не включает метаданные часового пояса в свой tzinfo атрибут.

Пакетные Python UDF в Unity Catalog получают входные значения времени в виде объектов pandas.Series и не используют это сопоставление datetime.

Это изменение согласует Python UDFs в каталоге Unity с оптимизированными с помощью Arrow Python UDFs в Apache Spark.

Например, следующий запрос явно устанавливает среду версии 6 и часовой пояс сессии в UTC:

SET TIME ZONE 'UTC';

CREATE FUNCTION timezone_udf(date TIMESTAMP)
RETURNS STRING
LANGUAGE PYTHON
ENVIRONMENT (
  environment_version = '6'
)
AS $$
return f"{type(date)} {date} {date.tzinfo}"
$$;

SELECT timezone_udf(TIMESTAMP '2024-10-23 10:30:00');

Ранний путь выполнения возвращает значение, учитывающее часовой пояс, в часовом поясе сессии. Это применимо к классическим вычислениям до Databricks Runtime 18.1. Это также относится к бессерверным вычислениям, а также к SQL-хранилищам Pro и Serverless, если вы опускаете предложение ENVIRONMENT, задаёте environment_version = 'None' или выбираете версию ниже 6. Если часовой пояс сессии установлен в UTC, предыдущий путь даёт:

<class 'datetime.datetime'> 2024-10-23 10:30:00+00:00 UTC

Согласно приведённому определению, бессерверные вычислительные ресурсы, а также SQL-хранилища Pro и Serverless используют поведение, совместимое с PySpark. Классические вычисления с Databricks Runtime 18.1 и выше используют то же поведение при корректировке или исключении клаузы ENVIRONMENT :

<class 'datetime.datetime'> 2024-10-23 10:30:00 None

Это изменение может повлиять на поля часов, а также на tzinfo. Для момента 2024-10-23T10:30:00Z, более раннее поведение в America/Los_Angeles сессии даёт 2024-10-23 03:30:00-07:00. Новое поведение возвращает значение UTC без информации о часовом поясе 2024-10-23 10:30:00.

Если ваш UDF зависит от информации о часовом поясе, восстановите UTC явно:

from datetime import timezone

date = date.replace(tzinfo=timezone.utc)

Добавление информации о часовом поясе UTC не восстанавливает поля предыдущих локальных часов сессии. Если вашей логике нужны эти поля, также преобразуйте значение осознанности в предполагаемый часовой пояс сессии. Рассмотрим пример.

from zoneinfo import ZoneInfo

date = date.astimezone(ZoneInfo("America/Los_Angeles"))

Ограничения

  • Вы можете определить любое количество функций Python в UDF Python, но все они должны возвращать скалярное значение.
  • Функции Python должны обрабатывать значения NULL независимо, и все сопоставления типов должны соответствовать сопоставлениям языков SQL Azure Databricks.
  • Если вы не указываете каталог или схему, Azure Databricks регистрирует пользовательские функции Python в текущей активной схеме.
  • Пользовательские функции Python (UDF) выполняются в защищённой, изолированной среде и не имеют доступа к файловым системам или внутренним сервисам.
  • Вы можете вызвать более пяти UDF в запросе на классических вычислениях с Databricks Runtime 18.1 и выше. В бессерверных вычислительных средах, а также в SQL-хранилищах Pro и Serverless каждое определение UDF должно явно задавать environment_version равным 6 или выше.
  • Last updated on