Managing stores

Overview

Stores are the building blocks of a Knowledge Base. Each store represents a collection of related information that has been ingested, processed, and indexed for semantic search.

Store types

There are two types of stores:

Manual

Files uploaded directly through the Knowledge Base admin interface

Workflow

JSON content ingestion through workflows (planned for future release)

Viewing stores

Navigate to your Knowledge Base to see all stores. The Stores tab displays:

Store information

Each row shows:

string

Manual: Files uploaded in the Knowledge Base page
Workflow: Content ingestion through workflow variables (planned for future release)

string

The unique name of the store within the Knowledge Base

string

Current processing state:

New: Store created, awaiting content upload
Processing: Content is being uploaded, chunked, and indexed
Ready: Content is fully processed and available for queries
Failed: An error occurred during processing, or content is partially degraded

Status badges update in real-time — you don’t need to refresh the page to see status changes.

string

Username: For files uploaded in the Knowledge Base page
Workflow name: For content ingested through workflows (planned for future release)

timestamp

Timestamp of the last upload or workflow operation execution

Uploading documents

Navigate to Knowledge Base

Open your Knowledge Base in FlowX Designer and select the Stores tab.

Open the upload dialog

Click the + button in the top-right of the Stores tab. A file picker opens.

Select file

Choose a PDF file from your computer and click Open. The Upload Store modal appears.

Set the store name

The Name field is pre-filled with the file name (without extension). Edit it if needed — the name must be unique within the Knowledge Base.

Review metadata (optional)

The Metadata section shows the metadata schema defined for this Knowledge Base. If no metadata is defined, a “No metadata defined” placeholder appears — click Go to Metadata Setup to configure a schema on the Metadata tab before uploading. See User-defined metadata for details.

Upload

Click Upload to start the ingestion process. The store appears in the list with status Processing, and transitions to Ready once chunking and indexing complete.

File requirements

Supported formats (current release):

PDF files only

File size:

Maximum file size: 20 MB (can be changed using environment variables)

Future releases will support:

Images
PowerPoint presentations
Word documents
Excel spreadsheets

Each store operation takes one document or one payload. There is no multi-file selector and no folder-based ingestion, in the upload dialog or on the Update Knowledge Base node.To load a set of documents in one pass, see Ingesting many documents.

Store naming

When uploading a document, you must provide a unique store name:

Store name rules:

Must be unique within the Knowledge Base
Default name is the file name without extension
Choose descriptive names for easy identification
Consider using versioning in names (e.g., “Product Guide v2.1”)

Duplicate stores

If you select a file with the same name as an existing store, you’ll see a warning:

A Store with this name already exists. We recommend updating the existing store instead.

Available options:

Append Content: Add the new document’s content to the existing store
Replace Content: Replace the existing content with the new document
Cancel: Choose a different name or file

Adding content from a payload

SaaS ·

Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Besides uploading a file, you can add content to a store by pasting a payload — free text, Markdown, or JSON — directly into a code editor. This is useful for seeding or updating a store quickly without producing a file, for example pasting a documentation snippet, a block of guidelines, or a JSON blob. The store add flow has a Source toggle:

Document (default) — upload a file, as described above.
Payload — paste content into the editor.

Payload works for all three content operations — create, append, and replace — and is available both in the Knowledge Base admin (design time) and in the Data Sources Content view of a running app.

Switch Source to Payload

In the store’s add or update flow, set the Source toggle to Payload.

Paste the content

Enter text, Markdown, or JSON. JSON is not validated — content is accepted as-is.

Name the store (create only)

When creating a store, type a unique name. Append and replace derive the entry name automatically.

Submit

Content is processed and indexed asynchronously — the store shows Processing until Ready. Replacing a populated store asks for confirmation first, since it deletes existing content.

A payload is stored as plain text — wrapped into a text file and chunked like a document. JSON is kept as an opaque text blob, so it is not stored or queried field by field.

The store’s History distinguishes how each operation was performed — for example Append Content - Payload vs Append Content - Document.

Managing stores

Once content is uploaded and processed, you can perform the following operations:

Append content

Add new content to an existing store without removing the existing chunks.

Select store

Click on the store you want to update

Choose Append Content

Select the Append Content operation

Upload new file

Select a new PDF file with additional content

Confirm

The new content will be processed and added to the existing chunks

Use case: Adding a new chapter to existing documentation or supplementing information without losing the original content.

Replace content

Replace all existing content in a store with new content.

Select store

Click on the store you want to replace

Choose Replace Content

Select the Replace Content operation

Upload new file

Select a new PDF file that will replace the existing content

Confirm

All existing chunks will be deleted and new chunks will be created from the new content

Replace Content will permanently delete all existing chunks from the store. This operation cannot be undone.

Use case: Updating documentation to a new version where the old content is no longer relevant.

