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

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

  • Статья

Внимание

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

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

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

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

Требования

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

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

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

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

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

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

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

Python UDF для каталога Unity используют операторы, выделенные двойными знаками доллара ($$). Кроме того, необходимо указать сопоставление типов данных. В следующем примере регистрируется UDF, вычисляющий индекс массы тела:

CREATE 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 каталога 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 рекомендует создать специальный каталог и схему с соответствующими элементами управления доступом.

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

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

Определяемые пользователем функции для доступа к внешним 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()
   # Assuming 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
AS $$
parts = email.split('@')
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 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 |
+---+------------+------------------------+------------------------+

Ограничения

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