Funciones definidas por el usuario (UDF) de SQL y Python en Unity Catalog

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 UDFs de Python registradas como funciones en el catálogo de Unity difieren en cuanto al ámbito y la compatibilidad respecto a las UDFs de PySpark que están restringidas a un cuaderno o SparkSession. Consulte Python funciones escalares definidas por el usuario (UDF).

Para registrar UDF escritas en Scala o Java en el catálogo de Unity, consulte Scala y Java funciones definidas por el usuario (UDF) en el catálogo de Unity.

Para ver qué cargas de trabajo y tablas hacen referencia a una UDF en el Catálogo de Unity antes de modificarla, consulta Ver linaje UDF.

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

Requisitos

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

• Para usar código de Python en UDFs registradas en el Catálogo de Unity, debe usar un almacén de datos SQL sin servidor o profesional, o un clúster que ejecute Databricks Runtime 13.3 LTS o superior.
• Si una vista incluye una UDF de Python del catálogo de Unity, se produce un error en los almacenes de SQL clásicos.
• La compatibilidad de instancias ARM con las UDF de Scala en clústeres habilitados para Unity Catalog está disponible en Databricks Runtime 15.2 y versiones posteriores.

Los UDFs de Python del Catálogo Scalar y Batch de Unity están generalmente disponibles en todos los tipos de cómputo soportados.

Requisitos de características de Python UDF

Los requisitos varían según la característica. Databricks Runtime 19 y la versión 6 del entorno no son requisitos generales para los UDF de Python del Unity Catalog.

Para los UDF de sesión de PySpark en cuadernos o tareas sin servidor, los requisitos del entorno hacen referencia al entorno de la sesión. Para las UDF de Python definidas en SQL, se hace referencia a environment_version en la cláusula ENVIRONMENT de cada función. Cambiar el entorno de sesión no cambia el entorno de una función existente del Catálogo de Unity. Por ejemplo, una sesión que utiliza la versión 6 del entorno puede llamar a una función del Catálogo Unity definida con la versión 5 del entorno.

Las UDF existentes y las características que estaban disponibles durante la versión preliminar pública siguen funcionando en las versiones anteriores aplicables del entorno de ejecución.

La versión del entorno también determina si los llamantes necesitan acceso directo a las dependencias almacenadas en un volumen del Catálogo de Unity. Consulte Permisos para dependencias en volúmenes del Catálogo de Unity.

Versiones del entorno en computación clásica

En la computación clásica, establecer environment_version un valor distinto a 'None' requiere Databricks en tiempo de ejecución 18.2 o superior. En Databricks Runtime 16.2 a 18.1, configúralo environment_version = 'None' siempre que uses la ENVIRONMENT cláusula. El valor 'None' utiliza el entorno Python por defecto.

En Databricks Runtime 18.2 o superior, para un comportamiento predecible, Azure Databricks recomienda establecer explícitamente un fijo environment_version en cada definición de Python UDF del Unity Catalog. Elige una versión que cumpla con los requisitos de funcionalidad de la UDF y siga estas recomendaciones de compatibilidad:

Creación de UDF de SQL y Python en Unity Catalog

Para crear una UDF de SQL o de Python en Unity Catalog, los usuarios necesitan los permisos 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.

Para crear y registrar una UDF en un esquema de catálogo de Unity, el nombre de la función debe seguir el formato catalog.schema.function_name. Como alternativa, puede seleccionar el catálogo y el esquema correctos en el Editor de SQL. En este caso, el nombre de la función no debe llevar catalog.schema antepuesto:

En el ejemplo siguiente se registra una nueva función al esquema my_schema del catálogo 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);

Las UDF de Python para Unity Catalog utilizan instrucciones precedidas por dos signos de dólar ($$). Debe especificar un mapeo de tipos de datos. En el ejemplo siguiente se registra una UDF que calcula el índice de masa corporal:

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

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;

Consulte Ejemplos de filtros de fila y Ejemplos de máscara de columna para obtener más ejemplos de UDF.

Utiliza un manejador con nombre en un UDF escalar de Python

En computación clásica, los manejadores nombrados requieren Databricks en tiempo de ejecución 18.1 o superior. En el procesamiento sin servidor y en los almacenes SQL Pro y serverless, establece explícitamente el environment_version de la UDF en 6 o superior. El siguiente ejemplo utiliza la versión 6 del entorno. En el cálculo clásico que ejecuta Databricks Runtime 18.1, omite la ENVIRONMENT cláusula. En versiones de ejecución posteriores, sigue las recomendaciones de compatibilidad si incluyes la cláusula.

