FlowRag — knowledge/update

When to Use

Policy revision: When a policy document is updated, call knowledge/update to replace the old embedding with the revised text. The knowledge base reflects the change immediately without re-seeding the entire collection.
Product description refresh: When product features, pricing, or descriptions change, update the corresponding knowledge item so AI agents always reference current product information.
Content correction: If an inserted document contained errors, update it with the corrected text rather than deleting and re-inserting — the operation is atomic and preserves your source system's reference via the returned newKnowledgeId.
Versioned content management: Use update in a publish workflow whenever a document reaches a new approved version, ensuring the knowledge base is always in sync with the latest approved content.

Update is replace, not patch: The knowledge/update operation removes the existing embedding and stores a completely new one from the provided content. It is not an in-place patch of specific fields. Always provide the full replacement text, not just the changed portion.

Save the new knowledgeId: The operation returns a newKnowledgeId that replaces the oldKnowledgeId in the vector store. Update your source system's reference to the new value after each update — subsequent delete or update operations must use the new GUID.

Configuration

Connection

Field	Required	Description
`providerName`	Required	Vector store provider. One of: `pinecone`, `weaviate`, `chroma`, `qdrant`, `pgvector`. Must match the provider used at insert time.
`collectionName`	Required	Collection name containing the document to update. Must match the collection used at insert time.
`credentialId`	Optional	Credential ID for the vector store, stored in the BizFirst Credentials Manager.
`embeddingProvider`	Optional	LLM provider for re-embedding, e.g. `openai`. Must match the model used at insert time.
`embeddingCredentialId`	Optional	Credential ID for the embedding model API key.
`embeddingModel`	Optional	Embedding model, e.g. `text-embedding-3-small`. Must be the same model used when the document was first inserted.

Operation

Field	Required	Description
`knowledgeId`	Required	GUID of the document to replace. Must be a valid UUID returned by the original `knowledge/insert` or a previous `knowledge/update`. Supports `{{ expressions }}`.
`content`	Required	Full replacement text to embed and store. Supports `{{ expressions }}`. Must be the complete new content — partial updates are not supported.
`fileName`	Optional	Updated filename for the document, e.g. `hr-pto-policy-2026.pdf`. If omitted, the previous filename is replaced with an empty value.
`source`	Optional	Updated source URL or file path. If omitted, the previous source is replaced with an empty value.

Sample Configuration JSON

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "update",
  "providerName": "qdrant",
  "collectionName": "hr-policies",
  "credentialId": "88",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "knowledgeId": "{{ $db.policyRecord.ragKnowledgeId }}",
  "content": "{{ $input.updatedPolicyText }}",
  "fileName": "{{ $input.fileName }}",
  "source": "{{ $input.sourceUrl }}"
}

Validation Errors

Error	Cause
`collectionName is required`	`collectionName` is empty or missing.
`providerName is required`	`providerName` is empty or missing.
`knowledgeId is required`	`knowledgeId` is empty after expression evaluation.
`content is required`	`content` is empty after expression evaluation.
`knowledgeId is not a valid GUID: '...'`	`knowledgeId` is not a valid UUID string. Verify it was taken directly from the original insert or update output.

Output

Success Port

Field	Type	Description
`oldKnowledgeId`	string (GUID)	The GUID of the document before the update. The old embedding has been removed from the vector store.
`newKnowledgeId`	string (GUID)	The GUID of the replacement document. Update your source system to reference this new value for all future operations.
`collection`	string	The collection where the update was applied.
`chunkCount`	number	Number of embedding chunks created from the new content.
`status`	string	`"success"`
`errorMessage`	string	Empty on success.

Error Port

Fires when the update fails. Common causes: document not found, vector store unreachable, invalid credentials, embedding API error, or malformed GUID.

Field	Type	Description
`oldKnowledgeId`	string (GUID)	The GUID that was supplied to the update operation.
`newKnowledgeId`	string (GUID)	Empty GUID (`00000000-0000-0000-0000-000000000000`) when the update failed — no new document was created.
`collection`	string	The collection that was targeted.
`chunkCount`	number	`0` on error.
`status`	string	`"error"`
`errorMessage`	string	Human-readable error description from the vector store or embedding provider.

Sample Output JSON

Success

{
  "oldKnowledgeId": "a3f2c1d4-8e5b-4a90-b231-7c6e9f12d847",
  "newKnowledgeId": "f9e1b2c3-4d5a-6f78-901b-2c3d4e5f6a7b",
  "collection": "hr-policies",
  "chunkCount": 2,
  "status": "success",
  "errorMessage": ""
}

