Operadores internos no Lakeflow Designer

O Lakeflow Designer inclui operadores internos para tarefas comuns de preparação e transformação de dados. Abra o painel de Operadores à esquerda para navegar por categoria, ou use Buscar por um operador... no topo do painel. A pesquisa do operador sugere operadores com base em sua intenção. Por exemplo, digitar average by month retorna o operador Aggregate . Veja Buscar operadores com IA search. Para configurar um operador depois de adicioná-lo à tela, clique duas vezes nele ou passe o mouse sobre ele e clique no (Operador Editar) para abrir o painel de configuração.

Cada operador exibe uma descrição gerada por IA do que ele faz. A descrição também atua como um editor para o operador: editar a descrição reconfigura o operador para corresponder à sua descrição.

Quando nenhum operador embutido se encaixa na sua tarefa, você pode criar seu próprio operador.

Entrada e saída

Fonte

Importa dados para o Designer de uma tabela do Catálogo do Unity ou de outra fonte com suporte. Para selecionar uma origem, pesquise uma tabela ou arquivo por nome ou navegue por catálogo e esquema. Você também pode criar uma nova tabela a partir deste painel.

Depois de selecionar uma tabela, o painel mostra o nome, o proprietário e a hora da última atualização da tabela. Clique em Selecionar uma nova fonte de dados para alterar a origem. Alterar a origem invalida o cache de saída para todos os operadores downstream.

Você também pode usar uma exibição de métrica do Catálogo do Unity como fonte. Ao selecionar uma exibição de métrica, selecione as dimensões e medidas a serem incluídas e o Designer gera a consulta agregada para você.

Para obter toda a gama de opções de ingestão de dados, incluindo o direcionamento de um volume ou pasta inteiro do Catálogo do Unity, consulte Ingestão de dados no Lakeflow Designer.

Inserir Dados

Cria uma tabela digitando valores em um editor de estilo de planilha. Use esse operador para adicionar pequenas quantidades de dados de referência, como valores de pesquisa ou dados de teste, sem criar uma tabela de origem separada.

Saída

Exporta dados do Designer. O operador de Saída pode gravar resultados em uma tabela do Catálogo Unity, publicá-los como uma visualização materializada ou gravá-los em um arquivo em um volume do Catálogo Unity, Google Drive ou SharePoint. No tipo de saída, selecione Tabela, Visualização Materializada ou Arquivo. Para a saída de um arquivo, selecione onde escrevê-lo no Destino.

Para saídas de tabela ou de arquivos em um volume do Unity Catalog, selecione um modo de escrita:

Clique em Executar para executar a preparação de dados visuais e gravar os resultados. Para uma saída de tabela, se a tabela não existir, o operador a criará. Execuções agendadas gravam no destino usando o mesmo modo de gravação.

Após um operador de Saída escrever uma tabela do Catálogo Unity, visualização materializada ou arquivo de volume, conecte sua porta de saída para continuar o fluxo de trabalho. Para tabelas, visualizações materializadas e saídas simples de arquivo único, a porta de saída lê diretamente do ativo persistente que o operador de saída acabou de escrever. Para saídas divididas, gravações em intervalo do Excel e arquivos sem cabeçalhos, a porta de saída passa pelas linhas de entrada.

Para saídas de arquivos em um volume do Unity Catalog, expanda Advanced para configurar as seguintes opções:

• Dividir por valores distintos: selecione uma coluna para escrever um arquivo para cada valor distinto. Para saída no Excel, você pode escrever cada valor em uma planilha separada em uma única cadeira. Uma execução pode criar até 50 arquivos ou planilhas.
• Nome da ficha: Para saída no Excel, defina a planilha alvo.
• Incluir linha de cabeçalho: Incluir nomes de colunas na saída CSV ou Excel.
• Faixa de células: Para saída do Excel no modo Sobrescrição, defina a célula inicial e uma célula final opcional. O designer preserva a formatação fora do intervalo e falha na execução se os dados não se encaixarem em um intervalo fixo. Você não pode combinar um intervalo de células com Dividir por valores distintos.

Para escrever um arquivo no Google Drive ou SharePoint:

1. Defina o tipo de saída para Arquivo e o Destino para Google Drive ou Microsoft 365 para SharePoint.
2. Ative o conector correspondente do Código Gênio e selecione Conectar , se solicitado. Faça login com uma conta que tenha acesso por escrita à pasta de destino.
3. Na URL da Pasta, cole o link na pasta do Google Drive ou SharePoint. No SharePoint, obtenha o link com o link de Copiar.
4. Digite um nome de arquivo, escolha um tipo de arquivo e clique em Executar.

