Knowledge Bases

Orq.ai provides two approaches to backing an agent with persistent knowledge, plus entity-scoped Memory Stores for cross-session recall:

Create a Knowledge Base

Upload and index documents for retrieval-augmented generation. Ground model responses in domain data.

External Knowledge Bases

Connect an existing vector database via a standard API. Keep data management on the existing infrastructure.

Use Cases

Both Knowledge Base approaches store information that an agent can retrieve, but they serve different purposes depending on where the data lives and how it changes. For entity-scoped memory that persists across sessions, see Memory Stores. Knowledge Bases index documents uploaded into Orq.ai. The platform handles embeddings, chunking, and retrieval. Use when a fully managed RAG pipeline is needed. External Knowledge Bases connect to an existing vector database. Orq.ai calls the database API at query time and passes the results to the model. Use when data cannot leave existing infrastructure, or an embedding pipeline is already in place.

	Knowledge Base	External Knowledge Base
Data hosted by	Orq.ai	Customer infrastructure
Document upload	Via Studio or API	Managed externally
Embeddings	Managed by Orq.ai	Managed externally
Search config	Full control	Delegated to the external API
Reranking	Supported	Post-processing
Agentic RAG	Supported	Supported
Metadata filtering	Full support	Depends on the external API
Scoped per entity	No	No
Persists across sessions	Yes (static content)	Yes (static content)
Best for	Domain documents, FAQs, policies	Existing vector DBs

A Knowledge Base is a database that provides relevant, specific information for an LLM to retrieve at query time. Knowledge can include domain-specific or business-specific information, ensuring the details surfaced to models are both correct and accurate.

Create a Knowledge Base

AI Studio
API & SDK
CLI

Use the button in a chosen Project and select Knowledge Base > Internal.Press Create Knowledge. The following modal appears:

Enter a unique Key used to reference your Knowledge Base within Prompts and Deployments. Choose an Embedding Model for knowledge search.

You can only create a Knowledge Base once you have activated an embedding model within the AI Gateway.

Use the Create a Knowledge API.Required inputs:

key: the name used to reference the Knowledge Base
embedding_model: formatted as supplier/model_name, for example cohere/embed-english-v3.0. Find embedding models in the AI Gateway by filtering for Model Type = Embedding.
path: the Project and folder, formatted as project/path, for example Default/Production

curl --request POST \
     --url https://api.orq.ai/v2/knowledge \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --data '
{
  "key": "<key>",
  "embedding_model": "<model>",
  "path": "<path>",
  "type": "internal"
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create(request={
        "key": "key",
        "embedding_model": "supplier/model",
        "path": "project/path",
        "type": "internal"
    })

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.create({
  key: "key",
  embeddingModel: "supplier/model",
  path: "project/path",
  type: "internal",
});

console.log(result);

Save the knowledge_id returned from the response.

orq knowledge-bases create \
  --key <key> \
  --embedding-model <model> \
  --path <path> \
  --type internal

See install and setup to get started with the CLI. Run orq knowledge-bases create --help for the full flag reference.

Datasource and Chunking

A source represents a document loaded within the Knowledge Base. Documents are parsed and split into chunks that models search and retrieve at query time.

Create a Datasource

AI Studio
API & SDK
CLI

Select Add Source to upload a document. Supported formats: TXT, PDF, DOCX, CSV, XML.

Datasources list view showing uploaded datasources with their processing status and an Add Datasource button.

A single source document must be a maximum of 10MB.

Once your document has been processed, the following summary is displayed:

See details of the data parsed into your Knowledge Base and estimate the cost of retrieval.

The most common workflow is uploading a file before creating a datasource. Use the Upload a file API. For the full file lifecycle, see the Files API.

The maximum file size is 10MB.

curl --request POST \
     --url https://api.orq.ai/v2/files \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form file='@file_path'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.files.create(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

    print(res)

import { Orq } from "@orq-ai/node";
import { openAsBlob } from "node:fs";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.files.create({
  file: await openAsBlob("example.file"),
});

console.log(result);

Save the file_id returned from the response, then create a datasource with the Create a datasource API.Required fields: knowledge_id, display_name, and optionally file_id to pre-populate the datasource.

curl --request POST \
     --url https://api.orq.ai/v2/knowledge/knowledge_id/datasources \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "display_name": "name",
  "file_id": "file_id"
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_datasource(knowledge_id="knowledge_id",
                                          file_id="file_id",
                                          display_name="name")

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.createDatasource({
  knowledgeId: "knowledge_id",
  requestBody: {
    displayName: "name",
    fileId: "file_id",
  },
});

console.log(result);

Save the datasource_id returned from the response.

orq files upload \
  --filename example.file \
  --content "$(base64 < file_path)"

orq knowledge-bases create-datasource <knowledge_id> \
  --display-name <name> \
  --file-id <file_id>

See install and setup to get started with the CLI. Run orq knowledge-bases create-datasource --help for the full flag reference.

Add Chunks to a Datasource

API & SDK
CLI

Use the Create chunk API to manually add chunks to a datasource.

curl --request POST \
   --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
   --header 'accept: application/json' \
   --header 'authorization: Bearer <API_KEY>' \
   --header 'content-type: application/json' \
   --data '
[
  {
    "text": "Your chunk content here.",
    "metadata": {
      "source": "manual",
      "topic": "example"
    }
  }
]
'

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    res = orq.knowledge.create_chunks(
        knowledge_id="<knowledge_id>",
        datasource_id="<datasource_id>",
        request_body=[{
            "text": "Your chunk content here.",
            "metadata": {
                "source": "manual",
                "topic": "example"
            }
        }]
    )

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });

