Collections

AI Draft

Group files into the boundary that Search and Query address.

A collection groups the files that Search and Query use together. It also defines processing choices and whether per-reader access rules apply.

Choose the retrieval boundary

Namespace: acme

Collection

incident-logs

TXT

checkout.txt

MP4

incident.mp4

Ranked evidence

Find the reports and passages that match.

Query

Answer + citations

Answer a question using this collection.

The policies collection is a separate retrieval boundary.

The incident-logs collection holds related reports and recordings. Search and Query address this collection. A separate policies collection has its own files and retrieval boundary.

Put files together when an answer should use them together. Split unrelated content into separate collections when it needs separate retrieval or key access. Each Search or Query request names exactly one collection.

Add a file directly to the collection. No separate attachment request is required. The same source URI can appear in two collections, but each collection has its own file resource.

Processing profile

Flag	Type and default	Meaning
`keyword`	boolean · true	Allows lexical Search based on words in the content.
`semantic`	boolean · true	Allows Search based on meaning.
`graph`	boolean · true	Enables graph processing for the collection.

All three flags default to true. At least one must stay enabled. On a collection update, an omitted flag keeps its existing value. Enabling processing can return a reindex job. Wait for that job before relying on the new capability.

Disabling a Search mode makes requests for that mode invalid. Discover available cluster modes through /info, then check the collection’s processing flags.

Read the collection state

Status	What it means for your application
`empty`	No living files. Search returns no results. Query returns collection_empty.
`indexing`	Files are processing and none is ready. Retrieval returns collection_not_ready.
`ready`	At least one file is ready for retrieval.
`degraded`	Some files are ready and some failed. Retrieval can use ready files.
`failed`	Files exist but none is ready. Search returns no results and a warning. Query returns collection_not_ready.
`deleting`	Deletion is in progress. Search and Query cannot use the collection.

Read file_counts to distinguish pending, indexing, ready, and failed files. The collection status summarizes the set; a ready collection does not imply that every file finished.

index_generation is an opaque identifier for the indexed content used by retrieval. Treat it as a string. Do not parse it or construct one.

Collection access and lifecycle

access_control defaults to off. Set it to enforced when Search and Query must apply per-reader rules. An enforced collection starts with an empty reader list at its root, so no content is visible until you grant access.

Ordinary file additions and removals update retrieval automatically. Use Reindex collection when you explicitly need to rebuild. Delete collection returns a job and removes its availability to Search and Query.

See Create collection for the full contract and Apply access rules for an enforced collection.

Was this page helpful?