Cada execução cria o arquivo ou substitui o conteúdo completo do arquivo existente pelo mesmo nome, incluindo todas as folhas de exercícios do Excel. A exportação deve caber em um arquivo de até 2,75 MiB. Prévias mostram os dados de entrada sem precisar gravar o arquivo. Execuções agendadas usam a conta e as credenciais do conector do usuário do run-as.

Limpar

Filter

Divide linhas com base em se elas atendem a uma ou mais condições, usando um construtor de condições gráficas.

Para combinar condições e organizar filtros complexos:

1. Clique em Adicionar condição e configure a coluna, operador e valor.
2. Selecione Todos para exigir que todas as condições sejam correspondidas, ou Qualquer para exigir pelo menos uma correspondência.
3. Para criar condições, abra o (Opções de condição) e selecione Converter para grupo. Adicione condições dentro do grupo e escolha Tudo ou Qualquer para esse grupo. Por exemplo, exigir que uma linha corresponda a uma condição de região e a qualquer uma de várias condições de status.
4. Clique em Aplicar para aplicar o filtro.

Para reverter uma condição, abra o (Opções de condição) e selecione Inverter condição. Para remover o aninhamento de um grupo, abra o menu do grupo e selecione Desagrupar.

Para reorganizar condições, clique (Reordenar condições), arraste as condições para a posição e clique em Fazer Pedido.

O operador Filter tem duas saídas para que você possa ramificar dados com base em se ele atende às condições:

Barreiras de proteção

Valida os dados recebidos em relação a uma lista ordenada de verificações e separa as linhas que passam das que falham.

• Avise e continue com as fileiras passadas:
  • A execução a jusante continua.
  • As linhas que passam em cada verificação ativada são enviadas para Aprovado.
  • Linhas que falham em pelo menos uma verificação ativada são enviadas para Falhado.
  • Erros contém uma linha para cada verificação falhada, incluindo seu tipo, gravidade e mensagem.
• Avise e bloqueie a saída passada:
  • Se uma verificação falhar, a execução a jusante continua, mas o Passed não contém linhas.
  • Falhou ainda contém as linhas falhadas, e Erros ainda contém os detalhes da falha.
  • Use essa opção para evitar o processamento posterior das linhas que passam, ao mesmo tempo em que permite o tratamento posterior de Falhas e Erros.
• Falhe no fluxo de trabalho:
  • Se uma verificação falhar, a execução para antes que os operadores a jusante executem.
  • Eles não recebem os resultados de Aprovado, Falhado ou Erros .
  • Em um trabalho agendado, a execução é marcada como falhada, o que pode acionar o gerenciamento configurado de falhas, como notificações de trabalho.

Quando você visualiza o próprio operador Guardrails, ainda pode inspecionar as três saídas no modo Fail no fluxo de trabalho .

Para persistir linhas de uma saída em qualquer um dos modos de aviso, conecte-a a um operador de saída.

Limit

Restringe a contagem de linhas passando apenas até o número máximo de linhas especificadas.

Prepare

Limpa e deriva colunas encadeando uma ou mais ações nos dados de entrada. Clique + Adicionar ação e selecione uma ação. Adicione quantas ações forem necessárias. Eles se aplicam em ordem.

Todas as ações, exceto Formula e Parse JSON , suportam múltiplas colunas.

Para remover uma ação, passe o mouse sobre sua linha e clique no .

Colunas personalizadas

A ação Fórmula abre o editor de expressões, em que você pode criar uma nova coluna ou substituir uma coluna existente usando linguagem natural ou código SQL. O editor tem duas caixas de entrada e é bidirecional:

• Descrição: Digite uma descrição em linguagem natural do que você quer que a coluna faça. O Designer usa o Código Genie para gerar a expressão de código correspondente abaixo.
• Expressão: Se você preferir escrever ou editar código diretamente, clique no botão de editar expressão. Editar a expressão gera automaticamente uma descrição de linguagem natural.

No editor de expressões, digite @ para abrir um menu com as colunas de entrada do operador e as funções SQL embutidas. Digite depois @ para filtrar a lista, depois selecione uma entrada para inseri-la: uma coluna insere seu nome, e uma função insere sua chamada com o cursor colocado entre parênteses. O mesmo @ menu está disponível nos editores de expressões de outros operadores, como condições personalizadas de Filtro e Join.