await orq.knowledge.createChunks({
  knowledgeId: "<knowledge_id>",
  datasourceId: "<datasource_id>",
  requestBody: [{
    text: "Your chunk content here.",
    metadata: {
      source: "manual",
      topic: "example",
    },
  }],
});

The request body is a JSON array, so it must be piped via --stdin:

echo '[
  {
    "text": "Your chunk content here.",
    "metadata": { "source": "manual", "topic": "example" }
  }
]' | orq knowledge-bases create-chunks <knowledge_id> <datasource_id> --stdin

See install and setup to get started with the CLI. Run orq knowledge-bases create-chunks --help for the full flag reference.

View Datasource Chunks

API & SDK
CLI

Use the List all chunks API to inspect chunks in a datasource.

curl --request GET \
     --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list_chunks(knowledge_id="<id>", datasource_id="<id>", status="completed")

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.listChunks({
  knowledgeId: "<id>",
  datasourceId: "<id>",
  status: "completed",
});

console.log(result);

orq knowledge-bases list-chunks <knowledge_id> <datasource_id> --status completed

See install and setup to get started with the CLI. Run orq knowledge-bases list-chunks --help for the full flag reference.

Chunk Strategy

AI Studio
API & SDK
CLI

When using the AI Studio, you only have access to the following chunk strategies. For more options, see the API & SDK tab.

Choose a chunking option when uploading a file in the Knowledge Base

Default

Automatically set chunk and preprocessing rules. Recommended for unfamiliar users.

Advanced

Maximum Chunk Length: Defines the maximum size of each chunk. Larger size means more information per chunk.Chunk Overlap: Defines the number of characters overlapping neighboring chunks. Higher values increase redundancy between chunks but improve the likelihood that relevant information is returned to models.

Use the sidebar to preview chunks using the chosen chunking strategy.

Use the Chunking API to prepare content for datasource ingestion before adding chunks manually.Common parameters:

text (required): the text content to chunk
strategy (required): token, sentence, recursive, semantic, agentic, or fast
metadata (optional, default: true): include metadata per chunk (start_index, end_index, token_count)
return_type (optional, default: "chunks"): "chunks" (with metadata) or "texts" (plain strings)

curl --request POST \
     --url https://api.orq.ai/v2/chunking \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ORQ_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "strategy": "semantic",
  "text": "Your text content here...",
  "chunk_size": 55,
  "embedding_model": "openai/text-embedding-3-small"
}
'

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.chunking.parse({
  text: "Your text content here...",
  metadata: true,
  strategy: "semantic",
  chunkSize: 256,
  threshold: 0.8,
  embeddingModel: "openai/text-embedding-3-small",
  mode: "window",
  similarityWindow: 1,
});

