> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing stores

> Learn how to upload documents, manage stores, and work with chunks in FlowX Knowledge Bases.

## 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:

> [card] Manual
>
> Files uploaded directly through the Knowledge Base admin interface

> [card] Workflow
>
> Content added from a workflow through the **Update Knowledge Base** node: a file path or a pasted payload

## Viewing stores

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

![Stores List](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_stores.png)

### Store information

Each row shows:

**Type** `string`

* **Manual**: Files uploaded in the Knowledge Base page
* **Workflow**: Content added from a workflow through the **Update Knowledge Base** node
* **Test Operation**: Content created from the **Test Knowledge Base** modal

**Store** `string`

The unique name of the store within the Knowledge Base

**Status** `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.

**Updated by** `string`

* **Username**: For files uploaded in the Knowledge Base page
* **Workflow name**: For content ingested through workflows

**Updated at** `timestamp`

Timestamp of the last upload or workflow operation execution

## Uploading documents

**1. Navigate to Knowledge Base**

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

**2. Open the upload dialog**

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

**3. Select file**

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

**4. 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.

**5. 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](#user-defined-metadata) for details.

**6. 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.

![Upload Store modal with Name field and Metadata section](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/upload-store.png)

### File requirements

> [!WARNING]
>
> **Supported formats:**
>
> * PDF files
>
> **File size:**
>
> * Maximum file size: 20 MB (can be changed using environment variables)
>
> **Future releases will support:**
>
> * Images
> * PowerPoint presentations
> * Excel spreadsheets

#### Word document support

Word documents (`.docx`) can also be uploaded as stores, and are chunked and indexed the same way as PDFs. This applies to store uploads in the Designer; the **Test Knowledge Base** modal accepts PDF only — see [Testing the Knowledge Base](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/testing-knowledge-base.md).

> [!NOTE]
>
> 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](#ingesting-many-documents).

### Store naming

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

> [!TIP]
>
> **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

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 in [Uploading documents](#uploading-documents).
* **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.

**1. Switch Source to Payload**

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

**2. Paste the content**

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

**3. Name the store (create only)**

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

**4. 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.

> [!NOTE]
>
> 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:

![Manage Stores](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/content_ops.png)

### Append content

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

**1. Select store**

Click on the store you want to update

**2. Choose Append Content**

Select the **Append Content** operation

**3. Upload new file**

Select a new PDF file with additional content

**4. 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.

**1. Select store**

Click on the store you want to replace

**2. Choose Replace Content**

Select the **Replace Content** operation

**3. Upload new file**

Select a new PDF file that will replace the existing content

**4. Confirm**

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

> [!WARNING]
>
> **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.

**1. Select store**

Click on the store you want to delete

**2. Choose Delete**

Select the **Delete Store** operation

**3. Confirm deletion**

Confirm that you want to permanently delete the store

> [!WARNING]
>
> 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

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.

**1. Add an Update Knowledge Base node**

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

**2. Choose Delete entries**

Set the operation to **Delete entries**.

**3. 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](#filtering-by-metadata) for the operator list.

**4. 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.

> [!WARNING]
>
> 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.

### How do I disable, re-activate, or permanently delete an entry?

Open the menu on an entry in a store to manage it from FlowX Designer:

* **Disable Entry**: takes a ready entry out of retrieval while keeping it in the store. The entry card shows a **Disabled** tag, and the store list shows how many entries are disabled. Entries removed by a **Delete entries** operation show as disabled too.
* **Activate Entry**: puts a disabled entry back into retrieval.
* **Permanent delete**: removes the entry, its indexed content, and its source document. FlowX Designer asks you to confirm with **Delete**, and the action can't be undone. It isn't available while the entry is still being indexed.

Disable and activate apply in one click, without a confirmation, because each reverses the other. The actions you see depend on your access rights on the Knowledge Base.

### Update Knowledge Base node failure handling

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.

> [!NOTE]
>
> 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.

**1. Collect the files in one action**

Add a [Multiple File Upload](https://docs.flowx.ai/6.x/docs/building-blocks/ui-designer/ui-component-types/multiple-file-upload.md) 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.

**2. Fan out over the list**

Add a [Call Activity](https://docs.flowx.ai/6.x/docs/building-blocks/node/call-subprocess-tasks/call-activity-node.md) 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.

**3. 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.

> [!TIP]
>
> 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.

> [!WARNING]
>
> 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](#update-knowledge-base-node-failure-handling) — 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.

> [!WARNING]
>
> 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](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition.md) 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:**

1. Check the error message in the Store History modal
2. Verify the file format and content
3. Retry the operation

![Failed State](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/console_history.png)

## Error handling

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

### Error states and recovery

> [accordion] Upload failed
>
> **Cause:** File upload was interrupted or the file format is invalid
>
> **Solution:**
>
> * Verify the file format is supported — see [File requirements](#file-requirements)
> * Check your network connection
> * Try uploading again

> [accordion] Chunking failed
>
> **Cause:** Error occurred while processing the content
>
> **Solution:**
>
> * Check the Store History for specific error details
> * Verify the file is not corrupted
> * Contact support if the issue persists

> [accordion] 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 lists every operation performed on a store. Open it from the store's actions menu with **View History**.

| Operation | Description |
| - | - |
| Create KB Store | Creates the store and inserts content |
| Append Content | Adds new content to existing chunks |
| Replace Content | Deletes existing content and inserts new content |
| Delete KB Store | Removes the store and all chunks |
| Update Content Metadata | Changes an entry's metadata values |

Each history entry includes:

* Timestamp
* User
* Type (Manual/Workflow/Test Operation)
* Operation performed
* Updated By (user or workflow name)
* Operation Status

## Working with chunks

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

**1. Navigate to Chunks tab**

Click the **Chunks** tab in your Knowledge Base

**2. Search chunks**

Enter a query to search for relevant chunks

**3. Filter results**

Apply filters to refine the search results

**4. Review chunks**

Examine the returned chunks, their relevance scores, and metadata

![Chunks](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_chunks.png)

### Chunk information

Each chunk displays:

**Relevance Score** `percentage`

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

**Store** `string`

The store that generated this chunk (clickable link)

**Submitted Content** `link`

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

**Chunk Content** `text`

The actual text content of the chunk

**Chunk Metadata** `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.