Usa la HANDLER cláusula para nombrar una función de Python en el cuerpo de la UDF como punto de entrada. El manejador nombrado acepta los argumentos UDF y devuelve un valor que coincide con el tipo de retorno declarado. El código externo al handler se ejecuta cuando cada entorno Python inicializa la UDF, antes de que el handler procese las entradas. Utiliza este código para inicializaciones únicas que pueden reutilizarse entre llamadas al manejador.

El siguiente ejemplo inicializa greeting_prefix antes de definir greet_handler, la función que gestiona las entradas 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}!"
$$;

Usar secretos en un UDF de Python

Las UDF de Python escalares y por lotes de Unity Catalog pueden acceder a los secretos declarados en la cláusula SECRETS. La definición de UDF debe establecer environment_version explícitamente como 6 o superior. Un secreto de Unity Catalog utiliza un nombre de tres partes (catalog.schema.secret) y es distinto de un secreto de Azure Databricks a nivel de espacio de trabajo. Para la compatibilidad de proceso, los permisos y la excepción de máscara de columna para proceso dedicado, consulte los requisitos y permisos de UDF.

Para acceder a un secreto de una UDF:

1. Añadir el nombre en tres partes del secreto a la SECRETS cláusula en la definición de la UDF. Una UDF solo puede recuperar los secretos declarados en esta cláusula.
2. En el cuerpo de la UDF, llama databricks.secrets.get() con el catálogo, el esquema y el nombre secreto.

El siguiente ejemplo de UDF escalar utiliza un secreto de Unity Catalog como clave de firma para un código de autenticación de mensajes basado en hash (HMAC). Usa la misma SECRETS cláusula con PARAMETER STYLE PANDAS para acceder a secretos declarados desde un manejador UDF por lotes.

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

Extensión de las UDF mediante dependencias personalizadas

Puede ampliar las funcionalidades de Unity Catalog Python UDF más allá del entorno de Databricks Runtime mediante la definición de dependencias personalizadas para bibliotecas externas.

Requisitos

Las dependencias personalizadas para las UDF del catálogo de Unity se admiten en los siguientes tipos de proceso:

• Cuadernos y trabajos sin servidor
• Cómputo clásico de uso general con Databricks Runtime, versión 16.2 y superiores
• Almacenamiento SQL pro o sin servidor

Orígenes de dependencia

Instale las dependencias desde las fuentes siguientes:

• Paquetes pyPI
• Archivos almacenados en volúmenes del Catálogo UnityConsulte Permisos para dependencias en volúmenes del Catálogo Unity.
• Archivos disponibles en direcciones URL públicas Las reglas de seguridad de red del área de trabajo deben permitir el acceso a direcciones URL públicas. Vea Requisitos.

Permisos para dependencias en volúmenes del Catálogo de Unity

El creador de la función debe tener READ VOLUME en un volumen de origen para añadir una dependencia entre ese volumen y una UDF.

Para una UDF cuya definición establece explícitamente environment_version en 6 o superior, quienes la invocan necesitan EXECUTE en la UDF, pero no necesitan READ VOLUME en el volumen fuente. Si la definición UDF omite environment_version, lo establece en None, o lo establece en una versión anterior, los llamantes también deben tener READ VOLUME sobre el volumen fuente.

Definición de dependencias

Use la ENVIRONMENT sección de la definición de UDF para especificar las dependencias:

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

La ENVIRONMENT sección contiene los siguientes campos:

Uso de 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

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 Unity Catalog