console.log(result);

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.chunking.parse(request={
        "text": "Your text content here...",
        "metadata": True,
        "strategy": "semantic",
        "chunk_size": 256,
        "threshold": 0.8,
        "embedding_model": "openai/text-embedding-3-small",
        "mode": "window",
        "similarity_window": 1,
    })

    print(res)

The response returns a chunks array. Each chunk contains id, text, index, and optional metadata (start_index, end_index, token_count).

Chunks can be then uploaded to an existing Datasource using the Add Chunk to Datasource API.

Chunk Settings and StrategiesLarger chunks hold more information but increase token use and generation cost.

Token

Splits text into chunks based on token count. Best for ensuring chunks fit within LLM context windows and maintaining consistent chunk sizes for embedding models.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`chunk_overlap`	Number of tokens to overlap between chunks	0

Sentence

Splits text at sentence boundaries while respecting token limits. Ideal for maintaining semantic coherence and readability.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`chunk_overlap`	Number of overlapping tokens between chunks	0
`min_sentences_per_chunk`	Minimum number of sentences per chunk	1

Recursive

Recursively splits text using a hierarchy of separators (paragraphs, sentences, words). Versatile general-purpose chunker that preserves document structure.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`separators`	Hierarchy of separators to use	`["\n\n", "\n", " ", ""]`
`min_characters_per_chunk`	Minimum characters allowed per chunk	24

Semantic

Groups semantically similar sentences using embeddings. Excellent for maintaining topic coherence and context within chunks.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`embedding_model`	Embedding model for similarity (required)	-
`dimensions`	Number of dimensions for embedding output	-
`threshold`	Similarity threshold (0-1) or “auto"	"auto”
`mode`	Chunking mode: “window” or “sentence"	"window”
`similarity_window`	Window size for similarity comparison	1

Agentic

AI-powered intelligent chunking that uses an LLM to determine optimal split points. Best for complex documents requiring intelligent segmentation.

Parameter	Description	Default
`model`	LLM model to use for chunking (required)	-
`chunk_size`	Maximum tokens per chunk	1024
`candidate_size`	Size of candidate splits for LLM evaluation	128
`min_characters_per_chunk`	Minimum characters allowed per chunk	24

Fast

High-performance SIMD-optimized byte-level chunking. Best for large files (>1MB) where speed and memory efficiency are critical. 2x faster and 3x less memory than token-based chunking.

Parameter	Description	Default
`target_size`	Target chunk size in bytes	4096
`delimiters`	Single-byte delimiters to split on (e.g., `"\n.?!"`)	`"\n.?"`
`pattern`	Multi-byte pattern for splitting (e.g., `"▁"` for SentencePiece)	-
`prefix`	Attach delimiter to start of next chunk	false
`consecutive`	Split at START of consecutive delimiter runs	false
`forward_fallback`	Search forward if no delimiter found backward	false

When to use Fast: Large files (>1MB), high-throughput ingestion, memory-constrained environments.When NOT to use Fast: When you need precise token counts for embedding models, small documents where speed isn’t critical, or when semantic boundaries matter more than byte boundaries.

Strategy Selection Guide

Use Case	Recommended Strategy
Large files (>1MB)	Fast: 2x faster, 3x less memory
RAG with precise tokens	Token or Recursive
Semantic search	Semantic
Complex document understanding	Agentic
General purpose	Recursive

--strategy currently only validates token via flags; pipe the body via --stdin for other strategies.

echo '{
  "strategy": "semantic",
  "text": "Your text content here...",
  "chunk_size": 55,
  "embedding_model": "openai/text-embedding-3-small"
}' | orq chunking parse --stdin

See install and setup to get started with the CLI. Run orq chunking parse --help for the full flag reference.

Chunk Metadata

Each chunk in a Knowledge Base can carry a metadata object: a set of key-value pairs that describe the chunk’s origin, topic, or any custom attribute relevant to your use case. Metadata lets you store all your content in a single Knowledge Base while still scoping retrieval to exactly the right subset of chunks at query time. Common use cases:

