Usando tabelas em workflows

Uma tabela é um recurso: linhas estruturadas que seus workflows leem e escrevem. Um bloco Table é o passo que faz a leitura e a escrita dentro de um workflow. Você escolhe uma operação no bloco (consultar linhas, inserir uma linha, atualizar linhas), aponta para uma tabela, e o resultado fica guardado sob o nome do bloco para os blocos seguintes usarem.

Um workflow usa as operações Table de que a tarefa precisa. Pode ler linhas para processar, gravar linhas produzidas em outro lugar, atualizar linhas no lugar ou só consultar algo no meio da execução. Esta página cobre as operações e mostra algumas formas de combiná-las.

Ao longo desta página, o exemplo contínuo é uma tabela leads com as colunas company, email, description e status. O objetivo é encontrar leads não processados, fazer um Agent classificar cada um e gravar a categoria de volta.

O bloco Table

Um bloco Table executa uma operação contra uma tabela. O dropdown Operation escolhe a ação; o seletor Table escolhe o alvo. Os campos abaixo desses dois mudam conforme a operação escolhida.

As operações se dividem em três grupos:

• Leitura: Query Rows, Get Row by ID, Get Schema.
• Escrita: Insert Row, Batch Insert Rows, Upsert Row.
• Atualização e exclusão: Update Row by ID, Update Rows by Filter, Delete Row by ID, Delete Rows by Filter.

Toda linha carrega três colunas internas além das suas: id (identificador único da linha), createdAt e updatedAt. O Zoen gerencia essas colunas, então você nunca as inclui ao inserir. Ainda assim, pode filtrar e ordenar por elas.

Lendo linhas

Query Rows recupera linhas de uma tabela, com filtragem, ordenação e paginação opcionais. É assim que um workflow obtém a entrada a partir de uma tabela.

No nosso exemplo, o bloco consulta leads onde status é igual a unprocessed. A saída traz as linhas correspondentes e as contagens:

{ success: true, rows: [ { id: "row_...", company: "Acme", ... } ], rowCount: 5, totalCount: 42 }

Blocos posteriores leem isso pelo nome: <table1.rows> é o array, <table1.rowCount> é quantas voltaram, <table1.totalCount> é quantas bateram no filtro antes do limite. (Para mais sobre leitura de saídas por referência, veja como os blocos passam dados.)

Filter Conditions restringem o resultado. No modo de entrada padrão Builder, você adiciona regras visualmente: escolha uma coluna, um operador e um valor. Mude o Input Mode para Editor para escrever o filtro como objeto, com operadores como $eq, $gt, $contains e $in:

{ status: "unprocessed", createdAt: { $gte: "2026-06-01" } }

Sort Order ordena o resultado, de novo visualmente no modo Builder ou como objeto no modo Editor, por exemplo { createdAt: "desc" }. Limit limita quantas linhas voltam (padrão 100, máximo 1000) e Offset pula linhas para paginação.

Para uma busca pontual, use Get Row by ID com um único Row ID. Get Schema devolve as definições de coluna da tabela, útil quando um workflow precisa inspecionar a estrutura antes de escrever. A lista completa de operadores está na referência do bloco Table.

Escrevendo linhas

Insert Row adiciona uma linha. O Row Data é um objeto cujas chaves batem com os nomes das colunas:

{ company: "Acme", email: "deals@acme.com", description: "...", status: "unprocessed" }

A saída é a linha inserida, incluindo o id e os timestamps que o Zoen gerou.

Batch Insert Rows adiciona muitas linhas de uma vez (até 1000) a partir de um array Rows Data. Use em vez de repetir Insert Row em loop quando tiver um conjunto de resultados para carregar de uma vez. A saída reporta insertedCount.

Upsert Row insere uma linha, ou atualiza a existente se bater em uma coluna única. A saída inclui um campo operation com insert ou update, para um bloco seguinte saber o que aconteceu.

Atualizando linhas

Para alterar uma linha existente, você a nomeia ou filtra por ela.

Update Row by ID modifica uma linha. Recebe um Row ID, muitas vezes <table1.rows[0].id> de uma consulta anterior, e Row Data só com os campos que você quer mudar. Campos não listados permanecem como estavam.

Update Rows by Filter altera todas as linhas que batem no filtro — a ferramenta certa quando você não conhece os IDs. No nosso exemplo, depois que o Agent classifica os leads, o workflow define status como qualified em todas as linhas onde status é unprocessed. A saída reporta updatedCount e a lista de updatedRowIds.

Delete Row by ID e Delete Rows by Filter removem linhas das mesmas duas formas, por ID ou por filtro, e reportam um deletedCount. Exclusões são mais para limpeza, não para o ciclo cotidiano de ler–processar–escrever.

Exemplo: enriquecendo linhas

Uma forma de combinar as operações é consultar linhas, processá-las e gravar os resultados de volta. Aqui, o workflow classifica leads não processados:

1. Table (Query Rows) lê leads onde status é unprocessed.
2. Agent lê os campos de uma linha, classifica e devolve uma saída estruturada como { category: "enterprise", score: 0.9 }.
3. Table (Update Rows by Filter) grava a categoria de volta e muda status para qualified.

Depois da execução, a tabela guarda as linhas enriquecidas. A próxima execução consulta de novo, e a coluna status impede o workflow de reprocessar o que já tratou. Assim, a tabela serve tanto de fila de onde o workflow puxa quanto de registro do que já foi feito.

Variações

Consulta no meio da execução. Um bloco Table não precisa ser o primeiro nem o último passo. Coloque um Query Rows no meio para buscar dados de referência enquanto processa: consulte uma tabela pricing pela moeda do pedido e deixe o Agent usar o resultado para calcular o total.

Iterar linha a linha. Envolva um ciclo consultar → processar → atualizar em um bloco Loop para tratar uma linha por vez. Roda em sequência, mais lento que uma atualização em lote, mas útil quando cada linha precisa da própria lógica em vários passos. Dentro do loop, o Agent lê a linha atual e um Update Row by ID grava o resultado.

Paginar leituras grandes. Query Rows devolve no máximo 1000 linhas. Quando totalCount passa do seu Limit, aumente o Offset a cada passagem (0, depois 100, depois 200) para percorrer a tabela inteira, tipicamente dentro de um Loop.

Inspecionando leituras e escritas

A entrada e a saída de todo bloco Table ficam registradas nos logs. Para um bloco Query, o log mostra o filtro e a ordenação enviados e as linhas recebidas. Para Update ou Insert, mostra os dados da linha gravados e a contagem afetada. Quando uma escrita não faz nada ou uma consulta volta vazia, o log é o primeiro lugar para checar o filtro e o formato dos dados.

Próximos passos