Prepare ações, trabalhe uma linha por vez. Para calcular uma coluna a partir dos valores em outras linhas, como um total acumulado ou o valor da linha anterior, use a Fórmula Multi-Linha.

Selecionar

Seleciona, renomeia e reordena colunas dos dados de entrada.

Classificar

Ordena linhas em uma ou mais colunas.

Único

Remove linhas duplicadas dos dados de entrada. Por padrão, o operador desduplica em todas as colunas. Você pode, em vez disso, escolher um subconjunto de colunas como chave e ordenar as linhas para controlar qual duplicado é mantido.

Combine

Combinar

Combina dados de múltiplas tabelas em uma única saída usando uma operação conjunta.

Join

Tabelas de links combinando conjuntos de dados de entrada com base em valores de coluna correspondentes.

Com duas entradas, o operador Join tem três saídas por padrão, então você pode ramificar um fluxo de trabalho baseado nos resultados da join:

Com duas entradas, selecionar um tipo específico de Join (full, inner, left ou right) produz uma única saída unida em vez das três saídas divididas.

Transform

Função de IA

Executa uma operação interna de IA em seus dados. No painel de configuração, abra Selecionar uma função e selecione uma das funções na tabela a seguir. Cada função expõe opções no painel para entradas (por exemplo, colunas, prompts, rótulos ou idiomas) e saídas.

Selecione Saídas limpas para usar os valores de resposta de ai_classify, ai_extract, ai_decide, ou ai_query em operadores posteriores. Para ai_query, a limpeza se aplica quando a função usa failOnError => false. A opção não está disponível para funções de valores de tabela como ai_forecast. Outras saídas de funções permanecem inalteradas.

Para cada saída limpa nomeada answer, o operador retorna:

• answer: A resposta limpa. Para ai_extract com um campo ou ai_decide com uma pergunta, este é o valor tipado. Múltiplos campos ou questões produzem uma estrutura.
• answer_ai_error: A mensagem de erro quando a função falha, ou nula quando ela tem sucesso. Uma linha falhada tem resposta nula.
• answer_raw: A resposta completa, incluindo metadados, para inspeção ou solução de problemas.

Para detalhes sobre cada função, veja Transformar dados não estruturados usando Funções de IA.

Aggregate

Resume as linhas agrupando dados e calculando valores agregados.

Fórmula Multi-Linha

Calcula novas colunas a partir dos valores em outras linhas, como totais gerados, números de linha e IDs de registro, rankings, valores anteriores e próximos, diferenças entre linhas e médias móveis. Use a Fórmula Multi-Linha quando um cálculo depende de linhas vizinhas. Para cálculos que usam apenas os valores na linha atual, use Preparar. Você também pode encontrar o operador pesquisando no menu de operador por Record ID.

O operador mantém uma lista ordenada de fórmulas. As fórmulas vão de cima para baixo, e cada fórmula adiciona uma coluna à saída. Se o nome da coluna de uma fórmula coincide com uma coluna existente, a fórmula sobrescreve essa coluna. Se a lista estiver vazia, ou se toda fórmula for desligada, o operador passa sua entrada sem alterações.

Todo tipo de fórmula possui um campo de nome de nova coluna . Todo tipo, exceto a expressão Custom , também tem Order by e Group by, que definem a janela de linhas que a fórmula observa:

Tipos de fórmulas

A tabela a seguir descreve cada tipo de fórmula e seus campos, além dos campos compartilhados:

Para Diferença em relação à linha anterior, Média móvel e suavização exponencial, a coluna Of lista apenas colunas numéricas. Linhas de distância, linhas de volta e Janela (linhas) aceitam números inteiros de 1 ou mais. Uma fração é arredondada para baixo, e um número menor que 1, um campo vazio ou um valor que não é um número usam 1. Um fator de suavização (α) fora da faixa permitida usa 0,3. Comece em aceita qualquer número inteiro, e um campo vazio usa 1. Se você digitar uma fração em Começar em, o campo mostra que Valor está fora da faixa e Aplicar não está disponível.

As seguintes condições fazem com que o operador retorne um erro ao ser executado:

• Uma coluna Of que não está nos dados de entrada, por exemplo, após um operador a montante renomear ou removê-la.
• Suavização exponencial em uma coluna decimal. Para suavizar valores decimais, primeiro converta a coluna em dupla, por exemplo, com a ação do tipo Preparar Alteração .
• Suavização exponencial com um fator de suavização muito pequeno, abaixo de cerca de 0,002. Use um valor maior.
• Numeração de número de linha/posto que passa por 2.147.483.647, o maior valor que uma coluna inteira tem, quando Start em é 2.147.483.647 ou menos. Use um Começo menor no valor.