Multi-tenant RAG: tag chunks by client_id to isolate results per customer.
Source filtering: filter by filetype or source to restrict results to PDFs, support tickets, or a specific data feed.
Topic scoping: tag chunks by topic or category and filter queries to stay on a single subject.

AI Studio
API & SDK
CLI

Open a chunk from the datasource view to access the Edit Chunk panel. The panel has three sections:

Text: the chunk content.
Metadata: a JSON editor pre-filled with the current metadata, or {} if none has been set.
Enabled: toggle to enable or disable the chunk.

Edit the metadata JSON directly and save. The metadata object must be valid JSON with all values as strings, numbers, or booleans. Nested arrays or objects are not supported.

Pass an optional metadata object when creating chunks. Metadata values must be primitive types: strings, numbers, or booleans.

curl --request POST \
   --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
   --header 'accept: application/json' \
   --header 'authorization: Bearer <API_KEY>' \
   --header 'content-type: application/json' \
   --data '
[
  {
    "text": "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
    "metadata": {
      "client_id": "acme_corp",
      "source": "contracts",
      "filetype": "pdf",
      "page_number": 3
    }
  }
]
'

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    res = orq.knowledge.create_chunks(
        knowledge_id="<knowledge_id>",
        datasource_id="<datasource_id>",
        request_body=[{
            "text": "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
            "metadata": {
                "client_id": "acme_corp",
                "source": "contracts",
                "filetype": "pdf",
                "page_number": 3
            }
        }]
    )

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });

await orq.knowledge.createChunks({
  knowledgeId: "<knowledge_id>",
  datasourceId: "<datasource_id>",
  requestBody: [{
    text: "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
    metadata: {
      client_id: "acme_corp",
      source: "contracts",
      filetype: "pdf",
      page_number: 3,
    },
  }],
});

Metadata constraints:

Use metadata for concise, discrete filter attributes to maximize search performance.
Avoid placing large text blobs in metadata. Long strings result in slower queries.
Keep each field’s data type consistent. Non-coercible values are discarded and omitted from the chunk.

The request body is a JSON array, so it must be piped via --stdin:

echo '[
  {
    "text": "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
    "metadata": {
      "client_id": "acme_corp",
      "source": "contracts",
      "filetype": "pdf",
      "page_number": 3
    }
  }
]' | orq knowledge-bases create-chunks <knowledge_id> <datasource_id> --stdin

See install and setup to get started with the CLI. Run orq knowledge-bases create-chunks --help for the full flag reference.

Data and PII Cleanup

AI Studio
API & SDK
CLI

Modify the data loaded within your sources to clean or anonymize it. Toggle on each cleanup option within the Data Cleanup panel.

Processing options panel showing seven Data cleanup toggles: Delete email addresses, Delete telephone numbers, Delete credit card numbers, Clean bullet points, Clean numbered list, Clean dashes, and Clean extra whitespaces.

Option	Description
Delete email addresses	Removes email addresses from chunk content
Delete credit card numbers	Removes credit card numbers from chunk content
Delete telephone numbers	Removes phone numbers from chunk content
Clean bullet points	Normalizes bullet point formatting
Clean numbered list	Normalizes numbered list formatting
Clean dashes	Removes or normalizes dash characters
Clean extra whitespaces	Removes excess whitespace from chunk content

Pass chunking_cleanup_options inside chunking_options when creating a datasource to clean or anonymize source content before it is chunked and indexed.

Option	Description
`delete_emails`	Removes email addresses from chunk content
`delete_credit_cards`	Removes credit card numbers from chunk content
`delete_phone_numbers`	Removes phone numbers from chunk content
`clean_bullet_points`	Normalizes bullet point formatting
`clean_numbered_list`	Normalizes numbered list formatting
`clean_unicode`	Removes or normalizes non-standard unicode characters
`clean_dashes`	Removes or normalizes dash characters
`clean_whitespaces`	Removes excess whitespace from chunk content

