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

Внимание

Эта функция доступна в общедоступной предварительной версии.

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

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

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

Требования

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

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

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

Чтобы создать UDF в 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 UDF для каталога Unity используют операторы, выделенные двойными знаками доллара ($$). Необходимо указать сопоставление типов данных. В следующем примере регистрируется пользовательская функция (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.

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

Внимание

Эта функция доступна в общедоступной предварительной версии.

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

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

  • Пакеты PyPI
  • Файлы, хранящиеся в томах каталога Unity Пользователь, вызывающий UDF, должен иметь READ VOLUME разрешения на исходный том.
  • Файлы, доступные на общедоступных URL-адресах Правила безопасности сети рабочей области должны разрешать доступ к общедоступным URL-адресам.

Примечание.

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

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

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

  • Бессерверные записные книжки и задания
  • Все целевые вычисления с помощью Databricks Runtime версии 16.2 и более поздних версий
  • Pro или бессерверное хранилище SQL

Используйте раздел 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 = 'None'
)
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.
В настоящее время поддерживается только значение None.		 STRING environment_version = 'None'

Использовать функции, определяемые пользователем (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.0 и более поздней версии. В более ранних версиях все пользовательские функции определения 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 в определение функции, если он создает те же выходные данные для одних и того же входных данных. Это позволяет оптимизировать запросы для повышения производительности.

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

СмCREATE FUNCTION (SQL и Python)

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

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

См. статью "Создание средств агента ИИ" с помощью функций каталога 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 |
+---+------------+------------------------+------------------------+

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

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

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

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)
$$;

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

В Databricks Runtime 18.0 и более поздних версиях при передаче значений в Python UDF значения остаются в UTC, но метаданные часового пояса (атрибут TIMESTAMP) не включаются в объект tzinfo.

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

Например, следующий запрос:

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

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

Ранее выдали эти выходные данные в версиях Databricks Runtime до 18.0:

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

В Databricks Runtime 18.0 и более поздних версиях теперь он создает следующие выходные данные:

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

Если ваша пользовательская функция (UDF) зависит от сведений о часовом поясе, необходимо явно восстановить эти сведения.

from datetime import timezone

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

Ограничения

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