Flink UDF: funções Java para fluxos que o SQL não resolve

ANÁLISE EDITORIAL

Quando uma transformação não cabe bem no SQL, é tentador pedir a um agente que escreva uma função Java, compile um JAR e publique tudo no ambiente. O problema é que esse pedido mistura decisões diferentes: escolher o tipo de função, gerar código, baixar dependências, criar infraestrutura, enviar um artefato e registrar uma função que passará a executar dentro do fluxo de dados. A Skill Flink UDF, mantida pela Confluent, separa essas etapas e inclui um gate explícito antes das mudanças.

Ela orienta UDFs escalares, funções de tabela e funções de tabela com processamento, conhecidas como PTFs. O material cobre Confluent Cloud e um laboratório local com Docker. Não é um runtime, não inclui Java, Flink ou credenciais e não transforma código gerado em produção confiável por conta própria.

O que esta Skill faz

A Skill ajuda o agente a identificar qual extensão é necessária, selecionar a referência correspondente ao ambiente, gerar uma base Java, implementar a lógica, montar o JAR, apresentar um plano de implantação e somente depois, se houver aprovação explícita, executar os passos de deploy e registro.

O roteamento evita carregar todo o material de uma vez. Há guias distintos para UDF ou UDTF em Confluent Cloud, PTF em Confluent Cloud, UDF ou UDTF local e PTF local. Referências separadas tratam dependências Maven ou Gradle e preparação de infraestrutura.

Para quem serve

É útil para desenvolvedores Java, engenheiros de dados e equipes de streaming que já sabem qual transformação desejam aplicar, mas precisam organizar a implementação para Apache Flink. Um bom caso é normalizar um valor com uma UDF escalar, expandir um campo em várias linhas com uma UDTF ou manter estado e temporizadores com uma PTF.

Não é uma introdução geral ao Kafka nem um substituto para desenho de arquitetura. Também não deve ser acionada para qualquer tarefa Flink sem função personalizada. A descrição da origem exclui Kafka Streams, conectores, produtores, consumidores e pipelines CDC mais amplos.

Origem, versão e exceção oficial

A origem auditada é o repositório confluentinc/agent-skills, mantido pela organização oficial da Confluent. A fotografia desta curadoria foi fixada no commit 914d95eff7ff50513b34bfb9ac97eda7c7fce899, de 02/09/2026. A Skill declara a versão 1.0.0.

O repositório tinha 56 estrelas e 10 forks na consulta de 13/09/2026. Portanto, esta entrada não foi escolhida por popularidade e está abaixo da preferência editorial por mil estrelas. A exceção foi aceita porque a origem é oficial, o repositório está ativo, a licença é Apache-2.0, o commit é verificável e as instruções podem ser comparadas com a documentação atual da própria plataforma.

Escolha primeiro entre UDF, UDTF e PTF

Uma UDF escalar recebe valores e devolve um valor por chamada. É adequada para conversão, validação ou cálculo pequeno. Uma UDTF pode emitir zero, uma ou várias linhas para uma entrada, útil para decompor coleções ou estruturas. Uma PTF opera sobre tabelas e pode usar estado e temporizadores para comportamentos mais avançados.

Essa escolha não é apenas um detalhe de classe Java. Ela muda assinatura, dependências, forma de invocação e risco operacional. A documentação de funções definidas pelo usuário deve ser a referência atual antes de decidir.

Compatibilidade e pré-requisitos

O pacote segue o formato de Agent Skills em Markdown. O material fixado trabalha com Java e apresenta configurações de Maven e Gradle. Para Confluent Cloud, a execução funcional também depende de conta, região compatível, ambiente, compute pool, Confluent CLI e permissões adequadas. Para o laboratório local, depende de Docker, Docker Compose e recursos suficientes para os contêineres.

As referências do commit usam Java 17 e versões específicas de dependências Flink. Isso registra a fotografia da Skill, não uma promessa de compatibilidade eterna. A documentação atual informa limites e capacidades que podem variar por linguagem, nuvem e região. Revalide Java, Flink, CLI, artefatos e disponibilidade antes de compilar.

Instalação com origem fixada

Abra primeiro a pasta fixada da Flink UDF e leia o SKILL.md auditado. O README oficial documenta instalação do catálogo por plugin e também por Skills CLI.

O comando npx skills add confluentinc/agent-skills --skill flink-udf consulta a rede e pode buscar uma revisão mais recente que a examinada nesta página. Faça a instalação em projeto de teste, confira o diff de arquivos e fixe a revisão aprovada quando precisar de reprodutibilidade.

Configuração antes do primeiro uso

Defina três respostas antes de pedir código: tipo de função, destino de implantação e forma de invocação. Registre também a versão efetiva do runtime, formato dos dados, comportamento diante de nulos, volume esperado, dependências externas e o resultado que validará a função.