curl --request POST \
     --url https://api.orq.ai/v2/knowledge/knowledge_id/datasources \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "display_name": "name",
  "file_id": "file_id",
  "chunking_options": {
    "chunking_configuration": {
      "type": "default"
    },
    "chunking_cleanup_options": {
      "delete_emails": true,
      "delete_credit_cards": true,
      "delete_phone_numbers": true,
      "clean_bullet_points": true,
      "clean_numbered_list": true,
      "clean_unicode": true,
      "clean_dashes": true,
      "clean_whitespaces": true
    }
  }
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_datasource(
        knowledge_id="knowledge_id",
        file_id="file_id",
        display_name="name",
        chunking_options={
            "chunking_configuration": {
                "type": "default"
            },
            "chunking_cleanup_options": {
                "delete_emails": True,
                "delete_credit_cards": True,
                "delete_phone_numbers": True,
                "clean_bullet_points": True,
                "clean_numbered_list": True,
                "clean_unicode": True,
                "clean_dashes": True,
                "clean_whitespaces": True
            }
        }
    )

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.createDatasource({
  knowledgeId: "knowledge_id",
  requestBody: {
    displayName: "name",
    fileId: "file_id",
    chunkingOptions: {
      chunkingConfiguration: {
        type: "default",
      },
      chunkingCleanupOptions: {
        deleteEmails: true,
        deleteCreditCards: true,
        deletePhoneNumbers: true,
        cleanBulletPoints: true,
        cleanNumberedList: true,
        cleanUnicode: true,
        cleanDashes: true,
        cleanWhitespaces: true,
      },
    },
  },
});

console.log(result);

orq knowledge-bases create-datasource <knowledge_id> \
  --display-name <name> \
  --file-id <file_id> \
  --chunking-options '{"chunking_configuration": {"type": "default"}, "chunking_cleanup_options": {"delete_emails": true, "delete_credit_cards": true, "delete_phone_numbers": true, "clean_bullet_points": true, "clean_numbered_list": true, "clean_unicode": true, "clean_dashes": true, "clean_whitespaces": true}}'

See install and setup to get started with the CLI. Run orq knowledge-bases create-datasource --help for the full flag reference.

Embedding Models

An embedding model is a machine learning tool that transforms complex, high-dimensional data into simpler, numerical values that machines can understand, enabling semantic search. Configure which embedding model to use to query the Knowledge Base from the Knowledge Settings panel.

Agentic RAG

Incorporates AI agents into the RAG pipeline to orchestrate its components and perform additional actions beyond simple information retrieval, overcoming the limitations of a non-agentic pipeline. Enable the Agentic RAG toggle in Knowledge Settings, then select a Model to use. The chosen model drives two actions:

Document Grading: ensures only relevant chunks are retrieved.
Query Refinement: rewrites the query if needed to improve retrieval quality.

Enable Agentic RAG in Knowledge Base Settings. Configure the related model after enabling.

Example: Query Refinement

See the screenshot below on how the input query gets refined.Input query: is my suitcase too big? is reformulated to luggage size requirements and restrictions for carry-on and checked baggage

Search Modes

Different Search modes are available for Information to be found in Knowledge Bases:

Vector Search

Vector search is the fastest method of searching through a database built with your Knowledge Sources. The system takes the user query and looks for the text segments most similar to their vector representations.The search returns the preprocessed chunks from the sources most similar and relevant to the user’s query.

Keyword Search

Keyword Search retrieves relevant results by indexing the entire content and searching for segments containing the words from the user’s query.

Hybrid Search

Hybrid search uses both Vector and Keyword search, then combines results and returns the most relevant chunks to the model.

Search Settings

Chunk limit

Sets the number of chunks most similar to the user’s question to return.

Threshold

Controls the relevance of results on a scale from 0 to 1. Results scoring below the threshold are excluded from retrieval.The closer to 1, the more relevant and narrow the results will be.

Setting too high a threshold can yield little to no results.

Rerank Model

Reranking invokes a model that analyzes your initial query and the results fetched by the Knowledge Base search. The model scores and ranks the chunks by similarity to the user query, ensuring the most relevant results are returned.

To use reranking, you must enable at least one Reranking model within the AI Gateway.

Search a Knowledge Base

Once your Knowledge Base is populated, you can query it in several ways.

AI Studio
API & SDK
MCP
CLI

Test via the Studio

Test your Knowledge Base search directly in the AI Studio using the built-in search panel.