Delete store

Remove a store and all its associated chunks from the Knowledge Base.

Select store

Click on the store you want to delete

Choose Delete

Select the Delete Store operation

Confirm deletion

Confirm that you want to permanently delete the store

Deleting a store will:

Remove all chunks generated from that content
Remove the store’s embeddings from the vector database (removal is asynchronous and may take a few moments to complete)
Permanently delete the content from the Knowledge Base
This operation cannot be undone

Delete entries

SaaS ·

Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

Remove individual chunks and entries from a store by matching their metadata, without deleting the whole store. This is a workflow-driven operation on the Update Knowledge Base node, useful when you need to retire a subset of content (for example, entries for a region or a document version) while keeping the rest of the store intact.

Add an Update Knowledge Base node

In your workflow, add an Update Knowledge Base node and select the target Knowledge Base and store.

Choose Delete entries

Set the operation to Delete entries.

Build the metadata filter

Define a metadata filter that matches the entries you want to remove. The filter uses the same query builder as chunk search (field / operator / value, grouped with AND / OR). See Filtering by metadata for the operator list.

Confirm

Matching entries and their chunks are soft-deleted from the store. Removal from the vector database is asynchronous and may take a few moments to complete.

A Delete entries operation requires a non-empty metadata filter. An empty or match-all filter is rejected, so a mis-configured node cannot wipe an entire store or Knowledge Base by accident.

Use case: Removing entries for a specific document version, region, or department while keeping the rest of the store’s content available for retrieval.

Update Knowledge Base node failure handling

SaaS ·

Available on SaaS with FlowX.AI . This feature is live on managed (SaaS) deployments now. Self-hosted deployments will receive it with the next LTS release family.

When an Update Knowledge Base operation fails during a workflow run, the platform rolls back any partial changes and routes the node to its FAIL branch with a structured error payload. Nothing is left half-applied: the store returns to the state it was in before the operation started. The error payload is available on the FAIL branch (in paramValues) and in the workflow run console. It carries the following keys:

Key	Description
`error`	Human-readable message: “The operation [<operation>] on store [<store>] failed. Any partial changes were reversed.”
`operation`	The operation that failed: `APPEND`, `REPLACE`, `DELETE`, or `DELETE_ENTRIES`
`storeName`	The name of the store the operation targeted
`errorReason`	A machine-readable reason (see table below)
`chunksRolledBack`	The number of chunks reverted by the rollback

Use errorReason to branch your workflow’s error handling:

`errorReason`	Meaning	Automatically retried
`size_exceeded`	The content exceeded the allowed size	No
`extraction_failed`	Text could not be extracted from the document	Yes
`chunking_failed`	The content could not be chunked or embedded	Yes
`timeout`	The operation did not complete in time	No
`unknown`	The cause could not be determined	Yes

When an operation is automatically retried, the console shows a retry notification with the original error and a “Retrying [<operation>] on store [<store>].” message.

Retryable reasons (extraction_failed, chunking_failed, unknown) are retried automatically before the node fails. Non-retryable reasons (size_exceeded, timeout) route to the FAIL branch immediately.

Ingesting many documents

Each Update Knowledge Base execution ingests a single document or payload, so loading a set of documents means running the node once per file. Collect the files first, then fan out.

Collect the files in one action

Add a Multiple File Upload component to the screen where the documents are submitted. It uploads the whole selection in a single request and writes the per-file results back as a list.

Fan out over the list

Add a Call Activity node in parallel multi-instance mode and set that list as its input array. One subprocess instance starts per element.The input array must be an array of objects — the per-file result list qualifies, a plain list of path strings does not, and only arrays of objects appear in the Input Array picker. Map the fields you need into the subprocess in the node’s Data Mapping section: a child that receives no mapping knows only its position in the collection, not which file it is handling.

Ingest one file per instance

In the subprocess, call the workflow that holds the Update Knowledge Base node and pass it the single file path from item. Use Append Content so every instance adds to the same store.

If the documents already sit in object storage, you can skip the upload step: set the node’s File Source to S3 Protocol and drive the same fan-out from your own list. Build it as an array of objects, one per file carrying its path, so the Call Activity can bind it as an input array.

A wide fan-out issues many concurrent append operations against one store. Start with a small set to confirm the mapping before scaling up, and handle per-instance errors on the node’s FAIL branch — a subprocess that ends any way other than reaching an end node never reports back to its parent.

Emptying a knowledge base

Stores are the unit of deletion: there is no bulk operation that clears all content from a Knowledge Base at once. To empty a Knowledge Base while keeping it available for re-ingestion, delete each of its stores individually. You can automate this from a workflow with the Update Knowledge Base node using the Delete operation.

Deleting the Knowledge Base data source itself does not remove content that was already ingested. To remove a Knowledge Base completely, delete all of its stores first, then delete the data source.