![Metadata tab](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/kb_metadata.png)

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. |

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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`) |

> [!NOTE]
>
> 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:

**Store** `string`

Filter by a specific store. Default: all stores

**Query Prompt** `string`

Enter a natural language question or search query

**Search Type** `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**)

**Max. Number of Results** `number`

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

**Min. Relevance Score** `percentage`

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

**Use Re-rank** `boolean`

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

**Metadata Filters** `object`

Refine results using the query builder (see [Filtering by metadata](#filtering-by-metadata))

> [!TIP]
>
> 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

> [!TIP]
>
> **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

> [!TIP]
>
> **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

> [!TIP]
>
> **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

> [card] [Using in Workflows](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows.md)
>
> Learn how to query Knowledge Bases from workflows

## Related resources

> [card] [Knowledge Base Overview](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview.md)
>
> Understanding Knowledge Base capabilities


## Related topics

- [Testing a knowledge base](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/testing-knowledge-base.md)
- [Using Knowledge Base in workflows](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/using-knowledge-base-in-workflows.md)
- [Knowledge Base integration](https://docs.flowx.ai/6.x/docs/platform-deep-dive/integrations/knowledge-base-integration/knowledge-base-overview.md)
- [Exporting and importing projects](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition.md)
- [FlowX.AI 5.11.0 Release Notes](https://docs.flowx.ai/release-notes/v5.x/v5.11.0-august-2026/v5.11.0-august-2026.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.