Los controles de acceso aplicados al catálogo, el esquema o la base de datos donde se registra la UDF administran sus permisos. Consulte Administración de privilegios en el 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 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`;

Aislamiento del entorno

Las UDF de Python del catálogo de Unity con el mismo propietario y sesión pueden compartir un entorno de aislamiento de forma predeterminada. Esto mejora el rendimiento y reduce el uso de memoria al reducir el número de entornos independientes que se deben iniciar.

Aislamiento estricto

Para comprobar que una UDF siempre se ejecuta en su propio entorno totalmente aislado, agregue la STRICT ISOLATION cláusula de característica.

La mayoría de las UDF no necesitan aislamiento estricto. Las UDF de procesamiento de datos estándar se benefician del entorno de aislamiento compartido predeterminado y se ejecutan más rápido con un menor consumo de memoria.

Añade la cláusula de característica STRICT ISOLATION a las UDF que:

• Ejecute la entrada como código mediante eval(), exec()o funciones similares.
• Escribir archivos en el sistema de archivos local.
• Modifique las variables globales o el estado del sistema.
• Acceso o modificación de variables de entorno.

En el código siguiente se muestra un ejemplo de una UDF que se debe ejecutar mediante STRICT ISOLATION. Esta UDF ejecuta código arbitrario Python, por lo que podría modificar el estado del sistema, acceder a variables de entorno o escribir en el sistema de archivos local. El uso de la STRICT ISOLATION cláusula ayuda a evitar la interferencia o las fugas de datos en las 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()
$$

Establecer DETERMINISTIC si la función genera resultados coherentes

Agregue DETERMINISTIC a la definición de función si genera las mismas salidas para las mismas entradas. Esto permite que las optimizaciones de consultas mejoren el rendimiento.

De forma predeterminada, Azure Databricks trata el catálogo de Batch Unity Python UDF como no determinista a menos que declare explícitamente lo contrario. Entre los ejemplos de funciones no deterministas se incluyen la generación de valores aleatorios, el acceso a las horas o fechas actuales, o la realización de llamadas API externas.

Consulte CREATE FUNCTION (SQL, Python, Scala y Java)

UDF para herramientas de agente

Los agentes de IA pueden usar UDF del catálogo de Unity como herramientas para realizar tareas y ejecutar lógica personalizada.

Consulte Creación de herramientas de agente mediante funciones del catálogo de Unity.

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.

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

$$;

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

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

procedimientos recomendados

Para que las UDF sean accesibles para todos los usuarios, Databricks recomienda crear un catálogo y un esquema dedicados con los controles de acceso adecuados.

Para las UDF específicas de un equipo, utiliza un esquema dedicado dentro del catálogo del equipo para su almacenamiento y administración.

Databricks recomienda incluir la siguiente información en la cadena de documentación del UDF:

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

En el ejemplo siguiente se muestra una UDF que sigue 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
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)
$$;

Comportamiento de la zona horaria de marca temporal para entradas fila a fila

Un valor de entrada TIMESTAMP llega a una UDF de Python que procesa una fila cada vez como un valor datetime sin información de zona horaria en UTC. En los entornos de procesamiento clásicos, este comportamiento requiere Databricks Runtime 18.1 o una versión posterior. En el procesamiento sin servidor y en los almacenes SQL Pro y serverless, establece explícitamente el environment_version de la UDF en 6 o superior. El datetime objeto no incluye metadatos de zonas horarias en su tzinfo atributo.

Los UDFs de Python del Catálogo Batch de Unity reciben entradas de marca de tiempo en pandas.Series los objetos y no utilizan este datetime mapeo.

Este cambio alinea las UDF de Python del catálogo de Unity con UDF de Python optimizadas para flechas en Apache Spark.

Por ejemplo, la siguiente consulta establece explícitamente la versión 6 del entorno y la zona horaria de la sesión a 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');

La ruta de ejecución anterior devuelve un valor con información de zona horaria según la zona horaria de la sesión. Esto se aplica en el cálculo clásico anterior a Databricks Runtime 18.1. También es aplicable al cómputo sin servidor y a los almacenes SQL Pro y sin servidor cuando se omite la cláusula ENVIRONMENT, se establece environment_version = 'None' o se selecciona una versión anterior a la versión 6. Con el huso horario de la sesión configurado en UTC, el camino anterior produce:

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

Con la definición mostrada, la computación serverless y los almacenes SQL Pro y Serverless usan el comportamiento compatible con PySpark. El computo clásico que ejecuta Databricks en tiempo de ejecución 18.1 o superior utiliza el mismo comportamiento cuando ajustas u omites la ENVIRONMENT cláusula:

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

Este cambio puede afectar a los campos de reloj, así como a tzinfo. En el instante 2024-10-23T10:30:00Z, el comportamiento anterior en una sesión America/Los_Angeles produce 2024-10-23 03:30:00-07:00. El nuevo comportamiento produce el valor UTC sin zona horaria 2024-10-23 10:30:00.

Si tu UDF se basa en la información de zonas horarias, restaura el UTC explícitamente:

from datetime import timezone

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

Añadir información de zonas horarias UTC no restaura los campos de reloj locales de sesión anteriores. Si tu lógica necesita esos campos, también convierte el valor consciente al husto horario previsto de la sesión. Por ejemplo:

from zoneinfo import ZoneInfo

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

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.
• Si no especifica un catálogo o esquema, Azure Databricks registra Python UDF en el esquema activo actual.
• Python UDF se ejecutan en un entorno seguro y aislado y no tienen acceso a sistemas de archivos ni a servicios internos.
• Puedes llamar a más de cinco UDF en una consulta en el cómputo clásico que ejecuta Databricks Runtime 18.1 o versiones posteriores. En el cómputo sin servidor y en los almacenes de SQL Pro y sin servidor, cada definición de UDF debe establecer explícitamente environment_version en 6 o un valor superior.