Configurar fórmulas

Para configurar a lista de fórmulas no painel de configuração, use os seguintes controles:

• Adicionar uma fórmula: Clique em Adicionar fórmula e selecione um tipo de fórmula. A nova fórmula aparece no final da lista com um nome de coluna padrão, como running_total, e seu editor se abre.
• Editar uma fórmula: Clique em uma fórmula na lista para abrir seu editor. Cada fórmula mostra seu tipo e um resumo de uma linha, como customer_running_total = sum(amount) (by customer_id; ordered by order_date). Para número de linha / posição, o resumo também mostra um Início em outro que 1 e um tipo de saída de texto , como record_id = row_number() from 1001 as text (ordered by order_id). O editor fica aberto enquanto você trabalha na tela. Para fechar, clique no O ícone de fechar.
• Reordenar fórmulas: arraste uma fórmula para cima ou para baixo. Como as fórmulas se executam em ordem, mova uma fórmula abaixo de qualquer fórmula cuja coluna ela utilize.
• Desligue ou ligue uma fórmula: Passe o mouse sobre uma fórmula e clique no botão do interruptor. Uma fórmula desativada permanece na lista, mas não roda.
• Duplicar ou excluir uma fórmula: Passe o mouse sobre uma fórmula, clique no menu Kebab, e selecione Duplicar ou Deletar.

Para salvar suas alterações, clique em Aplicar. Se uma fórmula ativada estiver sem um campo obrigatório, Apply não está disponível, e uma mensagem ao lado identifica os campos ou fórmulas a serem concluídos.

Se você não tiver permissão para editar a preparação dos dados visuais, pode ver a lista de fórmulas e seus resumos, mas não pode abri-las, adicioná-las, reordená-las ou alterá-las.

Exemplo: totais e mudanças contínuas para cada cliente

Este exemplo usa uma orders tabela com uma linha para cada ordem:

Para calcular o total contínuo de cada cliente, o valor do pedido anterior e a alteração em relação ao pedido anterior, adicione um operador Multi-Row Formula após a orders fonte e configure as seguintes fórmulas. Cada fórmula usa Ordem pororder_date (Ascendente) e Agrupar porcustomer_id:

1. Adicione uma fórmula agregada em curso . Defina o nome da nova coluna para customer_running_total, Agregue para Soma, e De paraamount.
2. Adicione um Valor de outra fórmula de linha . Defina o nome da nova coluna para previous_amount, Direção para Lag (linha anterior),Da coluna para amount, e Linhas afastadas para 1. Sair Se não houver tal linha definida como Nula.
3. Adicione uma diferença em relação à fórmula da linha anterior . Defina o nome da nova coluna para amount_change, Da coluna para amount, e Linhas de volta para 1.
4. Clique em Aplicar.

A tabela a seguir mostra a saída com as três novas colunas, ordenadas por cliente e data, com order_date as omitidas:

O primeiro pedido de cada cliente não tem pedido anterior, então previous_amount e amount_change são nulos. Para preencher previous_amount com 0, defina If no such row em Zero.

Dinâmico

Remodela dados tabulares em duas direções. Use as guias na parte superior do painel de configuração para selecionar o modo.

Linhas → Colunas (pivô)

Transforma valores distintos em uma coluna em novos cabeçalhos de coluna, preenchidos com valores agregados de outra coluna.

Colunas → Linhas (unpivot)

Dobra uma ou mais colunas em linhas.

Incluir colunas

Para qualquer um dos modos, selecione quais colunas permanecem na saída ao lado dos valores dinâmicos ou não dinâmicos e solte as colunas que você não precisa antes da transformação. O designer infere colunas fixas (agrupamento) das colunas que você não atribui a funções dinâmicas, de valor ou não dinâmicas.

Code

Python

Executa Python personalizados (PySpark) nos dados de entrada.

Um padrão mínimo é usar a primeira entrada quando presente ou um DataFrame vazio, caso contrário:

# inputs["data"] is a list of input DataFrames

result = inputs["data"][0] if inputs["data"] else spark.createDataFrame([], "col: string")

A partir daí, você pode encadear operações dataframe (por exemplo, , , ou junções) select antes do término da atribuição ou substituir filter por um novo DataFrame criado a partir de withColumn. resultresultinputs["data"]

