Funções definidas pelo utilizador (UDFs) de SQL e de Python no Unity Catalog

As funções definidas pelo usuário (UDFs) no Unity Catalog estendem os recursos SQL e Python no Azure Databricks. Permitem-lhe definir, usar e partilhar e governar de forma segura funções personalizadas em ambientes informáticos.

UDFs de Python registradas como funções no Unity Catalog diferem no âmbito e no suporte das UDFs PySpark com escopo para um bloco de notas ou SparkSession. Consulte funções escalares definidas pelo utilizador (UDFs) em Python.

Para registar UDFs escritos em Scala ou Java no Catálogo Unity, consulte Scala e funções definidas pelo utilizador (UDFs) em Java no Catálogo Unity.

Para ver que cargas de trabalho e tabelas referenciam um UDF no Unity Catalog antes de o modificar, veja Ver linhagem do UDF.

Veja CREATE FUNCTION (SQL, Python, Scala e Java) para referência completa à linguagem SQL.

Requisitos

Para usar UDFs no Unity Catalog, você deve atender aos seguintes requisitos:

• 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 vista incluir um UDF Python do Unity Catalog, irá falhar nos armazéns SQL clássicos.
• O suporte a instâncias ARM para UDFs Scala em clusters com Unity Catalog está disponível no Databricks Runtime 15.2 e a partir de versões superiores.

As UDFs Python escalares e em lote do Unity Catalog estão disponíveis de forma geral em todos os tipos de computação suportados.

Requisitos de funcionalidades do Python UDF

Os requisitos variam consoante a funcionalidade. O Databricks Runtime 19 e a versão 6 do ambiente não são requisitos gerais para os UDFs Python do Unity Catalog.

Para as UDFs de sessão do PySpark em notebooks serverless ou tarefas, os requisitos de ambiente referem-se ao ambiente da sessão. No caso das UDFs Python definidas em SQL, referem-se a environment_version na cláusula ENVIRONMENT de cada função. Alterar o ambiente de sessão não altera o ambiente de uma função existente do Catálogo Unity. Por exemplo, uma sessão que utiliza a versão 6 do ambiente pode chamar uma função do Catálogo Unity definida com a versão 5 do ambiente.

Feature	Requisitos
ENVIRONMENT Dependências de cláusulas e personalizadas	Notebooks e jobs serverless; armazéns SQL pro ou serverless; Databricks Runtime 16.2 ou superior em computação clássica. No cálculo clássico que executa Databricks Runtime 16.2 a 18.1, environment_version deve ser 'None'.
UDFs Python do Catálogo Batch Unity	computação sem servidor; data warehouses SQL Pro e sem servidor; Databricks Runtime 16.3 ou superior em computação clássica
Handler nomeado para um UDF escalar de Python	Databricks Runtime 18.1 ou superior em computação clássica. Em processamento sem servidor e em SQL warehouses Pro e Serverless, defina explicitamente o environment_version da UDF como 6 ou superior.
Credenciais de serviço num UDF Python escalar	Databricks Runtime 18.1 ou superior em computação clássica. Em processamento sem servidor e em SQL warehouses Pro e Serverless, defina explicitamente o environment_version da UDF como 6 ou superior. A computação clássica não requer a versão 6 do ambiente. Nos armazéns de SQL sem servidor, ative também a pré-visualização pública da rede de carga de trabalho isolada.
Credenciais de serviço num Batch Unity Catalog Python UDF	Computação serverless; armazéns SQL pro e serverless; Databricks Runtime 16.3 ou superior na computação clássica. A versão 6 do ambiente não é obrigatória. Nos armazéns de SQL sem servidor, ative também a pré-visualização pública da rede de carga de trabalho isolada.
Segredos num escalar ou Catálogo Batch Unity Python UDF	Defina explicitamente environment_version como 6 ou superior; computação serverless; SQL warehouses Pro e serverless; Databricks Runtime 19 ou superior com modo de acesso padrão em computação clássica. A invocação direta não é suportada em computação em modo de acesso dedicado.
Comportamento de entrada compatível TIMESTAMP com PySpark	Databricks Runtime 18.1 ou superior em computação clássica. Em processamento sem servidor e em SQL warehouses Pro e Serverless, defina explicitamente o environment_version da UDF como 6 ou superior.
Mais de cinco chamadas a UDF numa consulta	Databricks Runtime 18.1 ou superior em computação clássica. Em computação sem servidor e em armazéns de SQL Pro e sem servidor, defina explicitamente o environment_version de cada UDF para 6 ou superior.

Os UDFs e funcionalidades existentes que estavam disponíveis durante a Pré-visualização Pública continuam a funcionar nas versões de execução anteriores aplicáveis.

