Chunking

Use cases

Chunk documents for retrieval

Split large text into consistent chunks so a retrieval pipeline can index and search it.

Control chunk boundaries precisely

Fix chunk size and overlap before ingestion instead of relying on defaults.

Chunk outside of Knowledge Bases

Prepare text for a third-party vector database or an existing embedding pipeline.

Fix retrieval quality after ingestion

Inspect, edit, or delete chunks in a Knowledge Base Datasource.

Overview

Chunking splits large documents into smaller pieces that a retrieval pipeline can index and search. Orq.ai offers the standalone Chunking API and chunk management inside Knowledge Bases. Text becomes chunks through three paths: a Knowledge Base chunks uploaded files automatically, the Chunking API prepares text that is added to a Datasource manually, or the Chunking API feeds an external vector database. The sections below compare the strategies and the ingestion paths.

Quick start

Split text with the token strategy to see the API shape.

curl -X POST https://api.orq.ai/v2/chunking \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Your long text content here...",
    "strategy": "token",
    "chunk_size": 512,
    "chunk_overlap": 0
  }'

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

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

const result = await orq.chunking.parse({
  text: "Your long text content here...",
  strategy: "token",
  chunkSize: 512,
  chunkOverlap: 0,
});

console.log(result.chunks);

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.environ.get("ORQ_API_KEY"))

result = orq.chunking.parse(
    request={
        "text": "Your long text content here...",
        "strategy": "token",
        "chunk_size": 512,
        "chunk_overlap": 0,
    }
)

for chunk in result.chunks:
    print(f"Chunk {chunk.index}: {chunk.text[:50]}...")

Which chunking strategy to use

The Chunking API offers six strategies:

Strategy	Best for	Trade-off
`token`	Chunks that fit LLM context windows; consistent chunk sizes for embedding models	Boundaries are token-based, not semantic
`sentence`	Prose where sentence boundaries should be preserved	Chunk size varies with sentence length
`recursive`	General-purpose splitting that preserves document structure	Splits in a hierarchy of passes over the text
`semantic`	Topically coherent chunks using embedding similarity	Requires an `embedding_model`; slower and adds embedding cost
`agentic`	Complex documents needing LLM-determined split points	Runs an LLM per call; higher cost and latency
`fast`	Large files (over 1 MB) where speed and memory matter	Byte-level boundaries, not semantic ones

For the full parameter tables and defaults for each strategy, see Datasource and Chunking.

Chunk size and overlap

Chunk size controls how much context each retrieved unit carries. Smaller chunks retrieve more precisely but produce more chunks, more tokens, and higher embedding and storage cost. Larger chunks give the model more surrounding context but increase token use and generation cost.
Chunk overlap repeats tokens across neighboring chunks so a boundary does not cut off a relevant passage. Higher overlap increases redundancy between chunks but improves the likelihood that relevant information is returned to models.

Strategy defaults:

chunk_size 512 for token, sentence, and recursive
chunk_overlap 0 for token and sentence (recursive has no overlap parameter)
agentic uses chunk_size 1024
fast uses target_size 4096 bytes

See the strategy tables for the complete list.

Standalone chunking vs Knowledge Base chunking

Path	How it works	Use when
Knowledge Base file upload	Upload a file or create a Datasource with a `file_id`; the Knowledge Base parses, chunks, embeds, and indexes automatically	Fully managed RAG with no custom logic
Chunking API + Datasource	Call `/v2/chunking`, then add the returned chunks to an empty Datasource; the Knowledge Base embeds and indexes them	Custom strategy, size, or overlap; chunking inside an existing pipeline
Chunking API + external vector database	Call `/v2/chunking`, then embed and store the chunks in a vector database the application controls	Data must stay in existing infrastructure; custom embedding pipeline

Guides per path:

Managed upload: Create a Datasource
Manual pattern: Simple RAG cookbook
External storage: Use Pinecone and custom vector databases

Inspecting and correcting chunks

After ingestion, chunks in a Knowledge Base Datasource can be listed, counted, retrieved, updated, and deleted, one at a time or in bulk. The Knowledge Bases page covers the UI flow and chunk metadata; the reference pages list the exact payloads.

Operation	Endpoint	Reference
Create chunks	`POST /v2/knowledge/{knowledge_id}/datasources/{datasource_id}/chunks` (max 100 per request)	Create chunks
List chunks	`GET` the collection, or `POST .../chunks/list`	List all chunks
Count chunks	`POST .../chunks/count`	Get chunks total count
Retrieve a chunk	`GET .../chunks/{chunk_id}`	Retrieve a chunk
Update a chunk	`PATCH .../chunks/{chunk_id}`	Update a chunk
Delete a chunk	`DELETE .../chunks/{chunk_id}`	Delete a chunk
Delete multiple chunks	`DELETE` the collection with `chunk_ids` (max 100)	Delete multiple chunks

Worked example

For a complete example that chunks a document with the Chunking API, adds the chunks to a Knowledge Base Datasource, and retrieves them, see Simple RAG. For chunking into a custom vector database, see Use Pinecone and custom vector databases.

Best practices

Clean text before chunking (Knowledge Base path): pass chunking_cleanup_options inside chunking_options when creating a Datasource to remove emails, credit card numbers, and phone numbers, and to normalize whitespace, before content is indexed. See Datasource and Chunking.
Keep chunk metadata primitive and consistent: strings, numbers, or booleans only; non-coercible values are discarded from the chunk.
Match chunk size to the retrieval question: smaller chunks for precise Q&A, larger chunks when the model needs broader context.

Overview

Managed Agents

Context Management

Test & Evaluate

AI Chat

Use cases

Overview

Quick start

Which chunking strategy to use

Chunk size and overlap

Standalone chunking vs Knowledge Base chunking

Inspecting and correcting chunks

Worked example

Best practices

​Use cases

​Overview

​Quick start

​Which chunking strategy to use

​Chunk size and overlap

​Standalone chunking vs Knowledge Base chunking

​Inspecting and correcting chunks

​Worked example

​Best practices

Use cases

Overview

Quick start

Which chunking strategy to use

Chunk size and overlap

Standalone chunking vs Knowledge Base chunking

Inspecting and correcting chunks

Worked example

Best practices