Error

{
  "oldKnowledgeId": "a3f2c1d4-8e5b-4a90-b231-7c6e9f12d847",
  "newKnowledgeId": "00000000-0000-0000-0000-000000000000",
  "collection": "hr-policies",
  "chunkCount": 0,
  "status": "error",
  "errorMessage": "Document 'a3f2c1d4-8e5b-4a90-b231-7c6e9f12d847' not found in collection 'hr-policies'."
}

Expression Reference

Expression	Returns
`{{ $output.updateNode.newKnowledgeId }}`	New GUID of the replacement document. Persist this to replace the old reference.
`{{ $output.updateNode.oldKnowledgeId }}`	Old GUID of the replaced document (now removed from the vector store).
`{{ $output.updateNode.collection }}`	Collection name where the update was applied.
`{{ $output.updateNode.chunkCount }}`	Number of embedding chunks created from the new content.
`{{ $output.updateNode.status }}`	`"success"` or `"error"`.
`{{ $output.updateNode.errorMessage }}`	Error description on failure, empty on success.

Node Policies & GuardRails

Policy	Detail
GUID format validation	The `knowledgeId` is validated as a well-formed UUID before any request is sent to the vector store. Invalid GUIDs fail at the validation stage with a descriptive error message.
Atomic replace semantics	The old document is deleted and the new document is inserted as a single logical operation. If the new embedding fails (e.g. embedding API error), the operation fails to the error port and the old document state is preserved where possible, depending on the vector store provider's atomicity guarantees.
Embedding model consistency	Use the same embedding model as the original insert. Switching models within a collection is not supported without re-seeding all items. Mismatched embeddings corrupt similarity scoring.
newKnowledgeId rotation	Every successful update produces a new GUID. Always update the `knowledgeId` reference in your source system after each update. Using a stale GUID in a subsequent update or delete will fail with a "document not found" error.
Collection scoping	The update targets only the specified collection. A document in a different collection with the same GUID is not affected.
Credential isolation	Both vector store and embedding API keys are resolved from the BizFirst Credentials Manager. Raw credentials are never stored in node configuration.
Audit logging	Every update operation is logged with timestamp, collection, old GUID, new GUID, chunk count, and executor identity for compliance and change tracking.

Examples

Example 1 — Policy Annual Review Update

An annual review workflow fetches the updated policy text from the CMS and updates the knowledge base. A downstream node updates the stored knowledgeId in the database.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "update",
  "providerName": "pgvector",
  "collectionName": "company-policies",
  "credentialId": "55",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "knowledgeId": "{{ $db.policyRecord.ragKnowledgeId }}",
  "content": "{{ $cms.policy.revisedBody }}",
  "fileName": "{{ $cms.policy.fileName }}",
  "source": "{{ $cms.policy.canonicalUrl }}"
}

After success, a DataMapping node writes {{ $output.updateNode.newKnowledgeId }} back to the database policy record, replacing the old GUID reference.

Example 2 — Product Description Refresh on Catalogue Change

A webhook fires when a product is edited in the e-commerce platform. The workflow fetches the new description and updates the knowledge item.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "update",
  "providerName": "qdrant",
  "collectionName": "product-catalogue",
  "credentialId": "88",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "knowledgeId": "{{ $trigger.product.ragKnowledgeId }}",
  "content": "Product: {{ $trigger.product.name }}. Category: {{ $trigger.product.category }}. Description: {{ $trigger.product.description }}. Price: {{ $trigger.product.price | currency('USD') }}.",
  "fileName": "product-{{ $trigger.product.id }}.txt",
  "source": "https://store.acme.com/products/{{ $trigger.product.slug }}"
}

AI recommendation agents immediately retrieve the updated embedding on the next query, with no manual re-indexing required.

Example 3 — Support Article Correction

A support team member flags an article with incorrect troubleshooting steps. A correction workflow updates the knowledge item with the fixed content.

{
  "nodeType": "flow-rag",
  "resource": "knowledge",
  "operation": "update",
  "providerName": "pinecone",
  "collectionName": "support-articles",
  "credentialId": "101",
  "embeddingProvider": "openai",
  "embeddingCredentialId": "12",
  "embeddingModel": "text-embedding-3-small",
  "knowledgeId": "{{ $form.articleKnowledgeId }}",
  "content": "{{ $form.correctedArticleBody }}",
  "fileName": "{{ $form.articleFileName }}",
  "source": "{{ $form.articleUrl }}"
}

The success port output's newKnowledgeId is saved back to the Zendesk article's custom field, and an audit note is added recording the correction date and operator.