A versão do ambiente também determina se os chamadores precisam de acesso direto às dependências armazenadas num volume do Unity Catalog. Ver Permissões para dependências em volumes do Catálogo Unity.

Versões do ambiente na computação clássica

Na computação clássica, definir environment_version para um valor diferente 'None' de requer Databricks Runtime 18.2 ou superior. No Databricks Runtime 16.2 a 18.1, define environment_version = 'None' sempre que usares a ENVIRONMENT cláusula. O valor 'None' utiliza o ambiente Python predefinido.

No Databricks Runtime 18.2 ou superior, para comportamento previsível, o Azure Databricks recomenda definir explicitamente um fixo environment_version em cada definição de Python UDF do Unity Catalog. Escolha uma versão que cumpra os requisitos de funcionalidades da UDF e que siga estas recomendações de compatibilidade:

Versão do Databricks Runtime	Versão máxima recomendada do ambiente
da versão 18.2 até à 18.x	5
19.x	6

Criação de UDFs SQL e Python no Catálogo Unity

Para criar uma UDF em SQL ou Python no Unity Catalog, os utilizadores precisam das permissões USAGE e CREATE sobre o esquema e da permissão USAGE sobre o catálogo. Consulte o 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 da permissão USAGE no esquema e no catálogo.

Para criar e registar um UDF num esquema do Unity Catalog, o nome da função deve seguir o formato catalog.schema.function_name. Como alternativa, você pode selecionar o catálogo e o esquema corretos no Editor SQL. Neste caso, o nome da sua função não deve ter catalog.schema antes dele:

O exemplo a seguir registra uma nova função no my_schema esquema do 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);

Os UDFs em Python para o Catálogo Unity utilizam instruções de uso compensadas por sinais duplos de dólar ($$). Você deve especificar um mapeamento de tipo de dados. O exemplo seguinte regista um UDF que calcula o índice de massa 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)
$$;

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;

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

Utilize um processador com nome numa UDF escalar em Python

Em computação clássica, os handlers com nome requerem o Databricks Runtime 18.1 ou superior. Em processamento sem servidor e em SQL warehouses Pro e Serverless, defina explicitamente o environment_version da UDF como 6 ou superior. O exemplo seguinte utiliza a versão 6 do ambiente. No computo clássico a correr Databricks Runtime 18.1, omita a ENVIRONMENT cláusula. Em versões de runtime mais recentes, siga as recomendações de compatibilidade se incluir a cláusula.

Use a HANDLER cláusula para nomear uma função Python no corpo do UDF como ponto de entrada. O handler nomeado aceita os argumentos UDF e devolve um valor que corresponde ao tipo de retorno declarado. O código fora do handler é executado quando cada ambiente Python inicializa a UDF, antes do handler processar as entradas. Use este código para inicialização única que pode ser reutilizada entre chamadas de handler.

O exemplo seguinte inicializa greeting_prefix antes de definir greet_handler, a função que trata as 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 segredos num UDF Python

Scalar e Batch Unity Catalog Python UDFs podem aceder a segredos declarados na SECRETS cláusula. A definição UDF deve definir environment_version explicitamente como 6 ou superior. Um segredo do Unity Catalog usa um nome em três partes (catalog.schema.secret) e é diferente de um segredo do Azure Databricks ao nível da área de trabalho. Para suporte de computação, permissões e a exceção da máscara de coluna de computação dedicada, veja requisitos e permissões do UDF.

Para aceder a um segredo de uma UDF:

1. Adicione o nome em três partes do segredo na cláusula SECRETS na definição da UDF. Uma UDF só pode recuperar segredos declarados nesta cláusula.
2. No corpo da UDF, chame databricks.secrets.get() com o catálogo, o esquema e o nome do segredo.

O exemplo seguinte de UDF escalar usa um segredo do Unity Catalog como chave de assinatura para um código de autenticação de mensagens baseado em hash (HMAC). Utilize a mesma cláusula SECRETS com PARAMETER STYLE PANDAS para aceder a segredos declarados a partir de um processador Batch UDF.

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

Warning

Não retorne valores secretos a partir de uma UDF. A redação secreta ajuda a reduzir a exposição acidental em erros e logs, mas não impede que o código UDF exponha material secreto nos resultados das consultas.

Estender UDFs usando dependências personalizadas

Nota

Para instalar dependências personalizadas a partir da Internet num Serverless SQL Warehouse, o seu espaço de trabalho tem de ter ativada a funcionalidade de Pré-visualização Pública Enable networking for isolated workloads in Serverless SQL Warehouses na página Pré-visualizações.

Pode estender as capacidades dos UDFs Python do Unity Catalog para além do ambiente Databricks Runtime, definindo dependências personalizadas para bibliotecas externas.