Não cole chave, segredo ou arquivo de propriedades na conversa. Se o agente precisar orientar a configuração, forneça nomes de variáveis e identificadores não sensíveis. O conteúdo real deve permanecer em um gerenciador apropriado, fora do prompt e fora do repositório.

Primeiro uso seguro

Comece em um projeto descartável e limite a primeira tarefa à proposta. Exemplo: “Planeje uma UDF escalar Java que normalize códigos de produto. Não instale dependências, não compile, não acesse a nuvem e não altere arquivos até eu aprovar o plano”.

A saída inicial deve explicar assinatura, tratamento de nulos, casos de teste, arquivos que seriam criados e dependências necessárias. Só então autorize uma etapa pequena, como gerar a classe e os testes locais. Compilação, Docker e Confluent Cloud continuam como decisões separadas.

O gate obrigatório antes de modificar recursos

O ponto mais importante da Skill está no passo cinco. Antes de qualquer chamada que modifique recursos, ela manda apresentar o nome do artefato, caminho do JAR, nome da função, ambiente alvo e comandos ou SQL exatos. O agente deve aguardar aprovação explícita.

Esse gate cobre upload de artefato, cópia para contêiner em execução, CREATE FUNCTION e operações semelhantes. Preserve-o mesmo quando o pedido pareça óbvio. Aprovar geração de código não significa aprovar criação de cluster, chave, tópico, artefato ou função.

Fluxo local com Docker

No caminho local, a Skill orienta preparar Flink e Kafka em contêineres, compilar o JAR, copiá-lo para o SQL client e registrar a função. Isso é mais controlável que começar na nuvem, mas não é somente leitura. docker compose up cria contêineres, docker cp grava arquivos e reiniciar o cliente pode interromper sessões.

Use nomes de contêiner e portas confirmados no ambiente atual. Evite assumir que uma composição antiga continua compatível. Dados sintéticos e tópicos descartáveis reduzem o risco de confundir teste com carga real.

Fluxo na Confluent Cloud

Na nuvem, o JAR é enviado como artefato e a função é registrada no catálogo ou banco escolhido. A documentação oficial de criação de UDF descreve o processo atual e deve prevalecer sobre exemplos preservados no pacote.

Ambiente, organização, região, compute pool e credenciais precisam corresponder. Um comando válido no terminal errado ainda pode produzir uma mudança legítima no lugar errado. Mostre os identificadores antes da aprovação e use menor privilégio.

Dependências, JAR e cadeia de suprimentos

O material contém exemplos de Maven e Gradle, com escopos diferentes para execução local e serviço gerenciado. O agente pode propor plugins de empacotamento e bibliotecas adicionais. Cada dependência amplia a cadeia de suprimentos e o conteúdo do JAR.

Fixe versões, confira repositórios, gere inventário de dependências e execute testes antes do upload. Não inclua bibliotecas “por garantia”. Em Confluent Cloud, dependências fornecidas pelo runtime não devem ser empacotadas como se fossem dependências comuns sem confirmar a orientação atual.

Registro com CREATE FUNCTION

Depois do upload, a função é registrada com nome, classe e referência ao artefato. A referência atual de CREATE FUNCTION informa a sintaxe suportada. Nomear a função também é uma decisão de ciclo de vida, pois consultas passam a depender dela.

Teste primeiro com entrada conhecida e pequena. Confirme tipos, nulos, exceções e resultado antes de conectar a tabelas de produção. Uma função registrada com sucesso pode continuar incorreta do ponto de vista de negócio.

Atualização e remoção exigem plano próprio

A documentação atual registra que não há ALTER FUNCTION nem CREATE OR REPLACE FUNCTION para esse fluxo. Atualizar pode exigir remoção e novo registro. Consulte também a referência de DROP FUNCTION.

Não transforme atualização em sequência automática de drop e create. Mapeie consultas dependentes, janela de mudança, rollback, nome de versão e destino do artefato. Remover uma função usada pode interromper statements existentes.

PTF exige mais cuidado

Uma PTF pode lidar com estado, partições, temporizadores e semântica de tabela. Isso oferece mais poder e também mais maneiras de acumular estado, atrasar processamento ou produzir resultados inesperados. A documentação oficial de PTF deve orientar a implementação atual.

Defina limite de estado, expiração, particionamento e comportamento de timer. Teste eventos atrasados, chaves com alta cardinalidade e reinicialização. Uma demonstração com poucas linhas não prova estabilidade sob fluxo contínuo.

Resultado esperado

Uma boa entrega não é apenas um bloco de Java. Ela inclui escolha justificada do tipo de função, contrato de entrada e saída, tratamento de nulos, dependências fixadas, testes reproduzíveis, JAR identificável e plano de implantação com comandos exatos ainda não executados.

Depois de uma aprovação específica, a validação deve registrar artefato, função, ambiente, consulta de teste e resultado observado. Não trate ausência de erro como prova de correção, desempenho ou segurança.

Permissões e riscos

