Compartir vía

Funciones definidas por el usuario (UDF) en el catálogo de Unity

  • Artículo

Importante

Esta característica está en versión preliminar pública.

Las funciones definidas por el usuario (UDF) en el Catálogo de Unity amplían las funcionalidades de SQL y Python en Azure Databricks. Permiten definir, usar y compartir de forma segura funciones personalizadas en entornos informáticos.

Las UDF de Python registradas como funciones en el catálogo de Unity difieren en el ámbito y la compatibilidad de las UDF de PySpark con ámbito en un cuaderno o SparkSession. Consulte Función escalar definida por el usuario: Python.

Consulte CREATE FUNCTION (SQL y Python) para obtener una referencia completa del lenguaje SQL.

Requisitos

Para usar UDF en el catálogo de Unity, se deben cumplir los siguientes requisitos:

  • Para usar código de Python en UDF registrados en Unity Catalog, debe usar un almacenamiento SQL sin servidor o pro o un clúster que ejecute Databricks Runtime 13.3 LTS o superior.
  • Si una vista incluye una UDF de Python de UC, se producirá un error en almacenes clásicos de SQL.

Creación de UDF en el catálogo de Unity

Para crear una UDF en el catálogo de Unity, los usuarios necesitan el permiso USAGE y CREATE en el esquema y el permiso USAGE en el catálogo. Consulte Catálogo de Unity para obtener más detalles.

Para ejecutar una UDF, los usuarios necesitan el permiso EXECUTE en la UDF. Los usuarios también necesitan el permiso USAGE en el esquema y el catálogo.

En el ejemplo siguiente se registra una nueva función en el esquema de my_schema catálogo de Unity:

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

Las UDF de Python para el catálogo de Unity usan instrucciones de desplazamiento por signos de dólar doble ($$). También debe especificar una asignación de tipos de datos. En el ejemplo siguiente se registra una UDF que calcula el índice de masa corporal:

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

Ahora puede usar esta función de Catálogo de Unity en las consultas SQL o en el código pySpark:

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

Uso de la UDF del catálogo de Unity en PySpark

from pyspark.sql.functions import expr

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

Actualización de una UDF con ámbito de sesión

Nota:

La sintaxis y la semántica de las UDF de Python en el catálogo de Unity difieren de las UDF de Python registradas en SparkSession. Consulte funciones escalares definidas por el usuario: Python.

Dada la siguiente UDF basada en sesión en un cuaderno de 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()

Para registrar esto como una función de catálogo de Unity, use una instrucción SQL CREATE FUNCTION , como en el ejemplo siguiente:

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

Uso compartido de UDF en el catálogo de Unity

Los permisos para las UDF se administran en función de los controles de acceso aplicados al catálogo, el esquema o la base de datos donde se registra la UDF. Consulte Catálogo de Unity para obtener más información.

Use azure Databricks SQL o la interfaz de usuario del área de trabajo de Azure Databricks para conceder permisos a un usuario o grupo (recomendado).

Permisos en la interfaz de usuario del área de trabajo

  1. Busque el catálogo y el esquema donde se almacena la UDF y seleccione la UDF.
  2. Busque una opción Permisos en la configuración de UDF. Agregue usuarios o grupos y especifique el tipo de acceso que deben tener, como EXECUTE o MANAGE.

! [Permisos en la interfaz de usuario del área de trabajo](.. /_static/images/udf/high res udf permission.gif)

Permisos mediante Azure Databricks SQL

En el ejemplo siguiente se concede a un usuario el permiso EXECUTE en una función:

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

Para quitar permisos, use el REVOKE comando como en el ejemplo siguiente:

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

Procedimientos recomendados para UDF

Para las UDF a las que es necesario acceder a todos los usuarios, Databricks recomienda crear un catálogo y un esquema dedicados con los controles de acceso adecuados.

En el caso de las UDF específicas del equipo, use un esquema dedicado dentro del catálogo del equipo para el almacenamiento y la administración.

Azure Databricks recomienda incluir la siguiente información en la cadena de documentos de la UDF:

  • Número de versión actual
  • Un registro de cambios para realizar un seguimiento de las modificaciones entre versiones
  • Propósito, parámetros y valor devuelto de UDF
  • Ejemplo de cómo usar la UDF

Este es un ejemplo de una función definida por el usuario siguiendo los procedimientos recomendados:

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

UDF para acceder a las API externas

Puede usar UDF para acceder a las API externas desde SQL. En el ejemplo siguiente se usa la biblioteca de Python requests para realizar una solicitud HTTP.

Nota:

Las UDF de Python permiten el tráfico de red TCP/UDP a través de los puertos 80, 443 y 53 mediante proceso sin servidor o proceso configurado con el modo de acceso compartido.

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

$$;

UDF para seguridad y cumplimiento

Use UDF de Python para implementar la tokenización personalizada, el enmascaramiento de datos, la redacción de datos o los mecanismos de cifrado.

En el ejemplo siguiente se enmascara la identidad de una dirección de correo electrónico mientras se mantiene la longitud y el dominio:

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}"
$$

En el ejemplo siguiente se aplica esta UDF en una definición de vista dinámica:

-- 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 |
+---+------------+------------------------+------------------------+

Limitaciones

  • Puede definir cualquier número de funciones de Python dentro de una UDF de Python, pero todo debe devolver un valor escalar.
  • Las funciones de Python deben controlar los valores NULL de forma independiente y todas las asignaciones de tipos deben seguir las asignaciones de lenguaje SQL de Azure Databricks.
  • Puede importar bibliotecas estándar de Python incluidas en Azure Databricks, pero no puede incluir bibliotecas personalizadas ni dependencias externas.
  • Si no se especificase ningún catálogo o esquema, las UDF de Python se registrarán en el esquema activo actual.
  • Las UDF de Python se ejecutan en un entorno seguro y aislado y no tienen acceso a sistemas de archivos ni a servicios internos.