---
description: Bias AI Search results toward documents with specific metadata using relevance boosting.
title: Relevance boosting
image: https://developers.cloudflare.com/og-docs.png
---

[Skip to content](#main-content)

> Documentation Index  
> Fetch the complete documentation index at: https://developers.cloudflare.com/ai-search/llms.txt  
> Use this file to discover all available pages before exploring further.

# Relevance boosting

Last updated Aug 24, 2026|Copy as Markdown|[View as Markdown](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/ai-search/configuration/retrieval/boosting/index.md)|[Agent setup](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/agent-setup/)

Boosting lets you bias search results toward documents with specific metadata characteristics. For example, you can promote recent documents, surface higher-priority pages, or deprioritize drafts. Boosting re-ranks results without replacing semantic relevance.

## How it works

Boosting applies after the initial retrieval step and before [reranking](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/ai-search/configuration/retrieval/reranking/) (if enabled):

1. **Search**: AI Search retrieves up to 50 candidate chunks using vector search, keyword search, or both.
2. **Boost**: Each candidate is re-scored using the metadata fields you specify in `boost_by`. The boost is additive to the original retrieval score.
3. **Rerank**: If reranking is enabled, the boosted results are reranked by a reranking model.
4. **Return**: The top `max_num_results` are returned.

Boosting can change the order of results within the candidate set, but cannot promote a chunk that the initial search step did not retrieve.

## Supported fields

You can boost by the built-in `timestamp` field or by any field defined in your [custom metadata schema](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/ai-search/configuration/indexing/metadata/#define-a-schema).

| Field type | Supported directions           |
| ---------- | ------------------------------ |
| datetime   | asc, desc, exists, not\_exists |
| number     | asc, desc, exists, not\_exists |
| text       | exists, not\_exists only       |
| boolean    | exists, not\_exists only       |

### Directions

The direction controls how the field value affects the ranking of each result:

| Direction   | Effect                                                       |
| ----------- | ------------------------------------------------------------ |
| desc        | Higher field values score higher (for example, most recent). |
| asc         | Lower field values score higher (for example, lowest cost).  |
| exists      | Documents that have the field score higher.                  |
| not\_exists | Documents that do not have the field score higher.           |

If you omit `direction`, AI Search applies a default based on the field type:

| Field type                  | Default direction |
| --------------------------- | ----------------- |
| number, datetime, timestamp | asc               |
| text, boolean               | exists            |

Using `asc` or `desc` on a `text` or `boolean` field returns an error.

## Configuration

Specify `boost_by` as an array of up to 3 objects when creating or updating an instance. Each object must reference a unique field.

| Field     | Type   | Required | Description                                                                 |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| field     | string | Yes      | Metadata field name or timestamp. Must match your schema. Case-insensitive. |
| direction | string | No       | One of asc, desc, exists, not\_exists. Defaults by type.                    |

```ts
const instance = await env.AI_SEARCH.create({
	id: "my-instance",
	retrieval_options: {
		boost_by: [
			{ field: "timestamp", direction: "desc" },
			{ field: "priority", direction: "desc" },
		],
	},
});
```

To remove boosting, set `boost_by` to an empty array when updating the instance.

## Per-request overrides

You can override `boost_by` on individual requests using `ai_search_options.retrieval`. Per-request values fully replace the instance-level default.

```ts
const instance = env.AI_SEARCH.get("my-instance");

const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			boost_by: [{ field: "timestamp", direction: "desc" }],
		},
	},
});
```

To disable boosting for a single request, pass an empty array:

```ts
const results = await instance.search({
	messages: [{ role: "user", content: "What is Cloudflare?" }],
	ai_search_options: {
		retrieval: {
			boost_by: [],
		},
	},
});
```

## Common patterns

Here are some common ways to use relevance boosting:

| Pattern                          | Configuration                                                                                   |
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
| Prioritize recent documents      | \[{ "field": "timestamp", "direction": "desc" }\]                                               |
| Promote by custom priority       | \[{ "field": "priority", "direction": "desc" }\]                                                |
| Boost lower-cost options         | \[{ "field": "cost", "direction": "asc" }\]                                                     |
| Promote documents with an author | \[{ "field": "author", "direction": "exists" }\]                                                |
| Suppress drafts                  | \[{ "field": "draft", "direction": "not\_exists" }\]                                            |
| Combine recency and priority     | \[{ "field": "timestamp", "direction": "desc" }, { "field": "priority", "direction": "desc" }\] |

## Limitations

* Maximum of 3 boost fields per request.
* Field names must match a field in your custom metadata schema or the built-in `timestamp` field.
* `text` and `boolean` fields only support `exists` and `not_exists` directions.
* Boost fields within a single request must be unique.
* Boosting re-ranks the candidate set from the initial search. It cannot surface documents that were not retrieved.

Was this helpful?

YesNo

## On this page

[![](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://docs-durable-objects-instance-replaced-errors.previews.developers.cloudflare.com/)

```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/ai-search/configuration/retrieval/boosting/#page","headline":"Relevance boosting · Cloudflare AI Search docs","description":"Bias AI Search results toward documents with specific metadata using relevance boosting.","url":"https://developers.cloudflare.com/ai-search/configuration/retrieval/boosting/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-24","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}
```