Requisitos

As dependências personalizadas para UDFs do Unity Catalog são suportadas nos seguintes tipos de computação:

• Blocos de anotações e trabalhos sem servidor
• Computação clássica multiusos usando Databricks Runtime versão 16.2 e superior
• Armazém SQL profissional ou sem servidor

Fontes de dependência

Instale dependências das seguintes fontes:

• Pacotes PyPI
• Ficheiros armazenados em volumes do Catálogo UnityVer Permissões para dependências nos volumes do Catálogo Unity.
• Arquivos disponíveis em URLs públicas As regras de segurança de rede do espaço de trabalho devem permitir o acesso a URLs públicas. Consulte Requisitos.

Nota

Se o seu espaço de trabalho restringir o acesso à rede serverless, deve configurar regras de segurança de rede para permitir os URLs públicos. Veja Definir regras de saída.

Permissões para dependências em volumes do Catálogo Unity

O criador da função tem de ter READ VOLUME num volume de origem para adicionar uma dependência desse volume para uma UDF.

Para um UDF cuja definição define explicitamente environment_version como 6 ou superior, os autores das chamadas necessitam de EXECUTE no UDF, mas não de READ VOLUME no volume de origem. Se a definição de UDF omitir environment_version, o definir como None ou o definir como uma versão anterior, os autores da chamada também têm de ter READ VOLUME no volume de origem.

Definir dependências

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

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

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

Campo	Descrição	Tipo	Exemplo de utilização
dependencies	Uma lista de dependências separadas por vírgulas para instalar. Cada entrada é uma cadeia de caracteres que está em conformidade com o pip Requirements File Format.	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 onde deve ser executado o UDF. Este campo é obrigatório sempre que a ENVIRONMENT cláusula está presente. Uma versão de ambiente fixo executa o UDF com uma versão específica do Python e um conjunto de pacotes pré-instalados, independentemente da versão do Python e dos pacotes do Databricks Runtime subjacente. Os valores suportados são uma versão do ambiente igual ou superior a 3, por exemplo '6', ou a cadeia de caracteres 'None'. O valor 'None' seleciona o ambiente Python padrão. Na computação clássica, definir environment_version para um valor diferente 'None' de requer Databricks Runtime 18.2 ou superior. Nos Databricks, apenas 'None' o tempo de execução 16.2 a 18.1 é suportado. Quando são suportadas versões fixas do ambiente, selecione explicitamente uma para comportamento previsível. Na computação serverless e nos SQL warehouses pro e serverless, algumas funcionalidades exigem uma versão de ambiente explícita. Defina environment_version para a versão necessária ou superior em cada definição de UDF. Omitir a cláusula ENVIRONMENT inteira ou definir environment_version = 'None' não ativa essas funcionalidades. Consulte os requisitos de funcionalidades do Python UDF. Para compatibilidade de versões de computação clássica, veja Versões de Ambiente no computo clássico. Para consultar a lista de versões disponíveis, consulte Versões de ambiente.	STRING	environment_version = '6'

Use UDFs do catálogo Unity 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 definida no escopo da sessão

Nota

A sintaxe e a semântica das 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 num notebook 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

Os controlos de acesso aplicados ao catálogo, esquema ou base de dados na qual regista a UDF gerem as suas permissões. Consulte Gerenciar privilégios no Catálogo Unity 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 espaço de trabalho

1. Encontre o catálogo e o esquema onde o UDF está armazenado e selecione o UDF.
2. Procure uma opção Permissões nas configurações UDF. Adicione utilizadores ou grupos e especifique o tipo de acesso que devem ter, como EXECUTAR ou GERIR.

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 remover permissões, use o comando REVOKE como no exemplo a seguir:

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

Isolamento do ambiente

Nota

Ambientes de isolamento partilhado requerem Databricks Runtime 18.1 e superiores. Em versões anteriores, todos os UDFs Python do Unity Catalog corriam em modo de isolamento estrito.

Os Python UDFs no Unity Catalog com o mesmo proprietário e sessão podem partilhar um ambiente de isolamento por padrão. Isto melhora o desempenho e reduz o uso de memória ao diminuir o número de ambientes separados que têm de ser lançados.

Isolamento rigoroso

Para verificar que uma UDF é sempre executada num ambiente próprio e totalmente isolado, adicione a cláusula de característica STRICT ISOLATION.

A maioria das UDFs não precisa de isolamento estrito. As UDFs de processamento de dados padrão se beneficiam do ambiente de isolamento compartilhado padrão e são executadas mais rapidamente com menor consumo de memória.

Adicione a cláusula STRICT ISOLATION característica aos UDFs que:

