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

Importante

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

O Azure Databricks fornece uma sintaxe nativa do SQL para registrar funções personalizadas em esquemas regidos pelo Unity Catalog. UDFs Python registradas como funções no Unity Catalog diferem em escopo e suporte de UDFs PySpark com escopo para um notebook ou SparkSession. Consulte Funções escalares definidas pelo usuário - Python.

Para obter a referência completa da linguagem SQL, consulte CREATE FUNCTION (SQL e Python).

Para obter informações sobre como o Unity Catalog gerencia permissões em funções, consulte CREATE FUNCTION.

Requisitos

• Databricks Runtime 13.3 LTS ou superior.
• Para usar o código Python em UDFs registrados no Unity Catalog, você deve usar um armazém SQL sem servidor ou pro SQL ou um cluster executando o Databricks Runtime 13.3 LTS ou superior.
• Para resolver exibições que foram criadas usando um UDF registrado no Unity Catalog, você deve usar um armazém SQL sem servidor ou profissional.

Funções SQL personalizadas no Unity Catalog

Quando você cria uma função SQL usando computação configurada para o Unity Catalog, a função é registrada no esquema atualmente ativo por padrão. O exemplo a seguir demonstra a sintaxe que você pode usar para declarar um catálogo de destino e um esquema para uma nova função:

CREATE FUNCTION target_catalog.target_schema.roll_dice()
    RETURNS INT
    LANGUAGE SQL
    NOT DETERMINISTIC
    CONTAINS SQL
    COMMENT 'Roll a single 6 sided die'
    RETURN (rand() * 6)::INT + 1;

Todos os usuários com privilégios suficientes na função podem usar a função em ambientes de computação configurados para o Unity Catalog, como no exemplo a seguir:

SELECT target_catalog.target_schema.roll_dice()

Nota

Você pode usar UDFs usando LANGUAGE SQL para retornar tabelas ou valores escalares.

Registrar um Python UDF para Unity Catalog

No Databricks Runtime 13.3 LTS e superior, você pode usar a instrução SQL CREATE FUNCTION para registrar UDFs Python escalares no Unity Catalog.

Importante

Apenas armazéns SQL pro e sem servidor suportam UDFs Python para Unity Catalog.

As UDFs Python são projetadas para fornecer toda a expressividade do Python diretamente nas funções SQL, permitindo operações personalizadas, como transformações avançadas, mascaramento de dados e hashing.

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.

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

Consulte Quais UDFs são mais eficientes?.

Nota

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

UDFs Python para Unity Catalog usam instruções definidas por cifrões duplos ($$), como no exemplo de código a seguir:

CREATE FUNCTION target_catalog.target_schema.greet(s STRING)
RETURNS STRING
LANGUAGE PYTHON
AS $$
  return f"Hello, {s}"
$$

O exemplo a seguir demonstra o uso dessa função para retornar instruções de saudação para todos os nomes armazenados na first_name coluna de uma tabela chamada students:

SELECT target_catalog.target_schema.greet(first_name)
FROM students;

Você pode definir qualquer número de funções Python dentro de um Python UDF, mas deve retornar um valor escalar.

As funções Python devem manipular NULL valores de forma independente e todos os mapeamentos de tipo devem seguir os mapeamentos da 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 catálogo ou esquema for especificado, as UDFs Python serão registradas no esquema ativo atual.

O exemplo a seguir importa uma biblioteca e usa várias funções dentro de um Python UDF:

CREATE FUNCTION roll_dice(num_dice INTEGER, num_sides INTEGER)
RETURNS INTEGER
LANGUAGE PYTHON
AS $$
  import numpy as np

  def roll_die(num_sides):
    return np.random.randint(num_sides) + 1

  def sum_dice(num_dice,num_sides):
    return sum([roll_die(num_sides) for x in range(num_dice)])

  return sum_dice(num_dice, num_sides)
$$