Chunking strategies

Auto is the default chunking strategy. Start with its default settings, inspect the chunks returned by real questions, then change settings when passages combine unrelated topics or lose needed context.

Choose a different strategy when you need specific boundaries:

Settings

Set these values when creating a base:

Overlap must be smaller than Max Chunk Size. Min Chunk Size must be smaller than Max Chunk Size converted to characters (maxSize × 4).

The prose splitters estimate one token as roughly four characters. Tabular chunking uses a denser estimate of roughly three characters per token. These estimates guide splitting; they are not exact model-tokenizer counts.

Text, Recursive, Sentence, and Regex retain small fragments rather than applying the minimum-size filter. Token can filter small windows, with a fallback that retains them when filtering would remove every window. JSON/YAML applies the minimum in some paths; tabular chunking groups rows independently of this setting.

Overlap increases stored text and can produce similar hits from neighboring chunks. Text, Recursive, and non-strict Regex append overlap after forming chunks, so the final chunk can exceed the base size target. Token uses overlapping windows, and Sentence tries to repeat whole sentences.

Auto

Auto chooses from the parsed document type, MIME type, and tabular content shape:

• JSON, JSONL, and YAML use structural chunking when they parse as objects or arrays.
• CSV and Excel content is grouped by row with headers preserved. Delimited text can also be detected as tabular content.
• Other content, including ordinary PDF, Word, text, Markdown, HTML, and PowerPoint documents, uses Text.

Use .json, .jsonl, .yaml, or .yml when you need structural parsing. A plain .txt upload is not automatically treated as JSON just because it contains valid JSON. .tsv is not an offered knowledge-base upload extension; use an accepted format such as .csv.

Structural chunking keeps records together when they fit, batches small records, and splits oversized records or rows. Auto is not a guarantee of one record per chunk.

Text

Text splits general prose using a separator hierarchy:

Horizontal rules → Markdown headings → paragraphs (\n\n) → lines (\n) → sentence punctuation (. , ! , ? ) → clause punctuation (; , , ) → spaces.

It tries larger structural boundaries first and falls back when a piece is too large. Adjacent pieces can be packed together up to the size target before overlap is added.

Recursive

Recursive uses the same approach with a separator hierarchy you provide. For example, split code on \nclass , then \nfunction , then \n\n.

Enter custom separators in the creation form. The v2 API also accepts the built-in plain, markdown, and code recipes through strategyOptions.recipe with strategy: "recursive". Use Recursive when your content has markers the Text hierarchy misses.

Sentence

Sentence splits at sentence boundaries, with abbreviation handling, then packs whole sentences up to the size target. A sentence that exceeds the target is split at word boundaries.

Use it when an incomplete sentence would change the meaning, such as Q&A or legal text. Overlap prefers whole sentences; when none fits, it falls back to a text tail.

Token

Token uses a fixed sliding window aligned to word boundaries. It does not recognize paragraphs or sentences, and its token sizes are estimates rather than exact tokenizer counts.

Use it when a regular window is more useful than structural boundaries.

Regex

Regex splits text at a pattern you supply, then normally packs adjacent segments up to the size target. A pattern such as (?=\n\s*\{\s*"id"\s*:) can find record boundaries, but small segments can still share a chunk.

A consuming delimiter is removed from the split text. Positive lookaround preserves it: (?=X) splits before X, and (?<=X) splits after it.

Patterns can be up to 500 characters. Negative lookaround, backreferences, and repeat counts above 1,000 are unsupported. Positive lookaround is supported.

Strict boundaries

Enable Each match is its own chunk (don't merge) under Chunk Boundaries to keep each nonempty segment separate:

• Adjacent segments are not merged.
• Overlap is disabled.
• Oversized segments produced by a successful split are divided at word boundaries.

The checkbox refers to the segments separated by matches, not to returning only the matched delimiter text.

For example, given:

Question: How long do refunds take?
Answer: Refunds are issued within 14 days.

Question: Where can I find invoices?
Answer: Open Billing in workspace settings.

Use this pattern to split before the next question while retaining its label:

(?=\nQuestion:)

With strict boundaries enabled, each question-and-answer segment is separate, provided it fits the size target. Check the generated chunks to confirm the pattern matches your actual source.

If the pattern does not split

The prose splitters normalize text before splitting:

• \r\n and lone \r become \n.
• Three or more newlines become \n\n.
• Tabs become spaces, and repeated spaces collapse to one.

Adjust patterns that depend on the original whitespace. In non-strict mode, content that already fits the size target returns as one chunk without applying the pattern. If an oversized document produces no splits, non-strict mode falls back to word boundaries; strict mode returns it as a single chunk. Fix the pattern before relying on strict record boundaries.

One record per chunk

For structured input, JSONL makes record boundaries explicit:

{"id":"refunds","question":"How long do refunds take?","answer":"Within 14 days."}
{"id":"invoices","question":"Where can I find invoices?","answer":"In Billing settings."}

Auto can batch these small records into one chunk. Lowering Max Chunk Size reduces batching, but records that exceed the target can still be split. Use strict Regex boundaries when each delimited segment must stay separate, subject to its oversized-segment behavior.

Structural parsing is useful for nested records and escaped values. It does not guarantee recovery of malformed entries; inspect parsing errors and the resulting chunks.

Change settings on an existing base

The UI selects the strategy at creation and displays existing chunking settings as read-only. To use a different strategy through the UI, create a base with that strategy and upload the documents again.

The Update knowledge base API can change the sizes, overlap, strategy, and strategy options. It replaces the configuration object rather than merging it: read the current configuration, change the intended fields, and send back every setting you want to retain. Omitted size fields take their defaults, and an omitted strategy uses Auto. Changed settings apply to later document processing; existing chunks are not automatically rebuilt.

Related docs

• Debugging retrieval — decide whether the problem comes from chunk boundaries.
• Using a knowledge base in a workflow — inspect retrieved content and order.
• Knowledge Base — supported uploads and processing.