Contextual Text Splitter
Contextual Text Splitter splits your documents into pieces and asks a model to write, for each one, one or two sentences that place it within the whole document. That context is added in front of the piece before it is stored in a vector database.
Long documents are split into pieces so each search returns only the part that answers, not the whole document. The problem is that many pieces, on their own, don’t say what they are about. “Disconnect the probe and measure the resistance: it should read 1,000 ohms” does not say which machine or which fault. With the context in front, “From the technical manual of the Q90 coffee machine, section on error E07 (temperature probe)”, the search finds it when someone asks about E07 on the Q90. This technique is known as contextual retrieval.
When to use it
- Your documents have similar sections that only differ by their title: manuals for several machines, terms for several products, reports for several months.
- Some pieces lose their meaning outside their document, such as a price table without the product name or a procedure step that only says “the part”.
- You are going to reorder the results with Local Rerank: with context, reranking gets it right more often.
- Searches fail because the pieces don’t mention the topic they are about.
Configuration
| Field | What it does |
|---|---|
| Data Inputs (required) | The documents to split, with their text and data. For example, the output of Storage Files reading a PDF. |
| Language Model (required) | The model that writes the context of each piece. A fast, inexpensive model is enough. |
| Chunk Size | The maximum size of each piece, in characters (or in tokens with the token_based method). From 50 to 8,000. Default: 1000. |
| Chunk Overlap | How much text two consecutive pieces share, so an idea cut in two is complete in one of them. From 0 to 2,000. Default: 200. |
Advanced options
| Field | What it does |
|---|---|
| Split Method | How the text is cut. recursive (default): by paragraphs, then by lines and then by sentences, until the piece fits. token_based: the same, but the size is measured in tokens, the word pieces models work with. sentence: whole sentences only, it never cuts a sentence in half. |
| Preserve Paragraphs | On (default), it prefers to cut between paragraphs. With sentence, a piece also never joins two paragraphs. |
| Separator | What separates paragraphs in your documents. Default: a blank line. |
| Max Sentence Length | Only with sentence: sentences longer than this are cut into pieces of this many characters. Default: 500. |
| Parallel Requests | How many pieces get their context at the same time, from 1 to 20. Default: 5. More is faster, if your model provider allows it. |
Output
The Chunks output has one item per piece with this data:
| Data | What it holds |
|---|---|
text | The context, a blank line and the piece. This is what is stored and searched. |
context | Only the context written by the model. |
chunk | Only the original piece, as it was in the document. |
| The document’s data | Whatever the source document carried, for example the file name, is copied to every piece. |
Connect Chunks to Ingest Data of a vector database, such as Qdrant or Chroma DB, or first to Metadata Tagger to tag each piece.
If the model fails (for example, because of a credential with no balance), the run stops with the error. Pieces are never stored with an error message in place of the context.
Example
A coffee machine repair service wants its assistant to answer from its machine manuals.
- Read the PDF manual with Storage Files and connect its output to Data Inputs.
- Connect a fast model, such as DeepSeek, to Language Model. Set Chunk Size to 700 and Chunk Overlap to 100.
- Connect Chunks to Metadata Tagger and its output to Ingest Data of Qdrant with Operation set to
Add. - Run the flow once. In the output table you’ll see, for each piece, the text with its context in front, and the context and the original piece separately.
What it improves and what it costs: measured figures
Measured on 17 October 2026 on a test knowledge base (9 documents of a fictional repair service, 40 questions). These figures come from a single synthetic set: they show how the technique behaves, not a promise for your data.
- More hits: with search by meaning, the right piece was in the top 5 for 93 % of the questions with context, against 83 % without it.
- The best combination, with reranking: this component, hybrid search and Local Rerank was the best setup in the test: the right piece came first for 80 % of the questions and in the top 5 for all of them, against 60 % and 83 % with search by meaning alone. Without context, the same search with reranking had it in the top 5 for 87 % (measured on 18 October).
- Cost: one model call per piece, only when the documents are stored; searches have no added cost. In the test, 80 pieces took about 23 seconds, 5 at a time. Each call sends the whole document along with the piece, about 1,800 input tokens per piece in that test, so the cost grows with the size of your documents.
Good practices
- Use a fast, inexpensive model: the context is one or two sentences and needs no reasoning.
- For technical documents, pieces of 600 to 1,000 characters with an overlap of 100 to 200 work well.
- The model reads up to the first 60,000 characters of each document to write the context. If your documents are much longer, split them by chapter first.
- If you change Chunk Size, the method or the embeddings model, store the documents again in a new collection.
Related components
- Metadata Tagger: tags each piece with data to filter searches.
- Local Rerank: reorders the results; it does better with contextualised pieces.
- Recursive Character Text Splitter: splits without adding context, with no model cost.
- Qdrant and Chroma DB: where to store the pieces.
To see how it fits in a complete ingestion flow, see Preparing documents in the RAG guide.