Pular para o conteúdo principal
Última atualização em

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

info

Visualização

Esse recurso está em Public Preview.

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

Python Os UDFs registrados como funções em Unity Catalog diferem em escopo e suporte dos UDFs de PySpark com escopo para um Notebook ou SparkSession. Consulte Funções escalares definidas pelo usuário - Python.

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

Requisitos​

Para usar UDFs no Unity Catalog, o senhor deve atender aos seguintes requisitos:

  • Databricks Runtime 14.1 ou acima.
  • Para usar o código Python em UDFs registrados em Unity Catalog, o senhor deve usar um pro SQL warehouse ou um clustering executando Databricks Runtime 14.1 ou acima.
  • Para resolver visualizações que foram criadas usando um UDF registrado em Unity Catalog, o senhor deve usar Databricks Runtime 14.1 ou acima. O senhor não pode usar o site SQL warehouse.

Criação de UDFs no Unity Catalog​

Para criar um UDF no Unity Catalog, os usuários precisam de permissão USAGE e CREATE no esquema e permissão USAGE no catálogo. Veja Unity Catalog para obter mais detalhes.

Para executar um UDF, os usuários precisam de permissão EXECUTE no UDF. Os usuários também precisam da permissão de USO no esquema e no catálogo.

Para criar e registrar um UDF em um esquema Unity Catalog, o nome da função deve seguir o formato catalog.schema.function_name. Como alternativa, o senhor pode selecionar o catálogo e o esquema corretos no SQL Editor. Nesse caso, o nome da sua função não deve ter catalog.schema prefixado:

Criação de um UDF com o catálogo e o esquema pré-selecionados.

O exemplo a seguir registra uma nova função para o esquema my_schema no catálogo my_catalog:

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

As UDFs do Python para o Unity Catalog usam instruções compensadas por cifrões duplos ($$). Você deve especificar um mapeamento do tipo de dados. O exemplo a seguir registra um UDF que calcula o índice de massa corporal:

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

Agora o senhor pode usar essa função do Unity Catalog em suas consultas SQL ou no código PySpark:

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

Consulte Exemplos de filtro de linha e Exemplos de máscara de coluna para obter mais exemplos de UDF.

Estenda UDFs usando dependências personalizadas​

info

Visualização

Esse recurso está em Public Preview.

Amplie a funcionalidade dos UDFs do Unity Catalog Python para além do ambiente Databricks Runtime, definindo dependências personalizadas para bibliotecas externas.

Instale dependências das seguintes fontes:

  • PyPI pacote
  • Arquivos armazenados em volumes do Unity Catalog O usuário que invoca o UDF deve ter permissões READ VOLUME no volume de origem.
  • Arquivos disponíveis em URLs públicos Suas regras de segurança de rede workspace devem permitir o acesso a URLs públicos.

As dependências personalizadas para os UDFs do site Unity Catalog são compatíveis com os seguintes tipos de compute:

  • Notebook e trabalho sem servidor
  • compute para todos os fins usando Databricks Runtime versão 16.2 e acima
  • SQL warehouseprofissional ou serverless

Use a seção ENVIRONMENT da definição do UDF para especificar as dependências:

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

A seção ENVIRONMENT contém os seguintes campos:

campo

Descrição

Tipo

Exemplo de uso

dependencies

Uma lista de dependências separadas por vírgula a serem instaladas. Cada entrada é uma cadeia de caracteres que está em conformidade com o formato de arquivo de requisitos de 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

Especifica a versão do ambiente serverless na qual o senhor deve executar o UDF.

Atualmente, somente o valor None é suportado.

STRING

environment_version = 'None'

Utilizar UDFs Unity Catalog em PySpark​

Python
from pyspark.sql.functions import expr

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

Atualizar um UDF com escopo de sessão​

nota

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

Dada a seguinte sessão baseada em UDF em um Databricks Notebook:

Python
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:

SQL
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 gerenciadas com base nos controles de acesso aplicados ao catálogo, esquema ou banco de dados em que o UDF está registrado. Consulte gerenciar privilégios em Unity Catalog para obter mais informações.

Use a interface de usuário Databricks SQL ou Databricks workspace para conceder permissões a um usuário ou grupo (recomendado).

Permissões na interface do usuário workspace​

  1. Localize o catálogo e o esquema em que o UDF está armazenado e selecione o UDF.
  2. Procure a opção Permissions (Permissões ) nas configurações do UDF. Adicione usuários ou grupos e especifique o tipo de acesso que eles devem ter, como EXECUTAR ou gerenciar.

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

Permissões usando o Databricks SQL​

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

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

Para remover permissões, use o comando REVOKE como no exemplo a seguir:

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

Isolamento ambiental​

nota

Ambientes de isolamento compartilhado exigem Databricks Runtime 18.0 ou superior. Em versões anteriores, todas as UDFs (Funções Definidas pelo Usuário) Unity Catalog Python eram executadas em modo de isolamento estrito.