Open Knowledge Settings

Navigate to your Knowledge Base and click Knowledge Settings.

Enter your search query

Type your query in the Search query field in the right panel.

View results

Results appear below showing:

Document name (e.g., “Logistics FAQ.docx”)
Relevance score for each chunk (e.g., 0.49, 0.48)
Chunk content preview

Experiment with different search modes and threshold values to find the optimal configuration for your use case. Lower thresholds return more results but may include less relevant chunks.

Integrate to a Deployment

Attach a Knowledge Base to a Deployment to automatically retrieve relevant chunks on every call.

Open the Deployment’s configuration and go to Knowledge Bases.
Select Knowledge Base and choose your Knowledge Base.
Set the query type:
- Last User Message: the user’s latest message is used as the search query automatically.
- Query: use a predefined query. You can make it dynamic with an input variable such as {{query}}.
Reference the retrieved chunks in your prompt with the {{knowledge_base_key}} syntax. If not explicitly referenced, the chunks are appended to the end of the system message.

To learn more, see Using a Knowledge Base in a Deployment.

Integrate to an Agent

Add a Knowledge Base as context to an Agent. Unlike Deployments, the Agent only queries the Knowledge Base when it determines it is necessary, using the query_knowledge_base tool automatically.

In the Agent configuration, go to the Context section and click Add context.
Select your Knowledge Base.
In the Agent’s Instructions, explicitly tell it to use the Knowledge Base. For example:

“First use retrieve_knowledge_bases to see what knowledge sources are available, then use query_knowledge_base to find relevant information before answering.”

The Knowledge Base description must be explicit so the Agent can identify the right source to query.

To learn more, see Knowledge Bases with Agents.

Use in Prompts

To add a Knowledge Base in a Prompt, open the Knowledge Base tab in the Configuration screen and select Add a Knowledge Base.

Select which Knowledge Base to include by clicking on the key. Press Save when done.

Choose whether the Knowledge Base type is Last User Message or Query. This defines how the Knowledge Base will be queried.Use the {{key}} syntax in your prompt, where key is the key of your Knowledge Base.

Your Knowledge Base is correctly referenced when its key appears in blue.

Last User Message: the user message is used as a query to retrieve the relevant chunks.

Playground with the apple knowledge base attached, showing a user question about Apple green bonds and an assistant response citing retrieved context. — An example of using a Knowledge Base in Orq.ai

Query: your predefined query is used to retrieve the relevant chunks.Within a Deployment context, make the query dynamic by using an input variable in the query field.

Use the input variable {{query}} reachable through the invoke call as an input, letting you dynamically define the Knowledge Base query at runtime.

Query a Knowledge Base directly using the Search Knowledge Base API.Basic Search

curl --location 'https://api.orq.ai/v2/knowledge/KNOWLEDGE_BASE_ID/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data '{
    "query": "What are the benefits of machine learning?"
}'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.getenv("ORQ_API_KEY"))

results = client.knowledge.search(
    knowledge_id="KNOWLEDGE_BASE_ID",
    query="What are the benefits of machine learning?"
)

import { Orq } from '@orq-ai/node';

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const results = await orq.knowledge.search({
  knowledgeId: 'KNOWLEDGE_BASE_ID',
  query: 'What are the benefits of machine learning?'
});

Filter by MetadataPass a filter_by object to restrict results to chunks whose metadata matches specified conditions.Supported filter operators (MongoDB-inspired, no $ prefix):

Filter	Description	Example
`eq`	Equal to	`{"page_id": {"eq": "page_x1i2j3"}}`
`ne`	Not equal to	`{"page_id": {"ne": "page_x1i2j3"}}`
`gt`	Greater than	`{"edition": {"gt": 2019}}`
`gte`	Greater than or equal to	`{"edition": {"gte": 2020}}`
`lt`	Less than	`{"edition": {"lt": 2022}}`
`lte`	Less than or equal to	`{"edition": {"lte": 2020}}`
`in`	In array	`{"page_id": {"in": ["a", "b"]}}`
`nin`	Not in array	`{"page_id": {"nin": ["a", "b"]}}`
`and`	Logical AND	`{"and": [{...}, {...}]}`
`or`	Logical OR	`{"or": [{...}, {...}]}`

