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

# Chunking

> Split text into chunks for RAG with six strategies, and decide between the Chunking API and Knowledge Base-managed chunking.

## Use cases

<AccordionGroup>
  <Accordion title="Chunk documents for retrieval">
    Split large text into consistent chunks so a retrieval pipeline can index and search it.
  </Accordion>

  <Accordion title="Control chunk boundaries precisely">
    Fix chunk size and overlap before ingestion instead of relying on defaults.
  </Accordion>

  <Accordion title="Chunk outside of Knowledge Bases">
    Prepare text for a third-party vector database or an existing embedding pipeline.
  </Accordion>

  <Accordion title="Fix retrieval quality after ingestion">
    Inspect, edit, or delete chunks in a Knowledge Base Datasource.
  </Accordion>
</AccordionGroup>

## Overview

Chunking splits large documents into smaller pieces that a retrieval pipeline can index and search. **Orq.ai** offers the standalone [Chunking API](/reference/chunking/parse-text) and chunk management inside [Knowledge Bases](/docs/ai-studio/ai-engineering/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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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]}...")
  ```
</CodeGroup>

## 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](/docs/ai-studio/ai-engineering/knowledge-bases#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](/docs/ai-studio/ai-engineering/knowledge-bases#datasource-and-chunking) 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](/docs/ai-studio/ai-engineering/knowledge-bases#create-a-datasource)
* **Manual pattern**: [Simple RAG cookbook](/docs/ai-studio/cookbooks/common-architecture/simple-rag)
* **External storage**: [Use Pinecone and custom vector databases](/docs/ai-studio/cookbooks/integrations-tooling/using-thirdparty-vectordbs-with-orq)

## 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](/docs/ai-studio/ai-engineering/knowledge-bases) 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](/reference/knowledge-bases/create-chunks-for-a-datasource)     |
| List chunks            | `GET` the collection, or `POST .../chunks/list`                                              | [List all chunks](/reference/knowledge-bases/list-all-chunks-for-a-datasource) |
| Count chunks           | `POST .../chunks/count`                                                                      | [Get chunks total count](/reference/knowledge-bases/get-chunks-total-count)    |
| Retrieve a chunk       | `GET .../chunks/{chunk_id}`                                                                  | [Retrieve a chunk](/reference/knowledge-bases/retrieve-a-chunk)                |
| Update a chunk         | `PATCH .../chunks/{chunk_id}`                                                                | [Update a chunk](/reference/knowledge-bases/update-a-chunk)                    |
| Delete a chunk         | `DELETE .../chunks/{chunk_id}`                                                               | [Delete a chunk](/reference/knowledge-bases/delete-a-chunk)                    |
| Delete multiple chunks | `DELETE` the collection with `chunk_ids` (max 100)                                           | [Delete multiple chunks](/reference/knowledge-bases/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](/docs/ai-studio/cookbooks/common-architecture/simple-rag).

For chunking into a custom vector database, see [Use Pinecone and custom vector databases](/docs/ai-studio/cookbooks/integrations-tooling/using-thirdparty-vectordbs-with-orq).

## 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](/docs/ai-studio/ai-engineering/knowledge-bases#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.