• Execute a entrada como código usando eval(), exec()ou funções semelhantes.
• Grave arquivos no sistema de arquivos local.
• Modifique as variáveis globais ou o estado do sistema.
• Acesse ou modifique variáveis de ambiente.

O código seguinte mostra um exemplo de um UDF que deve ser executado usando STRICT ISOLATION. Este UDF executa código Python arbitrário, pelo que pode alterar o estado do sistema, aceder a variáveis de ambiente ou escrever no sistema de ficheiros local. A utilização da STRICT ISOLATION cláusula ajuda a prevenir interferências ou fugas de dados entre UDFs.

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

Definir DETERMINISTIC se a sua função produz 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.

Por defeito, o Azure Databricks trata os UDFs Python do Batch Unity Catalog como não determinísticos, a menos que declare explicitamente o contrário. Exemplos de funções não determinísticas incluem gerar valores aleatórios, acessar horas ou datas atuais ou fazer chamadas de API externas.

Ver CREATE FUNCTION (SQL, Python, Scala e Java)

UDFs para ferramentas de agentes

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

Veja Criar ferramentas de agente usando funções do Catálogo Unity.

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

Os UDFs em Python permitem tráfego de rede TCP/UDP nas portas 80, 443 e 53 quando utilizam computação serverless ou computação configurada com modo de acesso padrão.

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 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
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 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 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 as UDFs sejam acessíveis a todos os usuários, o Databricks recomenda a criação de um catálogo e esquema dedicados com controles de acesso apropriados.

Para UDFs específicas da equipe, use um esquema dedicado dentro do catálogo da equipe para armazenamento e gerenciamento.

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

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

O exemplo seguinte mostra uma UDF que segue as melhores práticas:

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 para entradas processadas linha a linha com marca temporal

Uma entrada TIMESTAMP chega a uma UDF Python processada linha a linha como um valor datetime sem fuso horário em UTC. Na computação clássica, este comportamento requer Databricks Runtime 18.1 ou superior. Em processamento sem servidor e em SQL warehouses Pro e Serverless, defina explicitamente o environment_version da UDF como 6 ou superior. O datetime objeto não inclui metadados de fuso horário no seu tzinfo atributo.

Os UDFs Python do Catálogo Batch Unity recebem entradas de carimbo temporal nos pandas.Series objetos e não utilizam este datetime mapeamento.

Esta alteração harmoniza os UDFs Python do Unity Catalog com os UDFs Python otimizados para Arrow no Apache Spark.

Por exemplo, a consulta seguinte define explicitamente a versão 6 do ambiente e o fuso horário da sessão para 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');

O caminho de execução anterior retorna um valor com informação de fuso horário no fuso horário da sessão. Isto aplica-se no computo clássico antes do Databricks Runtime 18.1. Também se aplica à computação sem servidor e aos armazéns de SQL Pro e sem servidor quando se omite a cláusula ENVIRONMENT, se define environment_version = 'None' ou se seleciona uma versão anterior à versão 6. Com o fuso horário da sessão definido para UTC, o caminho anterior produz:

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

Com a definição apresentada, a computação sem servidor e os armazéns SQL Pro e sem servidor utilizam o comportamento compatível com o PySpark. A computação clássica a correr Databricks Runtime 18.1 ou superior usa o mesmo comportamento quando ajusta ou omite a ENVIRONMENT cláusula:

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

Esta alteração pode afetar os campos de relógio, bem como tzinfo. Para o instante 2024-10-23T10:30:00Z, o comportamento anterior numa sessão America/Los_Angeles produz 2024-10-23 03:30:00-07:00. O novo comportamento produz o valor UTC sem fuso horário 2024-10-23 10:30:00.

Se o seu UDF depende da informação do fuso horário, restaure o UTC explicitamente:

from datetime import timezone

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

Adicionar informação do fuso horário UTC não restaura os campos de relógio locais da sessão anteriores. Se a tua lógica precisar desses campos, converte também o valor consciente para o fuso horário da sessão pretendido. Por exemplo:

from zoneinfo import ZoneInfo

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

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 valores NULL de forma independente e todos os mapeamentos de tipo devem seguir os mapeamentos da linguagem SQL do Azure Databricks.
• Se não especificar um catálogo ou esquema, o Azure Databricks regista os UDFs Python no esquema ativo atual.
• Os UDFs em Python correm num ambiente seguro e isolado e não têm acesso a sistemas de ficheiros ou serviços internos.
• Pode invocar mais de cinco UDFs numa consulta na computação clássica com o Databricks Runtime 18.1 ou superior. Na computação serverless e nos warehouses SQL Pro e serverless, cada definição de UDF deve definir explicitamente environment_version para 6 ou superior.