Stores and version export

Store contents stay on the workspace where they were ingested. A project version export carries the Knowledge Base data-source definition (system, endpoints, metadata keys), but not the stores’ documents or their indexed embeddings. After importing the version on another workspace or environment, the Knowledge Base appears with empty stores — upload the content again there to rebuild the index. See Export/import a project for the full export behavior.

Store states

Stores progress through different states during their lifecycle. Status badges update in real-time — you don’t need to refresh the page to see transitions.

New

The initial state after content is uploaded to the Knowledge Base. What’s happening:

File has been transferred to the FlowX platform
Content is being validated and queued for processing

Duration: Usually a few seconds, depending on file size

Processing

Content is being chunked, embedded, and indexed in the vector database. What’s happening:

Content is being extracted from the document
Text is being split into semantically meaningful chunks
Chunks are being embedded and indexed in the vector database

Duration: Can take from seconds to minutes depending on content size

Ready

Store is fully processed and available for queries. What you can do:

Query the store in AI agents
View individual chunks
Append or replace content
Delete the store

Failed

An error occurred during processing, or the store is partially degraded. What to do:

Check the error message in the Store History modal
Verify the file format and content
Retry the operation

Error handling

When processing fails, the store will show a warning indicator.

Error states and recovery

Upload failed

Cause: File upload was interrupted or the file format is invalidSolution:

Verify the file format (must be PDF)
Check your network connection
Try uploading again

Chunking failed

Cause: Error occurred while processing the contentSolution:

Check the Store History for specific error details
Verify the file is not corrupted
Contact support if the issue persists

Retry behavior

When retrying a failed operation:

Any chunks already created will be deleted
The content will be processed entirely from the beginning
No duplicate chunks will be created

Warning indicators

When a store has a failed update:

Yellow warning icon appears on the store row
Tooltip message: “Last Store update failed. Check history.”
Dismiss trigger: The warning is automatically dismissed after a successful update

Viewing store history

Store History is a low-priority feature that may be available in future releases.

Store History will show all operations performed on a store:

Operation	Description
Upload Document	Creates store and inserts content
Append Content	Adds new content to existing chunks
Replace Content	Deletes existing content and inserts new content
Delete Store	Removes the store and all chunks

Each history entry will include:

Timestamp
User or workflow name
Operation type (Manual/Workflow/Test)
Operation performed
View option (for uploaded files or JSON payloads)

Working with chunks

Chunks are the individual pieces of content that AI agents query. To view and test chunks:

Navigate to Chunks tab

Click the Chunks tab in your Knowledge Base

Search chunks

Enter a query to search for relevant chunks

Filter results

Apply filters to refine the search results

Review chunks

Examine the returned chunks, their relevance scores, and metadata

Chunk information

Each chunk displays:

percentage

How relevant the chunk is to your query (0-100%)

string

The store that generated this chunk (clickable link)

link

Link to the original document or JSON payload that created this chunk

text

The actual text content of the chunk

object

System metadata associated with the chunk:

source: manual_upload or from_workflow
path: Document filepath or JSON payload
chunk_id: UUID from the vector database
knowledge_base: Knowledge Base ID

User-defined metadata keys (if configured) are also included.

User-defined metadata

You can define custom metadata keys on a Knowledge Base and assign values to stores. User-defined metadata enables filtering and scoping when searching chunks — for example, filtering by department, document version, or region.

Defining metadata keys

Metadata keys are managed on the Metadata tab of the Knowledge Base data source.

To add a key, click Add Metadata Key and fill in the following fields:

Field	Description
Name	Unique key name. Cannot be changed after creation.
Type	Data type: `String`, `Number`, `Boolean`, `Enum`, or `Date`. Cannot be changed after creation.
Enum values	Allowed values (only visible when Type is `Enum`). Values defined at creation cannot be removed.
Description	Optional free-text description of the key’s purpose.

Name and type are locked after a key is saved. Only description and enum values (additions only) can be updated later.

Assigning metadata values

When uploading or appending a store (manually or through the Update Knowledge Base workflow node), a Metadata section appears in the upload modal listing all defined keys for the Knowledge Base. Assign a value to each relevant key before uploading. The values are stored alongside the content and propagated to the vector database.

Filtering by metadata

When searching chunks (in the Chunks tab or through the Context Retrieval workflow node), you can add metadata filters using the query builder. System metadata keys are always available as filter options alongside any user-defined keys.

The metadata filter UI is a full query builder with typed operators, AND/OR logic, and grouping.

System metadata keys

System metadata keys are reserved names populated automatically by the platform. They are listed in the filter picker with human-readable labels and can be combined with user-defined keys.

