Usando tabelas em workflows

Uma tabela é um recurso: linhas estruturadas que seus workflows leem e escrevem. Um bloco Table é o passo que faz essa leitura e 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 do Table de que sua tarefa precisa. Ele pode ler linhas para trabalhar, escrever linhas produzidas em outro lugar, atualizar linhas no lugar ou apenas consultar algo no meio da execução. Esta página cobre as operações e mostra algumas formas de combiná-las.

O exemplo usado ao longo da página é uma tabela leads com as colunas company, email, description e status. O objetivo é encontrar os leads não processados, pedir a um Agent que classifique cada um e escrever 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 destino. 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 ao lado das suas: id (o identificador único da linha), createdAt e updatedAt. O Studio gerencia essas colunas por você, então nunca as inclua ao inserir. Você ainda pode filtrar e ordenar por elas.

Lendo linhas

Query Rows recupera linhas de uma tabela, com filtro, ordenação e paginação opcionais. É assim que um workflow obtém sua 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 }

Os blocos seguintes leem esses valores pelo nome: <table1.rows> é o array, <table1.rowCount> é quantas linhas voltaram, <table1.totalCount> é quantas correspondiam ao filtro antes do limite. (Para mais sobre ler saídas por referência, veja como os blocks passam dados.)

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

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

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

Para uma consulta pontual, use Get Row by ID com um único Row ID. Get Schema retorna 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. Seu Row Data é um objeto cujas chaves correspondem aos nomes das suas colunas:

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

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

Batch Insert Rows adiciona muitas linhas em uma única operação (até 1000) a partir de um array Rows Data. Use em vez de repetir Insert Row em um loop quando você tem um conjunto de resultados para carregar de uma vez. A saída informa insertedCount.

Upsert Row insere uma linha, ou atualiza a existente se ela corresponder a uma coluna única. A saída inclui um campo operation com valor insert ou update, para que um bloco posterior saiba o que aconteceu.

Atualizando linhas

Para alterar uma linha existente, você a identifica pelo ID 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 um Row Data apenas com os campos que você quer alterar. Os campos não listados permanecem como estavam.

Update Rows by Filter altera todas as linhas que correspondem a um 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 informa 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 informam um deletedCount. Exclusões servem mais para limpeza do que para o ciclo diário de ler, processar e escrever.

Exemplo: enriquecendo linhas

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

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

Depois da execução, a tabela guarda as linhas enriquecidas. A execução seguinte consulta essas linhas de novo, e a coluna status impede o workflow de reprocessar o que já foi tratado. Assim a tabela funciona ao mesmo tempo como a fila de onde o workflow puxa trabalho e como o registro do que ele já fez.

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 durante o processamento: consulte uma tabela pricing pela moeda do pedido e deixe o Agent usar o resultado para calcular um total.

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

Paginar leituras grandes. Query Rows retorna no máximo 1000 linhas, e uma página também pode terminar antes se suas linhas atingirem o limite de tamanho da resposta — então uma página pode voltar menor que o seu Limit mesmo havendo mais linhas correspondentes. Avance o Offset pelo rowCount que você realmente recebeu, não pelo Limit que você pediu, e continue enquanto nextCursor estiver definido. Pare quando nextCursor for null. Avançar pelo Limit faz você perder o que uma página curta deixou para trás.

Inspecionando leituras e escritas

A entrada e a saída de todo bloco Table ficam registradas nos logs. Para um bloco de consulta, o log mostra o filtro e a ordenação enviados e as linhas recebidas. Para um Update ou um Insert, mostra os dados escritos e a contagem afetada. Quando uma escrita não faz nada ou uma consulta volta vazia, o log é onde você confere o filtro e o formato dos dados antes de olhar em qualquer outro lugar.

Próximos passos