BLOG
To update an n8n knowledge base without mixing old documents into new answers, give each source document a stable identity, track the chunks belonging to each version, and make retrieval use only the authorized version. Uploading the same file again does not necessarily replace previous vector records. Deleting everything before generating new embeddings can leave customer service without information if the update fails.
Practical rule: when service must continue during an update, prepare and verify the new version before making it searchable. Removing the old version is a separate step from publishing the new one.
A source file and its chunks need separate identities
One document may produce many chunks, each with its own vector-store ID. Keep a stable source-document ID as well. As an editorial design suggestion, associate each chunk with the customer or tenant, document, version, and position. A filename alone can change or repeat, so it is a weak operational key.
Illustrative metadata could include tenant_id, file_id, version, chunk_index, and content_hash. These are proposed fields, not mandatory n8n names. A hash helps recognize unchanged content; a version identifies a publication; the index helps reconstruct order. Decide where each value is stored and how the search uses it before the first load.
Supabase documents JSON and JSONB storage, which can hold metadata beside a record. Storing a field does not automatically apply it as a filter. Retrieval and deletion must use the field in the actual query.
Choose an update strategy by its failure behavior
| Strategy | Consider when | Check carefully |
|---|---|---|
| Update one entry by ID | Correcting a known vector record | Other chunks from the file remain |
| Upsert deterministic IDs | Repeating loads without duplicating sent rows | Removed chunks do not vanish automatically |
| Delete old set, then insert new | A maintenance gap is acceptable | Failure between steps can remove search coverage |
| Prepare version, then switch active reference | Search must continue during loading | All retrieval paths must honor active version |
These approaches solve different problems. A workflow that ends green may still leave obsolete chunks searchable or a new version only partly available. Define what a rollback means before changing the live base.
What n8n Update Documents actually changes
The n8n Supabase Vector Store node can update a vector-store item by its ID. That does not automatically replace every chunk derived from one source file. If a revision changes the file’s size or the splitter configuration, the number of chunks can change.
Updating the IDs you still know says nothing about old chunks no longer produced. Before a load, decide whether the job replaces the complete set, reconciles individual IDs, or keeps separate versions. Do not depend on an undocumented side effect of Update Documents.
Imagine a policy document that becomes shorter after a condition is removed. If the importer updates the chunks it can match and leaves an old chunk behind, the agent may still retrieve the deleted condition. The relevant test asks about that condition and inspects the returned chunk IDs and metadata; a successful load message is insufficient.
Upsert is not a delete-then-insert command
Supabase upsert uses conflict identity to insert or update rows sent to it. It does not remove rows omitted from the new payload. Deterministic IDs can make a retry recognize a row already processed, but they do not reconcile a chunk that the revised document no longer creates.
One design is to derive identity from tenant, file, version, and chunk, with a matching database constraint. Check how the chosen client exposes conflict handling and what happens under parallel jobs. This is an implementation choice, not an n8n setting that automatically appears when you name a metadata field.
If deletion is needed, target the exact tenant, file, and version. The Supabase delete reference describes filtered deletes. Preview which records the filter selects, preserve recovery data, and avoid an unbounded table delete. SQL on JSONB, REST parameters, and JavaScript client filters may have different syntax; use the mechanism supported by the node or documented API you actually call.
Why deleting the old version first can create a gap
Suppose a workflow deletes old vectors and then requests new embeddings. If the embedding service fails, retrieval may have no document. If insertion completes partly, the agent may see an incomplete set. Delete-then-insert can be suitable during a controlled maintenance window, but it is not universally the safest path.
For a small base with a planned pause, validate the new source before deletion, keep a restorable copy, and confirm the full load before reopening service. When an interruption is unacceptable, load the new version into a staging state that the production retriever cannot see yet.
A versioned design can store an active-version reference for each document. Generate chunks for the new version, verify count and content, then switch that reference. The query must combine tenant and document identity with the active version. Merely adding a version field to metadata does not switch search behavior.
PostgreSQL transactions can group database updates for commit or rollback. They do not make separate HTTP nodes or a call to an embedding provider part of the same transaction. Keep the external embedding work before the short database switch. If preparation fails, leave the prior version active.
Prevent an older job from finishing late and overwriting the active pointer after a newer job. Check the expected current version before switching and record which job made the change. This requires a deliberate concurrency rule in the database or service layer.
Retrieval must apply the same boundaries as loading
Supabase’s LangChain guide explains vector search through a configured matching function. Verify which metadata filters reach that function and how they are applied. A filter used during upload or cleanup does not ensure the agent’s retrieval path applies it.
In a shared base, isolate both reads and writes by tenant. Supabase documents Row Level Security and the role behavior around it. A tenant ID supplied by the model is not authorization. The application must derive the permitted tenant from the authenticated context and use appropriate database permissions.
Keep privileged credentials in the integration service, not in browser code. Check the role used by the retriever; administrative credentials may bypass the protection expected from table policies. Test whether a wrong metadata value can cause retrieval or deletion of another tenant’s record.
Review every search path: Get Many, chain retriever, agent tool, and custom SQL or API calls. A filter configured for one does not automatically propagate to the others. For each incoming support question, know which node searches and how it receives the authorized tenant and active version.
Build a controlled update flow
First, identify the tenant, source document, and change event. Compare hashes to detect repeated events and unchanged files. Extract text and generate chunks and embeddings with settings compatible with the search index. Store the new set under a pending version and record its job ID.
Next, compare expected and inserted chunk counts, inspect representative text, and run retrieval questions about changed and removed facts. Only then switch the active version through the chosen mechanism. Finally, remove old versions selectively under the business retention policy. Log each stage so a partial job is visible.
Treat removal of a source document as its own event. A temporarily incomplete file list or permission failure is not authorization to delete the base. Confirm the deletion source and the exact set affected. If an earlier version is kept for rollback, define its retention period and ensure ordinary retrieval no longer sees it.
Prove old material no longer appears in retrieval
Ask questions about changed facts, removed conditions, and information unique to the new version. Inspect retrieved chunk IDs and metadata as well as the final answer. A correct sentence might come from the model’s prior knowledge or conversation memory, and an old sentence may come from another store. The retrieval trace is the stronger evidence.
Test a repeated job, partial load, shorter document, concurrent update, and cross-tenant query. These are proposed tests, not measured outcomes here. Confirm that the old version stays active if preparation fails and that a retry does not duplicate the new set.
If the agent still mentions removed information, inspect its chat memory, cache, other tools, and document sources. Deleting a Supabase chunk does not erase text already in the current conversation context. Use a new conversation for the retrieval test and trace where each statement originated.
Make the acceptance check visible to the people who maintain the knowledge base. A short report can state the old and new version IDs, number of source files, expected and stored chunks, embedding configuration, test questions, retrieved IDs, active-version pointer, and cleanup result. Include the date, job owner, and any unresolved exception. If one of these fields is missing, mark the update incomplete rather than inventing a successful outcome. This record gives the next maintainer a way to compare a later problem with the exact state that was released.
Common questions
Does Update Documents replace a whole file?
The documented n8n operation updates a vector entry by ID. A file with several chunks needs set-level control, including records that no longer exist in the revised file.
Can I simply delete and insert the new version?
Yes, when an interim gap is acceptable and rollback is planned. It is not atomic merely because both calls sit in one workflow. For continuous service, prepare a version and switch a controlled active reference.
What does an update cost?
It depends on extraction, embedding provider, content volume, storage, and queries. Compare full regeneration with detecting unchanged files. No fixed price or measured saving is claimed here.
Make identity and retrieval part of the same design
Use per-ID updates for known entries, upsert for conflicts among sent rows, and selective deletion for obsolete records. When availability matters, prepare a new version and control when search can see it. The base is governable only when identity, retrieval, authorization, and rollback follow the same rules.
