Apresentando as Funções de Tabela Definidas pelo Usuário (UDTFs) em Python no Unity Catalog

As UDFs de Python permitem que você crie uma camada de abstração de lógica personalizada para simplificar a construção de query. Mas e se você quiser aplicar uma lógica complexa, como executar um modelo grande ou detectar padrões de forma eficiente em várias linhas da sua tabela?

Apresentamos anteriormente as Funções de Tabela Definidas pelo Usuário (UDTFs) em Python com escopo de sessão para oferecer suporte a uma lógica de query personalizada mais poderosa. As UDTFs permitem que você faça a execução de uma lógica robusta e com estado (stateful) em Python em tabelas inteiras, facilitando a solução de problemas que normalmente são difíceis em SQL puro.

Por que usar Funções de Tabela Definidas pelo Usuário:

• Processe qualquer dataset com flexibilidade

  A palavra-chave declarativa TABLE() permite que você direcione qualquer tabela, view ou até mesmo uma subconsulta dinâmica diretamente para sua UDTF. Isso transforma sua função em um bloco de construção poderoso e reutilizável para qualquer fatia de seus dados. Você pode até mesmo usar PARTITION BY, ORDER BY e WITH SINGLE PARTITION para particionar a tabela de entrada em subconjuntos de linhas a serem processados por chamadas de função independentes diretamente na sua função Python.

• Execução de inicialização pesada apenas uma vez por partição

  Com um UDTF, você pode fazer a execução de códigos de configuração caros, como carregar um modelo de ML grande ou um arquivo de referência grande, apenas uma vez para cada partição de dados, e não para cada linha.

• Manter o contexto entre as linhas

  As UDTFs podem manter estados de uma linha para a outra dentro de uma partição. Essa capacidade única permite análises avançadas, como detecção de padrões em séries temporais e cálculos contínuos complexos.

Melhor ainda, quando as UDTFs são definidas no Unity Catalog (UC), essas funções são acessíveis, detectáveis e executáveis por qualquer pessoa com o acesso apropriado. Em resumo, você escreve uma vez e execução em qualquer lugar.

Temos o prazer de anunciar que as UDTFs em Python do UC agora estão disponíveis em Public Preview com o Databricks Runtime 17.3 LTS, o Databricks SQL e os Notebooks e Jobs Serverless.

Neste blog, vamos discutir alguns casos de uso comuns de UDTFs Python do UC com exemplos e explicar como você pode usá-las em seu pipeline de dados.

Mas, primeiro, por que usar UDTFs com UC?

A Vantagem da UDTF Python no Unity Catalog

• Implemente uma vez em Python puro e chame-a de qualquer lugar em sessões e Workspaces

  Escreva sua lógica em uma classe Python padrão e chame as UDTFs em Python a partir de SQL warehouses (com Databricks SQL Pro e serverless), clusters UC Standard e Dedicados e Lakeflow Declarative pipelines.

• Descubra usando tabelas do sistema ou o Catalog Explorer
• Compartilhe-a entre usuários, com governança completa do Unity Catalog.

• Conceder e revogar permissões para UDTFs do Python
• Execução segura com isolamento LakeGuard: as UDTFs Python são executadas em sandboxes com acesso temporário a disco e rede, impedindo a possibilidade de interferência de outras cargas de trabalho.

Começo Rápido: correspondência de endereço IP simplificada

Vamos começar com um problema comum de engenharia de dados: corresponder endereços IP a uma lista de blocos CIDR de rede (por exemplo, para identificar tráfego de redes internas). Essa tarefa é complicada em SQL padrão, pois faltam funções integradas para lógica e pacotes CIDR.

Os UDTFs do UC Python eliminam esse atrito. Eles permitem que você traga as bibliotecas e os algoritmos avançados do Python diretamente para o seu SQL. Criaremos uma função que:

1. Usa uma tabela de logs de IP como entrada.
2. Carrega com eficiência uma lista de CIDRs de rede conhecidos apenas uma vez por partição de dados.
3. Para cada endereço IP, ele usa a poderosa biblioteca ipaddress do Python para verificar se o endereço pertence a alguma das redes conhecidas.
4. Retorna os dados de log originais, enriquecidos com a rede correspondente.