As UDFs (Funções definidas pelo usuário) Unity Catalog Python com o mesmo proprietário e sessão podem compartilhar um ambiente de isolamento por default. Isso melhora o desempenho e reduz o uso de memória, diminuindo o número de ambientes separados que precisam ser iniciados.

Isolamento rigoroso​

Para garantir que uma UDF seja sempre executada em seu próprio ambiente totalmente isolado, adicione a cláusula característica STRICT ISOLATION .

A maioria das UDFs não precisa de isolamento estrito. As UDFs (Funções Definidas pelo Usuário) de processamento de dados padrão se beneficiam do ambiente de isolamento compartilhado default e são executadas mais rapidamente com menor consumo de memória.

Adicione a cláusula de característica STRICT ISOLATION às UDFs que:

  • entrada de execução como código usando eval(), exec() ou funções semelhantes.
  • Escrever arquivos no sistema de arquivos local.
  • Modificar variáveis globais ou o estado do sistema.
  • Acesse ou modifique a variável de ambiente.

O código a seguir mostra um exemplo de uma UDF que deve ser executada usando STRICT ISOLATION. Esta UDF executa código Python arbitrário, podendo alterar o estado do sistema, acessar variáveis de ambiente ou escrever no sistema de arquivos local. O uso da cláusula STRICT ISOLATION ajuda a evitar interferências ou vazamentos de dados entre UDFs.

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

Defina DETERMINISTIC se sua função produzir resultados consistentes​

Adicione DETERMINISTIC à sua definição de função se ela produzir as mesmas saídas para as mesmas entradas. Isso permite otimizações de consulta para melhorar o desempenho.

Em default, os lotes Unity Catalog Python UDFs são considerados não determinísticos, a menos que sejam declarados explicitamente. Exemplos de funções não determinísticas incluem a geração de valores aleatórios, o acesso a horários ou datas atuais ou a realização de chamadas de API externas.

Consulte CREATE FUNCTION (SQL e Python)

UDFs para ferramentas do agente AI​

Os agentes generativos do AI podem usar os UDFs do Unity Catalog como ferramentas para realizar tarefas e executar lógica personalizada.

Consulte Criar ferramentas do agente AI usando as funções Unity Catalog.

UDFs para acesso a APIs externas​

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

nota

As UDFs Python permitem tráfego de rede TCP/UDP nas portas 80, 443 e 53 ao usar compute serverless ou compute configurada com o modo de acesso padrão.

SQL
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

$$;

UDFs para segurança e compliance​

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

O exemplo a seguir mascara a identidade de um endereço email, mantendo o comprimento e o domínio:

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

O exemplo a seguir aplica esse UDF em uma definição dinâmica do view:

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

Melhores práticas​

Para que os UDFs sejam acessíveis a todos os usuários, recomendamos criar um catálogo e um esquema dedicados com controles de acesso apropriados.

Para UDFs específicos da equipe, use um esquema dedicado no catálogo da equipe para armazenamento e gerenciamento.

Databricks recomenda que o senhor inclua as seguintes informações na documentação UDF:

  • O número da versão atual
  • Um registro de alterações para rastrear as modificações entre as versões
  • O objetivo, os parâmetros e o valor de retorno do UDF
  • Um exemplo de como usar o UDF

Aqui está um exemplo de um UDF que segue as práticas recomendadas:

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

Comportamento do fuso horário do carimbo de data/hora para entradas​

No Databricks Runtime 18.0 e superior, quando os valores TIMESTAMP são passados para UDFs Python , os valores permanecem em UTC, mas os metadados do fuso horário (atributo tzinfo ) não são incluídos no objeto datetime .

Essa alteração alinha as UDFs Python do Unity Catalog com as UDFs Python otimizadas para Arrow no Apache Spark.

Por exemplo, a seguinte consulta:

SQL
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');

Anteriormente, esse resultado era gerado em versões do Databricks Runtime anteriores à 18.0:

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

No Databricks Runtime 18.0 e versões superiores, agora ele produz esta saída:

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

Se sua UDF depende das informações de fuso horário, você precisa restaurá-las explicitamente:

Python
from datetime import timezone

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

Limitações​

  • O senhor pode definir qualquer número de funções Python em um UDF Python, mas todas devem retornar um valor escalar.
  • Python devem tratar os valores NULL de forma independente, e todos os mapeamentos de tipos devem seguir os mapeamentos da linguagem Databricks SQL.
  • Se nenhum catálogo ou esquema for especificado, os UDFs do Python serão registrados no esquema ativo atual.
  • Python Os UDFs são executados em um ambiente seguro e isolado e não têm acesso a sistemas de arquivos ou serviços internos.
  • Você não pode chamar mais de cinco UDFs por consulta.