curl --location 'https://api.orq.ai/v2/knowledge/<knowledge_id>/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data '{
    "query": "What are the contract renewal terms?",
    "filter_by": {
        "client_id": { "eq": "acme_corp" },
        "source": { "eq": "contracts" }
    },
    "search_options": {
        "include_metadata": true,
        "include_scores": true
    }
}'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.getenv("ORQ_API_KEY"))

client.knowledge.search(
    knowledge_id="<knowledge_id>",
    query="What are the contract renewal terms?",
    filter_by={
        "client_id": {"eq": "acme_corp"},
        "source": {"eq": "contracts"},
    },
    search_options={
        "include_metadata": True,
        "include_scores": True,
    },
)

import { Orq } from '@orq-ai/node';

const orq = new Orq({
  apiKey: process.env['ORQ_API_KEY'] ?? '',
});

orq.knowledge.search({
  knowledgeId: '<knowledge_id>',
  query: 'What are the contract renewal terms?',
  filterBy: {
    client_id: { eq: 'acme_corp' },
    source: { eq: 'contracts' },
  },
  searchOptions: {
    includeMetadata: true,
    includeScores: true,
  },
});

See knowledge base search used end-to-end in a real application. Read our cookbook Multilingual FAQ Bot.

Use the Orq MCP server to find and manage knowledge bases from an AI code assistant.Find an existing knowledge base:

Search for knowledge bases in my workspace

The assistant uses search_entities with type: "knowledge" to locate knowledge bases by name or key.

Delete a knowledge base:

Delete the knowledge base with ID "old-docs"

The assistant uses delete_entity with type: "knowledge" and the knowledge base ID.

Basic search:

orq knowledge-bases search <knowledge_id> \
  --query "What are the benefits of machine learning?"

Filter by metadata:

orq knowledge-bases search <knowledge_id> \
  --query "What are the contract renewal terms?" \
  --filter-by '{"client_id": {"eq": "acme_corp"}, "source": {"eq": "contracts"}}' \
  --search-options '{"include_metadata": true, "include_scores": true}'

See install and setup to get started with the CLI. Run orq knowledge-bases search --help for the full flag reference.

See knowledge base retrieval in a complete application. Read our cookbook Multilingual FAQ Bot.

Retrieval Traces and Logs

When using a Knowledge Base within Playground, Experiment, Deployment, or Agent, traces are generated containing details of how Knowledge Bases were accessed.

Traces
Logs

To find Traces, go to the Traces tab in the AI Studio.

Traces show the full breakdown of queries made to the knowledge base, including results and scores

Retrieval Spans show the following:

Query: the query used to retrieve relevant chunks.
Documents: the retrieved chunks, ordered by relevance score.

Overview

Managed Agents

Context Management

Test & Evaluate

AI Chat

Knowledge Bases

Create a Knowledge Base

External Knowledge Bases

Use Cases

Knowledge Bases

Create a Knowledge Base

Datasource and Chunking

Create a Datasource

Add Chunks to a Datasource

View Datasource Chunks

Chunk Strategy

Chunk Metadata

Data and PII Cleanup

Embedding Models

Agentic RAG

Search Modes

Rerank Model

Search a Knowledge Base

Retrieval Traces and Logs

Create a Knowledge Base

External Knowledge Bases

​Use Cases

​Knowledge Bases

​Create a Knowledge Base

​Datasource and Chunking

​Create a Datasource

​Add Chunks to a Datasource

​View Datasource Chunks

​Chunk Strategy

​Chunk Metadata

​Data and PII Cleanup

​Embedding Models

​Agentic RAG

​Search Modes

​Rerank Model

​Search a Knowledge Base

​Retrieval Traces and Logs

Use Cases

Knowledge Bases

Create a Knowledge Base

Datasource and Chunking

Create a Datasource

Add Chunks to a Datasource

View Datasource Chunks

Chunk Strategy

Chunk Metadata

Data and PII Cleanup

Embedding Models

Agentic RAG

Search Modes

Rerank Model

Search a Knowledge Base

Retrieval Traces and Logs