> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Metadata Boosts

* **Rank by your own metadata, not just filter by it**: [v3 Query](/reference/v3/query) accepts an optional `boost` array. Each clause retrieves chunks matching one of your `custom_metadata` keys and multiplies their retrieval score by a `weight` between `0.2` and `5.0`. Use it when a chunk is the right answer but does not share wording with the query: a reviewer marked it, a curated tag applies, or your application already cited it. Send no `boost` and retrieval is unchanged.
* **Soft by default, guaranteed when you ask**: with reranking on, boosts decide which chunks the reranker considers and the reranker still decides the final order. Set `reserve` on a clause to guarantee its best matches a place on the page.
* **Every boost explains itself**: each clause is echoed with `matched`, `in_pool`, and `on_page` counts; boosted results carry a `boost` record with the multiplier and the rank they held beforehand, and report `metadata` in `match_sources`. See [Advanced Search & Relations](/guides/advanced-querying#metadata-boosts).