Node Identity
| Property | Value |
|---|
| Operations | insert, update, delete, query |
| Supported Backends | PostgreSQL + pgvector, Qdrant |
| Node Type | AI / Knowledge Store |
| Output Ports | success, error |
Common Properties
| Property | Required | Description |
|---|
credential_id | Required | Reference to the vector backend credential stored in BizFirst Credentials Manager. |
operation | Required | The operation to perform. |
collection_name | Required | Name of the vector collection (namespace) to operate on. Collections are created automatically on first insert. Use descriptive names like hr-policies, product-catalog, support-faqs. |
insert Properties
| Property | Required | Description |
|---|
knowledge_item | Required | The text content to embed and store. This is the knowledge that will be retrieved by future queries. Can be a paragraph, a FAQ entry, a policy section, or any meaningful text block. Supports expressions. |
item_id | Optional | Optional unique identifier for this knowledge item. If omitted, a UUID is auto-generated. Use a meaningful ID (e.g. policy-pto-v3) to enable targeted updates and deletes later. |
metadata | Optional | Key-value metadata tags attached to the knowledge item. Used for filtering during queries. Example: {"category": "hr", "department": "all", "effective_date": "2025-01-01", "version": "3"}. |
update Properties
| Property | Required | Description |
|---|
item_id | Required | The ID of the knowledge item to update. The item is re-embedded with the new text. |
knowledge_item | Required | The new text content. The existing embedding is replaced with a freshly generated embedding of this new text. |
metadata | Optional | Updated metadata. Replaces all existing metadata for the item. |
delete Properties
| Property | Required | Description |
|---|
item_id | Required | The ID of the knowledge item to permanently remove from the collection. |
query Properties
| Property | Required | Description |
|---|
query | Required | Natural language query string. FlowRag embeds this query and finds the most similar knowledge items using cosine similarity. Example: {{ vars.user_question }}. |
top_k | Optional | Number of most similar results to return. Default: 3. For most RAG use cases, 3–5 results provide sufficient context without overwhelming the AI prompt with irrelevant content. |
min_score | Optional | Minimum cosine similarity score (0.0–1.0). Results below this threshold are excluded. Default: 0.7. Higher values (e.g. 0.85) return only highly relevant results. Lower values return more but potentially less relevant content. |
metadata_filter | Optional | Optional metadata filter to restrict the search to a subset of documents. Example: {"category": "legal", "status": "active"}. Only items with exactly matching metadata are considered in the similarity search. |
Similarity Score Guide
| Score Range | Interpretation | Recommended Use |
|---|
| 0.90 – 1.00 | Near-identical or highly specific match | Exact document lookup, deduplication |
| 0.80 – 0.89 | Strongly relevant, on-topic match | Precise Q&A bots, policy compliance |
| 0.70 – 0.79 | Relevant, contextually related | General knowledge retrieval, FAQ |
| 0.60 – 0.69 | Loosely related, may include noise | Exploratory search, broad topic matching |
| Below 0.60 | Weak similarity | Not recommended — likely irrelevant results |
Optimal chunk size: For best retrieval quality, insert knowledge items as focused, single-topic paragraphs (200–500 tokens). Very long documents should be split into smaller, coherent chunks before insertion. Each chunk should stand alone as a meaningful, self-contained piece of information.
Embedding model consistency: All inserts and queries within a collection must use the same embedding model. Mixing models will produce incompatible vector spaces and incorrect similarity scores. The embedding model is configured globally in BizFirst AI settings, not per-node.
Metadata Design Patterns
Well-designed metadata enables powerful filtered queries that dramatically improve retrieval precision. Consider these metadata field patterns:
| Field Name | Example Values | Purpose |
|---|
category | hr, legal, product, support | Route queries to the right knowledge domain |
status | active, draft, deprecated | Filter out inactive content without deleting it |
department | all, engineering, sales | Personalise queries to the user's department |
version | 1, 2, 3 | Track policy/document version for compliance |
effective_date | 2025-01-01 | Allow date-based filtering for current policies |
source | confluence, sharepoint, manual | Track origin for audit and re-ingestion workflows |
language | en, de, fr | Multi-language knowledge bases — filter by user locale |
product | platform-v3, mobile-app | Scope support FAQs to the specific product variant |
Full Example — query with Metadata Filter
{
"credential_id": "pgvector-prod",
"operation": "query",
"collection_name": "hr-policies",
"query": "{@ $var.employeeQuestion }",
"top_k": 5,
"min_score": 0.75,
"metadata_filter": {
"status": "active",
"department": "{@ $var.employeeDepartment }",
"language": "{@ $var.userLocale }"
}
}
Full Example — insert with Rich Metadata
{
"credential_id": "pgvector-prod",
"operation": "insert",
"collection_name": "product-catalog",
"item_id": "product-{@ $var.productId }-features",
"knowledge_item": "{@ $var.productFeaturesText }",
"metadata": {
"category": "product",
"product_id": "{@ $var.productId }",
"product_name": "{@ $var.productName }",
"version": "{@ $var.productVersion }",
"status": "active",
"ingestion_date": "{@ $workflow.startedAt }",
"source": "pim-system"
}
}
Metadata values must be strings or simple scalars. Arrays and nested objects are not supported as metadata values in the current FlowRag implementation. If you need to store multi-value metadata (e.g. multiple tags), use a delimited string: "tags": "billing,account,upgrade" and filter with a contains check in a downstream IfCondition node after retrieval.
