> ## 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.
# Testing a knowledge base
> Test create, append, replace, delete, edit-metadata, and query operations against a knowledge base on a deployed build before running them in production.
The **Test Knowledge Base** modal lets you exercise content-management operations against a knowledge base on a deployed build, without modifying a workflow first. Use it to validate a knowledge base after deploy, to load initial content, or to investigate retrieval issues from a production knowledge base.
## Overview
Knowledge bases are populated and queried through workflows. The Test Knowledge Base modal gives you a direct, build-level UI for the same operations, so you can:
* Seed a newly created knowledge base with content immediately after deploy
* Append or replace store content without triggering a workflow run
* Spot-check what a query returns against the current knowledge base state
* Edit metadata on individual entries when a real-world correction is needed
All write actions performed from this modal are tagged with `source: manual` on the affected entries, so they remain distinguishable from workflow-driven changes.
## Opening the modal
Navigate to a project that has a knowledge base configured, and open the build where you want to test.
On the build, click the **play** button and select **Test Knowledge Base**.
In the modal header, open the knowledge base dropdown and select the knowledge base you want to act on. The dropdown lists both project knowledge bases and any knowledge bases referenced from libraries used by the build.
## Available actions
Six actions are available inside the modal. Each one is run by clicking **Test** after filling in the required fields.
### Create new store
Creates a new store in the selected knowledge base and ingests an initial document.
| Field | Description |
| -------------- | --------------------------------------------------------------------------------- |
| **Store name** | Required. Must be unique within the knowledge base. |
| **Upload** | Opens the file picker, filtered to PDF. |
| **Metadata** | Same metadata inputs available when uploading from the knowledge base admin view. |
If a store with the same name already exists, the modal shows the toast error "Store name already exists." and highlights the store-name input.
### Append to a store
Adds new content to an existing store, leaving prior chunks in place.
| Field | Description |
| -------------- | ------------------------------------------------------------------------------------ |
| **Store name** | Required. Searchable dropdown of existing stores. |
| **Type** | Either **From document** (PDF upload) or **From payload** (JSON in the code editor). |
| **Metadata** | Metadata values applied to the appended content. |
### Replace store content
Removes the existing content of a store and replaces it with new content.
| Field | Description |
| -------------- | ------------------------------------------------------- |
| **Store name** | Required. Searchable dropdown of existing stores. |
| **Type** | Either **From document** or **From payload**. |
| **Metadata** | New metadata values applied to the replacement content. |
Replace is destructive. All existing chunks in the store are removed before the new content is added.
### Delete a store
Removes a store from the knowledge base.
| Field | Description |
| -------------- | ------------------------------------------------- |
| **Store name** | Required. Searchable dropdown of existing stores. |
### Edit metadata values
Updates metadata values on individual entries inside a store.
Pick a store from the searchable dropdown. The entries of that store appear on the right side of the modal.
Click the entry you want to edit. Each entry card shows both user-defined and system metadata.
Use the metadata area on the left to update values. Metadata is grouped into two categories: **configured** (keys that already have a value) and **empty** (keys that have no value yet). When you populate an empty key and save, it moves to the configured category. The empty category is hidden when no keys remain in it.
Save commits the changes to the selected entry. Discard clears the selection and any unsaved edits. If you try to switch entries with unsaved changes, the modal prompts you to confirm.
Metadata **values** are editable, metadata **keys** are not. Adding, removing, or renaming a metadata key from the modal is intentionally not allowed because metadata filters elsewhere in the platform depend on the key set.
### Query
Runs a retrieval against the knowledge base and shows which chunks come back.
| Field | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Query** | Free-text query string. |
| **Metadata filters** | Advanced query builder over all metadata keys, including system metadata. Store-level filtering is expressed as a metadata filter. |
Use this to validate retrieval quality, debug an AI agent that is pulling unexpected chunks, or confirm that a recent ingestion is searchable.
## Reading the results
When you click **Test**, the modal header shows progress and an action-specific summary on completion.
| Action | Status header on completion |
| --------------------- | ----------------------------------------- |
| Create new store | `Created: [X] chunks` |
| Append to a store | `Appended: [X] chunks` |
| Replace store content | `Deleted: [X] chunks Added: [Y] chunks` |
| Delete a store | `Deleted: [X] chunks` |
| Query | (no count, retrieved chunks listed below) |
The chunks pane below the header reflects the action:
* **Create / Append** — new chunks are listed with a badge. For Append, new chunks appear at the top of the list, above pre-existing ones.
* **Replace** — only the new chunks are shown, each with a badge.
* **Delete** — the chunks area is empty.
* **Query** — retrieved chunks are listed without a badge.
Only the first **10 chunks** are shown in the preview. A disclaimer is rendered above the chunks list when the result set is truncated.
## Limitations
* The preview shows at most 10 chunks per action.
* Metadata keys cannot be added, removed, or edited from the modal — only values.
* File uploads accept PDF only.
* Edits made from this modal are tagged `source: manual` and remain distinguishable from workflow-driven changes.
## Related resources
Concepts, stores, chunks, and search modes.
Design-time UI for store management.
Query, append, and replace from inside a workflow.
Wire a knowledge base into an AI agent.