O uso funcional pode criar ambientes, clusters, tópicos, chaves, artefatos e funções. Também pode baixar dependências, gerar código, compilar, copiar JARs, reiniciar contêineres, consultar dados e excluir recursos durante limpeza. Cada classe de ação precisa de escopo e aprovação claros.

O material de configuração menciona credenciais e arquivos de propriedades. Não permita que o agente leia ou exponha segredos. Use contas de teste, papéis mínimos e dados sintéticos. O guia do Bastidores sobre revisão de permissões para agentes ajuda a separar leitura, escrita, execução e ação externa.

Limites, disponibilidade e custos

Regiões, versões, tamanho de artefato, quantidade de funções e conectividade externa mudam com o serviço. A página de conceitos e limitações de UDF deve ser consultada no dia da implantação.

Uma referência preservada no commit contém estimativas aproximadas de custo. Elas não foram usadas nesta página como preço atual confirmado. Consulte a calculadora, a tabela comercial e o contrato aplicáveis ao ambiente real antes de criar recursos.

Erros comuns e como corrigir

• Tipo de função errado: volte ao contrato de entrada e saída antes de mudar a classe Java.
• Classe não encontrada: confira nome totalmente qualificado, conteúdo do JAR e referência do artefato.
• Método eval incompatível: valide assinatura, visibilidade e tipos aceitos pelo runtime atual.
• Conflito de dependência: diferencie bibliotecas fornecidas pelo ambiente das que precisam entrar no JAR.
• Credencial recusada: confirme conta, recurso e papel sem copiar segredo para o prompt.
• Região sem suporte: consulte a matriz atual antes de mover dados ou criar nova infraestrutura.
• Estado cresce sem limite: revise partição, retenção e temporizadores da PTF.
• Teste passa, produção falha: amplie casos de nulo, volume, serialização, atraso e reinício em ambiente controlado.

Quando não usar

Não use esta Skill para consultas que o Flink SQL já expressa com clareza, para Kafka Streams, configuração de conectores, código genérico de produtor ou consumidor, ou pipelines CDC completos. Uma UDF adiciona código ao caminho de dados e precisa justificar sua existência.

Também não use para alterar um ambiente desconhecido apenas porque o agente consegue montar comandos. Sem inventário de recursos, dono, dados, dependências e rollback, permaneça na etapa de planejamento.

Versão, licença e pacote auditado

A pasta foi auditada no commit 914d95eff7ff50513b34bfb9ac97eda7c7fce899. O repositório usa licença Apache-2.0, que permite redistribuição com preservação dos termos aplicáveis.

O pacote local contém 11 arquivos textuais: SKILL.md, oito referências Markdown, LICENSE e ORIGEM.md. Seu SHA-256 é 04b2c042066d7923fe7e359d13a62a3938e292669b77957f8c4dd90aa7088ddd.

Limites do pacote local

O ZIP não inclui Confluent Cloud, Apache Flink, Kafka, Docker, Java, Maven, Gradle, Confluent CLI, JAR, imagem de contêiner, plugin, executável, script, avaliação, dependência, credencial, chave, segredo, arquivo .env, configuração, tópico, dado, log ou resultado.

As referências mantêm exemplos de comandos e código da origem porque são parte essencial da orientação. Isso não autoriza executá-los. Leia o ORIGEM.md, compare a revisão fixada e revalide versões e documentação antes de usar.

O que a revisão editorial confirmou

Os nove arquivos documentais usados pela Skill foram lidos e comparados por SHA-256 com a origem. A pasta também contém um arquivo JSON de avaliações, que não foi incluído no espelho porque não é necessário para o uso da Skill. Não há executável na pasta auditada.

A capa é uma ilustração editorial exclusiva de partículas atravessando um módulo de transformação. Ela não é captura de tela, interface real, logotipo, benchmark, resultado de execução ou material oficial da Confluent ou do Apache Flink.

Checklist antes de executar

• Fixar commit da Skill e versões de Java, Flink, CLI, Maven ou Gradle.
• Escolher UDF, UDTF ou PTF com base no contrato de dados.
• Confirmar ambiente, organização, região, compute pool e nomes sem expor segredos.
• Usar projeto, tópicos e dados descartáveis no primeiro teste.
• Revisar código, dependências, licenças, JAR e casos de teste.
• Separar geração, compilação, upload, registro, teste e limpeza.
• Exigir plano e comandos exatos antes de qualquer mutação.
• Validar resultado de negócio, logs, estado e rollback depois da execução.

Fontes oficiais consultadas

Foram consultados o README fixado do repositório, a documentação de conceitos e limitações de UDF, o guia de criação de UDF, o guia de criação de PTF, as referências de CREATE FUNCTION e DROP FUNCTION, a instalação da Confluent CLI e a especificação de Agent Skills. Consulta e números de adoção: 13/09/2026.

Veja também o catálogo de Skills do Bastidores da IA para comparar outras ferramentas por finalidade, origem e risco.