> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How Chunking Works
> What happens to your content after upload: how Gloo splits it into chunks, embeds it, and indexes it, and how to prepare content that chunks well.
When you upload a document to Gloo, [Search](/api-guides/search) and [Grounded Responses](/api-guides/grounded-responses) don't operate on the whole file. They operate on **chunks**: passages of text small enough to retrieve precisely and large enough to carry meaning. A question about one paragraph of a 40-page report should surface that paragraph, not the entire report, and the model grounding an answer should receive exactly the passages that matter.
Chunking is the stage that produces those passages. It runs automatically on every upload; you will see it as the `CHUNKING` status while an item is processing. This page explains what happens to your content between upload and searchable, and then how to make decisions about your own content with that machinery in mind.
## From Upload to Searchable
Every item you upload moves through the same processing pipeline:
**Parse.** Gloo detects the file format automatically and extracts clean text from it. Documents (Markdown, HTML, PDF, Word, and the other [supported formats](/best-practices/ingestion-pattern#normalize-to-clean-text)) are parsed directly. Audio and video files take one extra step first: Gloo transcribes them, and the transcript then enters the same pipeline as any other text.
**Chunk.** The extracted text is split into overlapping chunks. This is the stage reported as `CHUNKING` when you poll an item's status.
**Embed.** Each chunk is encoded for semantic search, so retrieval can match on meaning rather than exact keywords. You never manage embedding models or vectors.
**Index.** The embedded chunks are stored and made retrievable. When the item reaches `COMPLETED`, its chunks are what Search queries and grounded responses draw from.
None of these stages needs configuration, and none of them can be skipped or tuned per upload. Your influence over the outcome comes entirely from what you upload and how you divide it into items, which the rest of this page covers.
## How Content Is Split
{/* DE-REVIEW Q3: confirm this boundary-based description as the approved public wording. We deliberately do not use the phrase "semantic-overlap chunking". */}
Gloo splits content on natural text boundaries, preferring paragraph breaks and falling back to sentence breaks, so that chunks align with the structure of your writing rather than cutting mid-thought. Chunks are roughly paragraph-sized, and consecutive chunks share a small amount of overlapping text:
The overlap exists because meaning doesn't stop at chunk boundaries. A sentence that ends one chunk often sets up the sentence that begins the next; by repeating a small window of text in both chunks, each one stays understandable on its own, and retrieval doesn't miss a passage just because the answer straddles a boundary.
Because splitting prefers natural boundaries, well-structured text produces better chunks than flat text. Headings, paragraphs, and section breaks give the splitter good places to cut; a wall of unbroken text forces arbitrary ones. This is why the [content preparation guide](/best-practices/ingestion-pattern#normalize-to-clean-text) recommends Markdown: it preserves exactly the structure that chunking uses.
Every format follows this same splitting behavior once its text has been extracted, whether the text came from a Markdown file, a parsed PDF, a scraped web page, or an audio transcription.
Chunks never lose track of where they came from. Each chunk stays tied to its parent item, so search results and grounded responses can attribute a passage to the item it belongs to, along with that item's metadata: title, author, canonical URL, tags, and the other [item metadata fields](/api-guides/edit-content). This is why metadata quality matters at the item level; it travels with every chunk of that item into retrieval.
## Can Chunking Be Turned Off?
No. Chunking always runs, and there is no setting to disable it, bypass it, or tune its size and overlap.
You do have one meaningful lever: **item granularity**. Content short enough to fit within a single chunk is not split further, so a short item effectively becomes one chunk. If your content must not be merged with a neighbor, such as individual Q\&A pairs, upload each unit as its own item. The item remains isolated from neighboring content, but oversized items may still be split into multiple chunks. The next section covers when that is the right call.
## Pre-Split or Let Gloo Chunk?
**Default: let Gloo chunk.** For most content (articles, reports, transcripts, long-form prose of any kind), upload the document as one item and let the pipeline handle the rest. Pre-splitting long prose into fragments works against you: it discards the document structure that helps chunking find natural boundaries, and it multiplies the items you have to manage.
Split content into separate items *before* upload only when it has hard semantic boundaries that retrieval must never cross: units that would be wrong to return partially or merged with a neighbor.
* **Q\&A content.** Each question-and-answer pair is one unit. A chunk containing half an answer, or the end of one answer and the start of the next question, misleads retrieval.
* **Devotionals and daily entries.** Each entry stands alone. A passage spanning two days' entries belongs to neither.
* **Episodic collections.** If each segment has its own title, date, and canonical URL, it deserves its own item so its metadata and citations point to the right place.
This is a decision about *what constitutes one document*, not about tuning chunk sizes. Within each item you create, Gloo still chunks automatically. Each pre-split item needs its own [`producer_id`](/getting-started/glossary#producer_id) and metadata; the [content preparation guide](/best-practices/ingestion-pattern#pre-chunk-vs-let-gloo-chunk) covers how to structure that.
## Guidance by Content Type
Chunking itself behaves the same way for every content type. What varies is how you should divide content into items and what metadata to attach:
| Content type | One item is... | Preparation notes |
| --------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Articles and blog posts | One article | Let Gloo chunk. Convert HTML to Markdown, keep headings, strip navigation and boilerplate. Attach title, author, publication date, and canonical URL. |
| Reports and long documents | One report | Let Gloo chunk. Preserve heading structure; it gives the splitter its boundaries. Clean PDF extraction noise (page numbers, running headers) before upload. |
| Podcasts, sermons, and other recordings | One episode or sermon | Upload the audio or video file itself, or use the [Studio YouTube connector](/api-guides/upload-content); Gloo transcribes automatically. Attach episode title, series, date, and URL. |
| Transcripts you already have as text | One session or episode | Let Gloo chunk. Keep speaker labels and section breaks that carry meaning; strip per-word timestamps and filler tokens. |
| Q\&A content | One question-and-answer pair | Pre-split. Give each pair its own item, `producer_id` (e.g. `faq-item-291`), and metadata. |
| Devotionals and daily entries | One entry | Pre-split. One item per entry (e.g. `devotional-2026-03-14`), with the entry's date and title as metadata. |
## What Gloo Handles for You
After upload, the following are automatic. Don't build them yourself:
* **Format detection and parsing** for all [supported document formats](/best-practices/ingestion-pattern#normalize-to-clean-text), with no format flags.
* **Transcription** of audio and video files, whether uploaded directly or ingested through Studio connectors.
* **Chunking**, as described on this page, with nothing to configure.
* **Embedding** of every chunk for semantic search, with no models or vectors to manage.
* **Vector storage and retrieval indexing**, with no database to run or index to maintain.
Your job ends at clean text, sensible item granularity, stable IDs, and good metadata. Everything between upload and searchable is Gloo's job.
## Next Steps
* **[Preparing Content for Ingestion](/best-practices/ingestion-pattern)** — the full source-agnostic pattern for structuring content before upload, including `producer_id` schemes and metadata timing.
* **[Upload Content](/api-guides/upload-content)** — send files to the ingestion endpoint.
* **[Search](/api-guides/search)** — query the chunks this pipeline produces.
* **[Grounded Responses](/api-guides/grounded-responses)** — ground model answers in your indexed content.
* **[Building a Knowledge Base](/ai-learning-center/gloo-ai-103/building-a-knowledge-base)** — Learning Center background on chunking and metadata in RAG systems generally.