Durante uma prévia, a saída do operador flui para o painel de saída conforme é produzida, incluindo qualquer coisa que você renderize display() e texto que imprima, para que você possa ver os resultados antes do fim da execução.

Modo de pré-visualização em Python

Enquanto você constrói uma preparação visual de dados, o Designer visualiza continuamente a saída de cada operador em uma amostra dos seus dados. Essas prévias rodam seu código em Python da mesma forma que uma execução completa. Isso é um problema quando seu código tem efeitos colaterais, como chamar uma API externa, enviar uma notificação ou escrever para um sistema fora do Unity Catalog. Normalmente, você não quer que esses efeitos colaterais apareçam em toda prévia.

Para deixar seu código diferenciar os dois, leia config["is_preview"], um valor booleano que o Designer define para você:

• True Durante uma prévia, então você pode pular efeitos colaterais.
• False durante uma execução completa, como quando você clica em Executar ou em uma execução programada.

Por exemplo, efeitos colaterais do guarda para que eles rodem apenas fora das prévias:

result = inputs["data"][0] if inputs["data"] else spark.createDataFrame([], "col: string")

# Side effects run only on a full run or scheduled job, not during previews.
if not config["is_preview"]:
    write_results_to_external_system(result)

Um operador personalizado deve declarar uma is_preview propriedade config para receber esse valor. Veja Pular efeitos colaterais durante as prévias.

SQL

Grava código SQL personalizado para qualquer transformação não coberta pelos outros operadores.

Campo	Descrição
Editor de SQL	Digite uma instrução SQL SELECT . Para fazer referência à saída de um operador de entrada, use o nome desse operador como o nome da tabela em sua consulta. Por exemplo: SELECT COUNT(*) FROM aggregate_2 WHERE 1 = 1 Clique no Botão para abrir o painel de código SQL completo e ver como sua instrução se encaixa no fluxo de trabalho completo.
Parameters	Para fazer referência a um parâmetro de preparação de dados visuais, use a sintaxe de marcador de parâmetro nomeada, como :environment. O designer mostra um exemplo acima do editor quando você abre o operador para edição. Veja Usar parâmetros no Lakeflow Designer.

Relatório

HTML

Renderiza uma página HTML personalizada, incluindo CSS e JavaScript incorporados, no painel de saída. Conecte um ou mais operadores ao operador HTML para exibir seus dados como gráficos, tabelas ou outras visualizações. O operador HTML não tem porta de saída, então você não pode conectar outros operadores depois dele.

Por exemplo, a página a seguir mostra quantas linhas o primeiro operador conectado passa para a página:

<h2>Summary</h2>
<p id="summary">Connect an operator to bind data.</p>
<script>
  const input = window.inputs[0];
  if (input) {
    document.getElementById('summary').textContent = input.rows.length + ' rows available.';
  }
</script>

Durante uma prévia, cada entrada é limitada pela configuração de Linhas escaneadas pelo operador. A página recebe no máximo 10.000 linhas no total, divididas igualmente entre as entradas conectadas. Veja Controle quanto processamento de pré-visualização de dados.

Visualization

Cria uma visualização dos dados de entrada e os renderiza diretamente na tela. Conecte um operador de Visualização a qualquer operador que produza dados tabulares para mapear os resultados sem sair do Designer.

Para configurar a visualização, abra o operador e selecione um tipo de Visualização e mapeie suas colunas para o gráfico.

Ferramentas de lona

Group

Agrupa visualmente operadores na tela sem alterar como os dados fluem entre eles, o que é útil quando uma preparação de dados visuais aumenta ou você deseja refletir estágios lógicos.

Note

Adiciona uma anotação na tela para que você possa documentar o fluxo de trabalho em si: sua finalidade, suposições, ressalvas ou contexto de entrega para qualquer pessoa que abra a preparação de dados visuais mais tarde.

Crie seu próprio operador

Quando nenhum operador embutido cobre sua lógica, crie um operador personalizado. Um operador personalizado é local ou compartilhado:

• Local: O operador pertence à preparação atual de dados visuais. Descreva a transformação, e o Código Gênio gera o operador. Você não escreve código. Veja Criar um operador local personalizado com Código Genie.
• Compartilhado: O operador está registrado para que outros usuários e preparadores de dados visuais possam usá-lo. Sua lógica é Python ou uma função do Catálogo Unity, descrita no YAML. Veja Construir um operador compartilhado.

Recursos adicionais

• Tutorial: Construa uma preparação visual de dados
• Ingestão de dados no Lakeflow Designer
• Operadores personalizados no Lakeflow Designer