Key	Type	Scope	Description
`source`	Enum	Entry	How the entry was added: `manual_upload`, `from_workflow`, `test_operation`
`uploaded`	Date	Entry	UTC timestamp set when the entry was added to the Knowledge Base
`docName`	String	Entry	File name of the uploaded document
`docType`	Enum	Entry	Document type derived from the file extension, lower-cased (starter values include `pdf`, `xlsx`, `docx`, `txt`)
`docPages`	Number	Entry	Total page count, reported once document parsing completes (a re-index refreshes the value)
`storeOrigin`	String	Entry	Name of the store the entry was added to
`chunkCounter`	Number	Chunk	Sequential position of the chunk within its source document
`chunkType`	Enum	Chunk	Structural element the chunk was extracted from (starter values include `table`, `header`, `section_header`, `picture`, `paragraph`)
`chunkSection`	String	Chunk	Document section heading the chunk belongs to
`chunkPageStart`	Number	Chunk	Page number where the chunk starts in the source document
`chunkEntry`	String	Chunk	Document name of the entry the chunk belongs to (equivalent to `docName`)

If a user-defined metadata key collides with a reserved system name, it is automatically renamed to <name>_user on upgrade. Wire-level identifiers stay plain; the filter picker shows human labels (for example, Doc type for docType).

Filters are expressed as conditions made of field / operator / value. Each condition uses operators appropriate to the metadata key’s type:

Type	Available operators
String	equals, not equals, contains, starts with, ends with, matches regex, in, not in, exists, is null
Number	equals, not equals, greater than, greater or equal, less than, less or equal, between, in, exists, is null
Boolean	is true, is false, exists
Date	equals, before, after, between, exists, is null
Enum	equals, not equals, in, not in, exists

Conditions are organized in groups. Within a group, conditions can be combined with and or or. Groups themselves are also combined with and or or, which lets you express non-trivial logic such as (region = "EU" AND tier IN ["gold", "platinum"]) OR priority >= 5. Use New Filter to add a condition and New Group to add a nested group.

Searching chunks

Use the Chunks tab to test how chunks will be retrieved by AI agents:

string

Filter by a specific store. Default: all stores

string

Enter a natural language question or search query

select

Strategy used for retrieving context:

Hybrid (default) — combines semantic and keyword search
Semantic — vector similarity only
Keywords — lexical match only (hides Min. Relevance Score)

number

Maximum number of chunks to return. Range: 1-10. Default: 4.

percentage

Only return chunks with relevance score above this threshold. Range: 0-100%. Hidden when Search Type is Keywords.

boolean

Reorders results to surface the best matches. Improves quality but takes slightly longer.

object

Refine results using the query builder (see Filtering by metadata)

Use chunk search to understand what information AI agents will receive for different queries. This helps you optimize your Knowledge Base content and structure.

Best practices

Content organization

Organize by topic or version:

Create separate stores for different topics
Use versioning in store names (e.g., “User Guide v1.0”, “User Guide v2.0”)
Group related documents in the same store using Append Content

Content updates

Choose the right operation:

Use Append Content when adding supplementary information
Use Replace Content when updating to a new version
Test queries after updates to verify the changes work as expected

Error prevention

Avoid common errors:

Ensure PDF files are not corrupted before uploading
Use unique, descriptive names for stores
Monitor the status of stores during processing
Check Store History when errors occur

Next steps

Using in Workflows

Learn how to query Knowledge Bases from workflows

Knowledge Base Overview

Understanding Knowledge Base capabilities

​Overview

​Store types

Manual

Workflow

​Viewing stores

​Store information

​Uploading documents

​File requirements

​Store naming

​Duplicate stores

​Adding content from a payload

​Managing stores

​Append content

​Replace content

​Delete store

​Delete entries

​Update Knowledge Base node failure handling

​Ingesting many documents

​Emptying a knowledge base

​Stores and version export

​Store states

​New

​Processing

​Ready

​Failed

​Error handling

​Error states and recovery

​Warning indicators

​Viewing store history

​Working with chunks

​Chunk information

​User-defined metadata

​Defining metadata keys

​Assigning metadata values

​Filtering by metadata

System metadata keys

​Searching chunks

​Best practices

​Content organization

​Content updates

​Error prevention

​Next steps

Using in Workflows

​Related resources

Knowledge Base Overview

Overview

Store types

Viewing stores

Store information

Uploading documents

File requirements

Store naming

Duplicate stores

Adding content from a payload

Managing stores

Append content

Replace content

Delete store

Delete entries

Update Knowledge Base node failure handling

Ingesting many documents

Emptying a knowledge base

Stores and version export

Store states

New

Processing

Ready

Failed

Error handling

Error states and recovery

Warning indicators

Viewing store history

Working with chunks

Chunk information

User-defined metadata

Defining metadata keys

Assigning metadata values

Filtering by metadata

Searching chunks

Best practices

Content organization

Content updates

Error prevention

Next steps

Related resources