Partilhar via

Funções definidas pelo usuário (UDFs) no Unity Catalog

  • Artigo

Importante

Esta funcionalidade está em Pré-visualização Pública.

As funções definidas pelo usuário (UDFs) no Unity Catalog estendem os recursos do SQL e do Python no Azure Databricks. Eles permitem que funções personalizadas sejam definidas, usadas e compartilhadas e controladas com segurança em ambientes de computação.

UDFs em Python registadas como funções no Unity Catalog diferem no âmbito e suporte em relação a UDFs PySpark com âmbito limitado a um notebook ou SparkSession. Consulte Funções escalares definidas pelo usuário - Python.

Consulte CREATE FUNCTION (SQL e Python) para obter a referência completa da linguagem SQL.

Requisitos

Para usar UDFs no Unity Catalog, os seguintes requisitos devem ser atendidos:

  • Para usar o código Python em UDFs registradas no Unity Catalog, você deve usar um armazém SQL sem servidor ou pro ou um cluster executando o Databricks Runtime 13.3 LTS ou superior.
  • Se uma exibição incluir um UDF Python UC, ela falhará no SQL Classic Warehouses.

Criando UDFs no Unity Catalog

Para criar uma UDF no Unity Catalog, os utilizadores precisam das permissões USAGE e CREATE no schema e da permissão USAGE no catalog. Consulte Unity Catalog para obter mais detalhes.

Para executar um UDF, os usuários precisam da permissão EXECUTE no UDF. Os utilizadores também precisam de permissão de utilização no schema e catalog.

O exemplo a seguir registra uma nova função para o my_schema Unity Catalogschema:

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

UDFs Python para Unity Catalog usam instruções offset com cifrões duplos ($$). Você também precisa especificar um mapeamento de tipo de dados. O exemplo a seguir registra um UDF que calcula o índice de massa 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)
$$;

Agora você pode usar esta função Unity Catalog em suas consultas SQL ou código PySpark:

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

Usando o Unity Catalog UDF no PySpark

from pyspark.sql.functions import expr

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

Atualizar uma UDF com escopo de sessão

Nota

A sintaxe e a semântica para UDFs Python no Unity Catalog diferem das UDFs Python registadas no SparkSession. Consulte funções escalares definidas pelo usuário - Python.

Dada a seguinte UDF baseada em sessão em um bloco de anotações do 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 isso como uma função Unity Catalog, use uma instrução SQL CREATE FUNCTION, como no exemplo a seguir:

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

Compartilhar UDFs no Unity Catalog

As permissões para UDFs são geridas com base nos controles de acesso aplicados ao catalog, schemaou banco de dados where onde o UDF é registrado. Consulte Unity Catalog para obter mais informações.

Use o Azure Databricks SQL ou a interface do usuário do espaço de trabalho do Azure Databricks para conceder permissões a um usuário ou grupo (recomendado).

Permissões na interface do usuário do espaço de trabalho

  1. Encontre o catalog e o schema. Verifiquewhere onde o seu UDF está armazenado e select localize o UDF.
  2. Procure uma opção Permissões nas configurações UDF. Adicione usuários ou grupos e especifique o tipo de acesso que eles devem ter, como EXECUTAR ou GERENCIAR.

permissões na UI de espaço de trabalho

Permissões usando o Azure Databricks SQL

O exemplo a seguir concede a um usuário a permissão EXECUTE em uma função:

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

Para definir permissões de remove, use o comando REVOKE, como no exemplo a seguir:

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

Práticas recomendadas para UDFs

Para UDFs que precisam ser acessíveis a todos os utilizadores, o Databricks recomenda a criação de catalog e schema dedicados com os controles de acesso apropriados.

Para UDFs específicas da equipe, use um schema dedicado dentro do catalog da equipe para armazenamento e gerenciamento.

O Azure Databricks recomenda que você inclua as seguintes informações no docstring da UDF:

  • O número da versão atual
  • Um changelog para controlar modificações entre versões
  • A finalidade da UDF, o parameterse o valor de retorno
  • Um exemplo de como usar o UDF

Aqui está um exemplo de uma UDF seguindo as práticas recomendadas:

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

UDFs para acessar APIs externas

Você pode usar UDFs para acessar APIs externas do SQL. O exemplo a seguir usa a biblioteca Python requests para fazer uma solicitação HTTP.

Nota

As UDFs Python permitem o tráfego de rede TCP/UDP nas portas 80, 443 e 53 usando computação sem servidor ou computação configurada com modo de acesso compartilhado.

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

$$;

UDFs para segurança e conformidade

Use UDFs Python para implementar tokenização personalizada, mascaramento de dados, edição de dados ou mecanismos de criptografia.

O exemplo a seguir mascara a identidade de um endereço de e-mail enquanto mantém o comprimento e o domínio:

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

O exemplo a seguir aplica essa UDF em uma definição de exibição 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 |
+---+------------+------------------------+------------------------+

Limitações

  • Você pode definir qualquer número de funções Python dentro de um Python UDF, mas todas devem retornar um valor escalar.
  • As funções Python devem manipular values NULL de forma independente, e todos os mapeamentos de tipo devem seguir os mapeamentos de linguagem SQL do Azure Databricks.
  • Você pode importar bibliotecas Python padrão incluídas pelo Azure Databricks, mas não pode incluir bibliotecas personalizadas ou dependências externas.
  • Se nenhum catalog ou schema for especificado, as UDFs Python serão registradas na instância ativa atual de schema.
  • As UDFs Python são executadas em um ambiente seguro e isolado e não têm acesso a sistemas de arquivos ou serviços internos.