Vamos começar com alguns dados de amostra contendo endereços IPv4 e IPv6.

A seguir, definiremos e faremos o registro de nossa UDTF. Observe a estrutura da classe Python:

• O parâmetro t TABLE aceita uma tabela de entrada com qualquer schema — a UDTF se adapta automaticamente para processar quaisquer colunas que sejam fornecidas. Essa flexibilidade significa que você pode usar a mesma função em diferentes tabelas sem precisar modificar a assinatura da função, mas também exige uma verificação cuidadosa do esquema das linhas.
• O método __init__ é perfeito para configurações pesadas e únicas, como carregar nossa grande lista de redes. Esse trabalho ocorre uma vez por partição da tabela de entrada.
• O método eval processa cada linha, contendo a lógica principal de correspondência. Este método é executado exatamente uma vez para cada linha da partição de entrada que está sendo consumida por sua instância correspondente da classe UDTF IpMatcher para essa partição.
• A cláusula HANDLER especifica o nome da classe Python que implementa a lógica da UDTF.

Agora que nosso ip_cidr_matcher está registrado no Unity Catalog, podemos chamá-lo diretamente do SQL usando a sintaxe TABLE(). É tão simples quanto consultar uma tabela comum.

A saída é:

Gerando legendas para imagens com inferência em lote

Este exemplo demonstra a configuração e o uso de uma UDTF em Python do UC para legendagem de imagens em lotes usando Endpoints de servindo modelo de visão da Databricks. Primeiro, criamos uma tabela contendo URLs de imagens públicas do Wikimedia Commons:

Esta tabela contém 4 imagens de amostra: um calçadão na natureza, uma foto macro de uma formiga, um gato e uma galáxia.

E então criamos uma UDTF Python do UC para gerar legendas de imagem.

1. Primeiro, inicializamos a UDTF com a configuração, incluindo o tamanho dos lotes, os tokens da API da Databricks, o endpoint do modelo de visão e a URL do workspace.
2. No método eval, coletamos os URLs da imagem em um buffer. Quando o buffer atinge o tamanho do lotes, nós trigger o processamento em lotes. Isso garante que várias imagens sejam processadas juntas em uma única chamada de API, em vez de chamadas individuais por imagem.
3. No método de processamento em lotes, fazemos o download de todas as imagens armazenadas em buffer, as codificamos como base64 e as enviamos para uma única solicitação de API para o Databricks VisionModel. O modelo processa todas as imagens simultaneamente e retorna legendas para o lote inteiro.
4. O método terminate é executado exatamente uma vez no final de cada partição. No método terminate, processamos as imagens restantes no buffer e geramos todas as legendas coletadas como resultados.

Lembre-se de substituir <workspace-url> pela URL real do seu workspace da Databricks (por exemplo, https://your-workspace.cloud.databricks.com).

Para usar a UDTF de legendagem de imagens em lotes, basta chamá-la com a tabela de imagens de amostra: lembre-se de substituir your_secret_scope e api_token pelo secret scope e pelo nome da key reais para o token da API da Databricks.

A saída é:

Você também pode gerar legendas de imagens categoria por categoria:

A saída é:

Trabalhos futuros

Estamos trabalhando ativamente para estender as UDTFs em Python com recursos ainda mais poderosos e de alto desempenho, incluindo:

• Os UDTFs polimórficos no Unity Catalog são funções cujos esquemas de saída são analisados e resolvidos dinamicamente com base nos argumentos de entrada. Eles já são suportados em UDTFs Python com escopo de sessão e estão em andamento para UDTFs Python no Unity Catalog.
• Python Arrow UDTF: uma nova API de UDTF em Python que permite o processamento de dados com lote de registros (record batch) nativo do Apache Arrow (iterator[Arrow.record_batch]) para ganhos de desempenho significativos com grandes conjuntos de dados (datasets).

(This blog post has been translated using AI-powered tools) Original Post