BLOG
Para atualizar a base de conhecimento no n8n sem misturar documentos antigos, mantenha uma identidade estável para cada documento, controle quais chunks pertencem a cada versão e faça a busca consultar apenas a versão autorizada. Inserir o arquivo novamente não substitui necessariamente os registros anteriores. Apagar tudo antes de gerar os novos embeddings também pode deixar o atendimento sem conteúdo se a atualização falhar.
O arquivo e seus chunks não têm a mesma identidade
Um documento pode gerar vários chunks, e cada entrada vetorial pode ter seu próprio ID. Mantenha também um identificador estável do documento de origem, separado desses IDs. Como recomendação editorial, associe documento, cliente, versão e posição do chunk para localizar exatamente o conjunto que será atualizado. O nome do arquivo sozinho pode mudar ou se repetir e não deve ser a única referência operacional.
Um conjunto ilustrativo de metadados inclui tenant_id, file_id, version, chunk_index e content_hash. Esses nomes são uma proposta para o seu esquema, não campos obrigatórios do n8n. O hash ajuda a reconhecer conteúdo já processado; a versão identifica uma publicação; o índice organiza os fragmentos. Defina onde esses valores são gravados e como entram na consulta antes de iniciar a carga.
O Supabase permite armazenar dados JSON e JSONB e consultar propriedades desses objetos, como explica a documentação de JSON no banco. Isso oferece uma forma de guardar a identidade do documento junto ao chunk. Porém, armazenar o metadado não aplica um filtro automaticamente: a operação de busca ou de exclusão precisa utilizá-lo.
| Estratégia | Quando considerar | O que conferir |
|---|---|---|
| Atualizar uma entrada pelo ID | Correção de registro conhecido | Outros chunks do documento continuam exigindo tratamento. |
| Upsert com identidade determinística | Repetir cargas sem inserir a mesma entrada novamente | Chunks que deixaram de existir não somem por consequência. |
| Excluir o conjunto antigo e inserir o novo | Carga com janela de manutenção ou indisponibilidade aceitável | Há um intervalo sem os dados e risco de falha entre etapas. |
| Preparar versão e trocar a versão ativa | Atendimento que precisa continuar durante a carga | A busca deve respeitar a versão ativa e a troca deve ser controlada. |
O que Update Documents resolve no n8n
O nó Supabase Vector Store oferece Update Documents para atualizar uma entrada pelo ID do embedding. Esse modo não equivale a substituir automaticamente todos os chunks de um arquivo. A função por ID está descrita na documentação do nó.
Se uma revisão alterar a divisão do documento, os registros necessários podem mudar de quantidade e de conteúdo. Atualizar alguns IDs conhecidos não explica o que acontecerá com os fragmentos antigos que sobraram. Antes da carga, determine se você vai substituir o conjunto completo, reconciliar IDs ou manter versões separadas. Essa decisão precisa ser explícita no fluxo, sem depender de um efeito implícito de Update Documents.
Como exemplo hipotético, uma política comercial revisada pode ficar menor depois que uma condição foi removida. Se a ingestão apenas atualizar as entradas que continuam existindo, um chunk antigo com a condição excluída pode permanecer consultável. O teste relevante é fazer a pergunta sobre essa condição e examinar os documentos recuperados, não apenas confirmar que a nova carga terminou sem erro.
Upsert não é apagar e inserir novamente
No Supabase, upsert usa as colunas de conflito para decidir entre inserir uma linha e tratar uma linha já existente. Ele não é sinônimo de executar DELETE e depois INSERT. Configure a identidade e o tratamento de conflitos de acordo com o esquema, como explica a referência de upsert.
IDs determinísticos podem ajudar uma retentativa a reconhecer entradas já carregadas. Como recomendação editorial, derive a identidade de valores estáveis do cliente, documento, versão e chunk, com a restrição correspondente no banco. Isso não elimina a necessidade de verificar os registros que a nova carga deixou de produzir. Upsert resolve conflitos das linhas enviadas; a reconciliação do conjunto antigo continua sendo outra responsabilidade.
Se a estratégia exigir exclusão, selecione o conjunto exato por cliente, documento e versão. A referência de delete mostra a operação acompanhada de filtros. Antes de aplicar uma exclusão em produção, confira os registros que o mesmo filtro selecionaria e preserve uma forma de recuperação. Não use uma tabela inteira como substituto de um filtro incompleto.
Também diferencie o formato da ferramenta usada. Uma expressão SQL sobre JSONB, um parâmetro REST e um filtro do cliente JavaScript não têm necessariamente a mesma sintaxe. Escolha o mecanismo realmente disponível no seu nó ou em uma chamada de API documentada. Copiar uma expressão de outro contexto pode falhar ou selecionar um conjunto diferente do pretendido.
Por que excluir antes pode criar uma lacuna
Considere um fluxo que apaga a versão anterior e depois chama o serviço de embeddings. Se a chamada falhar, o documento pode ficar indisponível para recuperação. Se a inserção terminar parcialmente, o agente pode consultar um conjunto incompleto. Por isso, “delete then insert” não deve ser apresentado como a estratégia universalmente mais segura; avalie a janela de manutenção, a possibilidade de retorno e a exigência de continuidade.
Para uma base pequena com atualização acompanhada, uma substituição durante manutenção pode ser suficiente. Nesse caso, valide o conteúdo novo antes da exclusão, guarde os dados necessários para restauração e confirme a carga completa antes de retomar o atendimento. Se a operação não tolera essa interrupção, considere preparar os registros novos sem torná-los visíveis ao mecanismo de busca.
Uma alternativa editorial é manter um registro do documento com uma referência à versão ativa. Primeiro gere e grave os chunks da nova versão em estado de preparação; depois confira sua integridade e altere a referência ativa. A consulta deve combinar a identidade do cliente e do documento com essa referência. Esse controle exige esquema e consulta próprios: não surge apenas por acrescentar um campo chamado version nos metadados.
No PostgreSQL, uma transação pode agrupar operações do banco como uma unidade, com confirmação ou reversão, conforme o guia de transações. Isso pode apoiar uma troca controlada da referência ativa. Não significa que duas chamadas HTTP em nós diferentes, ou uma chamada externa de embeddings, passaram a integrar automaticamente a mesma transação.
Evite também que uma carga mais antiga termine depois e substitua a versão mais recente. Como recomendação de projeto, confira a versão esperada antes de publicar a nova referência e registre qual job fez a mudança. Gere os embeddings antes da etapa curta de confirmação no banco. Se a preparação falhar, mantenha a versão anterior como ativa e investigue o job incompleto.
A busca precisa aplicar os mesmos filtros
A integração LangChain documentada pelo Supabase permite filtros de metadados na busca, utilizando a função de correspondência configurada. Confira quais filtros chegam à função e como ela os aplica, conforme o guia de LangChain e Supabase. Um filtro usado na carga ou na limpeza não garante que a recuperação feita pelo agente use a mesma restrição.
Em uma base compartilhada, o isolamento precisa alcançar leitura e escrita. Inclua a identidade do cliente no desenho da consulta e nas permissões apropriadas. O Supabase documenta Row Level Security e os limites de papéis que podem contorná-la. Um valor de tenant enviado pelo modelo não substitui a autorização estabelecida pelo sistema.
Mantenha credenciais privilegiadas no serviço que executa a integração, com acesso controlado. Não exponha uma chave administrativa no navegador nem suponha que ela preserva o isolamento apenas porque a tabela tem políticas. Confira o papel efetivo da conexão e o comportamento da consulta usada pelo retriever. O objetivo é impedir que um erro de metadado se transforme em consulta ou exclusão de outro cliente.
Reveja todos os caminhos de consulta: Get Many, retriever conectado a uma chain, ferramenta do agente e eventuais consultas próprias. Não presuma que um filtro configurado em um caminho será transportado para os demais. Para cada entrada de atendimento, registre qual função ou nó faz a busca e como recebe cliente, documento e versão autorizados.
Fluxo operacional para uma atualização controlada
- Identifique a origem: confira cliente, documento e evento de mudança.
- Compare o conteúdo: reconheça eventos repetidos e arquivos que não mudaram.
- Prepare a versão: extraia texto, gere chunks e embeddings com configuração compatível com a busca.
- Registre a carga: guarde a relação dos chunks e o estado do job.
- Confira a integridade: compare o esperado com o que foi efetivamente gravado.
- Valide a recuperação: execute perguntas que dependem de mudanças e remoções.
- Publique a versão: use o mecanismo de troca definido para a sua base.
- Limpe versões antigas: aplique retenção e exclusão seletiva conforme a política do negócio.
Trate remoção do documento de origem como evento próprio. Uma lista incompleta, uma falha de permissão ou um erro transitório ao buscar arquivos não deveria ser interpretado automaticamente como autorização para apagar a base. Confirme a origem da remoção e a abrangência do filtro. Se mantiver uma versão para retorno, defina por quanto tempo ela será retida e quem ainda pode consultá-la.
Como provar que os documentos antigos saíram da recuperação
Monte perguntas sobre fatos alterados, condições removidas e informação exclusiva da nova versão. Inspecione os chunks recuperados, seus identificadores e seus metadados, além da resposta final. Uma frase correta pode vir da memória da conversa ou do conhecimento prévio do modelo, sem demonstrar que a busca deixou de retornar o documento antigo.
Inclua retentativa do mesmo job, carga parcial, documento menor, duas atualizações concorrentes e tentativa de consulta a outro cliente. Essas são recomendações de teste, não resultados medidos neste guia. Confira se a versão ativa permanece válida quando a preparação falha e se o job repetido evita inserir novamente o mesmo conjunto. Preserve esses casos para a próxima alteração do fluxo.
Se o agente ainda mencionar uma informação removida, investigue também memória de conversa, cache, outra ferramenta e outro repositório de documentos. Excluir um chunk do Supabase não apaga mensagens já presentes no contexto da sessão. Para comparar a recuperação, use uma conversa nova e rastreie a origem do conteúdo retornado, sem concluir que toda resposta antiga prova falha na exclusão.
Perguntas frequentes
Update Documents substitui um arquivo inteiro?
A operação documentada atua pelo ID da entrada vetorial. Um arquivo dividido em vários chunks exige controle do conjunto. Confira o que será atualizado, o que ficará de fora e como os registros que deixaram de existir serão tratados.
Posso simplesmente apagar e inserir a nova versão?
Pode ser uma escolha de implementação quando a indisponibilidade intermediária é aceitável e há recuperação definida. Ela não é atômica apenas por estar no mesmo workflow. Para continuidade, avalie preparação de versão e troca controlada com consulta compatível.
Qual é o custo dessa atualização?
Depende do processamento, do serviço de embeddings, do volume de conteúdo, do armazenamento e das consultas. Compare gerar tudo novamente com reconhecer documentos que não mudaram. Não há preço fixo ou economia medida neste artigo.
O que escolher para a sua operação
Use atualização por ID para uma entrada conhecida, upsert para tratar conflitos de identidade e exclusão seletiva para reconciliar registros que não devem permanecer. Quando a continuidade importa, prepare a nova versão e controle sua publicação na busca. A base fica governável quando identidade, recuperação, autorização e retorno usam o mesmo desenho, não quando o workflow apenas termina em verde.
