# Boosting chat responses using metadata boosting
Metadata boosting (Legacy)

**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

**Important**  
This section assumes that you understand [document attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html) and [metadata controls](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html) in Amazon Q Business.

**Note**  
Before you configure relevance tuning, you must [create a Amazon Q Business retriever and index](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/select-retriever.html) for your application.

If you choose to use an Amazon Q Business native retriever, you can assign weights to document attributes after mapping them to Amazon Q Business index fields using the Amazon Q Business *metadata boosting* feature. Then, you can use these assigned weights to fine-tune the underlying ranking of RAG retrieved passages within your Amazon Q application environment to optimize the relevance of chat responses. In Amazon Q, boosting means to raise a document in chat results using these weights.

**Important**  
Boosting document attributes using *metadata boosting* is an admin-only feature.

Boosting chat responses based on document attributes helps you rank sources that are more authoritative higher than other sources in your application environment. You can assign a higher value to more recent content, specific file types, or specific data sources.

Amazon Q Business automatically boosts specific document attributes, like document title, when retrieving information from your index to generate end user chat responses. You can use the boosting feature to customize and control boosting, and also override any pre-existing boosts applied by Amazon Q Business.

When you use this feature, a Retrieval Augmented Generation (RAG)-generated result is given a boost during retrieval when the query includes terms that match that field or attribute. You specify how much of a boost the document receives when there is a match. When Amazon Q Business generates responses, it prioritizes the sources that are assigned higher rankings.

Choosing to boost document attributes doesn't by itself cause Amazon Q Business to include or exclude a document in the chat response. A boosted document attribute is only one of the factors that Amazon Q Business uses to determine the relevance of a document.

**Note**  
Boosting in Amazon Q Business is only available if you use an Amazon Q native retriever. If you use an Amazon Kendra retriever, you must [configure boosting for document attributes](https://docs.aws.amazon.com/kendra/latest/dg/tuning.html) in Amazon Kendra. Amazon Q Business supports any boosting that's already configured in your Amazon Kendra index.

**Topics**
+ [

## Understanding boosting in Amazon Q Business
](#understanding-boosting)
+ [

# Amazon Q Business boosting types
](boosting-parameters.md)
+ [

# Configuring document attributes for boosting in Amazon Q Business
](configuring-boosting.md)
+ [

# Enabling document attributes for search in Amazon Q Business
](boosting-searchable-attributes.md)

## Understanding boosting in Amazon Q Business
Understanding boosting (Legacy)

**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

To improve retrieved results and customize the end user chat experience, Amazon Q enables you to map attributes to fields in your Amazon Q Business index.

Amazon Q Business offers [two kinds of attributes](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html#doc-attribute-types): 
+ **Reserved or default** – Reserved attributes are based on document attributes that commonly occur in most data. You can use reserved attributes to map commonly occurring document attributes in your data to Amazon Q Business index fields.
+ **Custom** – You can create custom attributes to map document attributes that are unique to your data to Amazon Q Business index fields.

Document attributes can be [mapped to index fields](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html) using either the Amazon Q console or the API:[https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html)[https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html)
+ **Use the API** – Before you use the API, you must first create an index. Next, create index fields. Then, to ingest documents into your Amazon Q Business index, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_CreateDataSource.html) or [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_BatchPutDocument.html) API operations.
+ **Use the console** – You can choose to map document attributes directly to your index or from your data sources when you connect your data source to Amazon Q Business.

  You can create and map document attributes to index fields using the *Metadata* function on the console.

   When you use data sources the your document attributes are added using data sources, Amazon Q Business automatically maps specific data source document fields to Amazon Q Business index fields. You can choose to add custom fields during the data source configuration process as well.

Document attributes—both reserved and custom—can only be of the following data types: `DATE`, `NUMBER`, `STRING`, and `STRING_LIST`. To use `STRING` and `STRING_LIST` type document attributes for boosting on the console and the API, they must be enabled for search. To enable these attributes using API, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation.

To customize and control boosting for document attributes, use the `boostingOverride` parameter of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_NativeIndexConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_NativeIndexConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateRetriever.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateRetriever.html) API operation.

To enable these attributes using the console, follow the steps in [Mapping document attributes directly to index fields](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/mapping-doc-attributes.html#mapping-doc-attributes-directly).

**Note**  
If you don't enable search on these attributes, you can't boost attributes of these data types on either the Amazon Q Business console or the API.

For more information about Amazon Q Business document attributes and how to map them, see [Document attributes and types](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/doc-attributes.html).

# Amazon Q Business boosting types
Boosting types (Legacy)

**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

Amazon Q Business offers two types of boosting: document attribute boosting and document attribute value boosting. This section outlines how these types of boosting work.

**Note**  
To use the `STRING` and `STRING_LIST` type document attributes for boosting on the console and the API, they must be enabled for search using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation. If you don't enable search on these attributes, you can't boost attributes of these data types on either the Amazon Q Business console or the API.

**Topics**
+ [

## Boosting document attribute importance
](#boosting-document-attribute)
+ [

## Boosting document attribute value
](#boosting-document-attribute-value)

## Boosting document attribute importance


**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

You can boost document attributes to control the relative importance, or boosting level, of the field for end user queries. You can boost importance for all document attribute data types that are supported by Amazon Q—`DATE`, `NUMBER`, `STRING`, and `STRING_LIST`.

**Note**  
Amazon Q Business automatically boosts the document title attribute to **Low**. You can change this value when you customize boosting.

If you choose to boost document attributes, you can also customize boosting in the following ways:
+ **Boost duration** – Specifies the time period over which a boost applies to a `DATE` type document attribute. For example, if you set boosting duration to 604,800 seconds (1 week) for the `_created_at` reserved attribute, documents created within the last week will be boosted.

  Generally, all documents inside the boosting duration will be given more importance over documents outside the boosting duration. Within the boosting duration, documents with more recent dates will be given more importance over documents with less recent dates.

  Outside the boosting duration, the documents with more recent dates will continue to be given more importance over documents with less recent dates. However, the overall effect of the date boosting will taper to zero as the dates move further away from the boosting duration.
**Note**  
Boosting duration is based on the most recent date in all documents in the index.
+ **Boost order** – Determines whether a `NUMBER` type document attribute is boosted in prioritizing higher values or prioritizing lower values.

  For example, if your documents contain attributes for view count, you can choose to prioritize chat responses with higher view count values by boosting larger values over smaller values. Or, suppose your documents contain attributes that denote priority—for example, a task tracker that assigns priority 1 to the most important task. In that case, you can choose to boost documents using smaller values.

## Boosting document attribute value


**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

To customize boosting levels, you can boost document attribute values for only `STRING` type document attributes.

For example, suppose that you're applying an importance boost to a `STRING` attribute called `department`. The `department` attribute has values like `HR` and `Legal`. You can assign the values `HR, VERY_HIGH` and `Legal, HIGH` to customize the importance that Amazon Q gives to these attribute values when they match a chat request.

# Configuring document attributes for boosting in Amazon Q Business
Configuring document attributes for boosting (Legacy)

**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

To boost specific documents for end user queries using document attributes, you can use the AWS Management Console or the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeBoostingConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeBoostingConfiguration.html) parameter of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateRetriever.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateRetriever.html) API operation.

**Note**  
For `STRING` and `STRING_LIST` type document attributes to be used for boosting on the console and the API, they must be enabled for search using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation. If you don't enable search on these attributes, you can't boost attributes of these data types on either the console or the API.

The following tabs provide a procedure to boost document attributes using the console and code examples for the AWS CLI.

------
#### [ Console ]

**To boost document attributes** 

1. Sign in to the AWS Management Console and open the Amazon Q Business console.

1. In **Applications**, select the name of your application environment from the list of applications.

1. From the left navigation menu, choose **Metadata boosting**.

1. In **Metadata boosting**, choose the document attribute type that you want to boost.
**Note**  
You can boost attributes using the following values: **None**, **Low**, **Medium**, **High**, and **Very high**.

   Choose from the following options:

   1. **Popular** – Amazon Q displays the following popularly boosted document attributes for you to choose from:

      1. **Document title** – Use to boost the title of a document. You can also use **Advanced settings** to boost specific document titles. By default, the document title attribute is enabled for search with a value of `Low`. You can change this value when you customize boosting.

      1. **Last updated** – Use to boost content by its last updated date. You can also use **Advanced settings** to configure **Boosting duration**, or how long your boost should apply.

      1.  **File type** – Use to boost content by file type.

      1. **Data sources** – Use to boost the content data source type.

      1. To save your configuration, choose **Save**.

   1. **Text** – Use to boost `STRING` and `STRING_LIST` type reserved or custom document attributes that you have enabled for search. Then, choose **Save**.

   1. **Date** – Use to boost content using `DATE` type reserved or custom document attributes. For example, use the **Created at** document attribute to boost content based on recency. You can also use **Advanced settings** to configure **Boosting duration**, or how long your boost should apply. Then, choose **Save**.

   1. **Numeric** – Use to boost content using `NUMERIC` type reserved or custom attributes. For example, use the **View count** document attribute to boost content based on view count. Based on your boosting needs, choose either **Prioritize higher values** or **Prioritize lower values**. Then, choose **Save**.

   1. Once done, you can select **View web experience** to check boosting. Your configured web experience will open in a new window.

------
#### [ AWS CLI ]

**Update your Amazon Q Business index to apply boosting **

This example shows how to apply `VERY_HIGH` boosting for the `STRING` type document attribute `_document_title`. 

```
aws qbusiness update-retriever \
--application-id APPLICATION-ID --retriever-id RETRIEVER-ID \
--configuration '{
        "nativeIndexConfiguration": {
            "indexId": "INDEX-ID",
            "boostingOverride": {
                "_document_title": {
                    "stringConfiguration": {
                        "boostingLevel": "VERY_HIGH"
                    }
                }
            }
        }
}'
```

This example shows how to apply boosting for the `STRING` type attribute `_category`, the `DATE` type attribute `_created_at`, the `NUMBER` type attribute `_view_count`, and the `STRING_LIST` type attribute `_authors`.

```
aws qbusiness update-retriever \
--application-id APPLICATION-ID --retriever-id RETRIEVER-ID \
--configuration '{
        "nativeIndexConfiguration": {
            "indexId": "INDEX-ID",
            "boostingOverride": {
                "_category": {
                    "stringConfiguration": {
                        "boostingLevel": "LOW",
                        "attributeValueBoosting": {
                            "HR": "MEDIUM"
                        }
                    }
                },
                "_created_at": {
                    "dateConfiguration": {
                        "boostingLevel": "LOW",
                        "boostingDurationInSeconds": 2592000
                    }
                },
                "_view_count": {
                    "numberConfiguration": {
                        "boostingLevel": "LOW",
                        "boostingType": "PRIORITIZE_SMALLER_VALUES"
                    }
                },
                "_authors": {
                    "stringListConfiguration": {
                        "boostingLevel": "HIGH"
                    }
                }
            }
        }
}'
```

**Update your Amazon Q Business retriever to remove any existing boosts**

This example shows how to remove any existing boosts from document attributes in your retriever.

```
aws qbusiness update-retriever \
--application-id APPLICATION-ID --retriever-id RETRIEVER-ID \
--configuration '{
        "nativeIndexConfiguration": {
            "indexId": "INDEX-ID"
        }
}'
```

**Get details about your Amazon Q Business retriever boosts **

This example shows how to get details for your existing boosting configuration

```
aws qbusiness get-retriever \
--application-id APPLICATION-ID --retriever-id RETRIEVER-ID
```

------

# Enabling document attributes for search in Amazon Q Business
Enabling document attributes for search (Legacy)

**Note**  
Relevance tuning has replaced metadata boosting. For more information, see [Tuning the query results based on document attribute relevancy](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/relevancy-tuning.html).

For `STRING` and `STRING_LIST` type attributes to be eligible for boosting, they must first be enabled for search in your Amazon Q index.

The following sections outline how to do so using both the console and the API.

**Topics**
+ [

## Using the console
](#enable-attribute-search-console)
+ [

## Using the API
](#enable-attribute-search-api)

## Using the console


To enable document attributes using the console, use the **Metadata** functionality. The following procedure outlines how.

**To create and map document attributes to index fields **

1. Sign in to the AWS Management Console and open the Amazon Q Business console.

1. From the left navigation pane, from **Enhancements**, choose **Metadata controls**.

1. From **Metadata**, choose **Add metadata field**.

1. From the **Add metadata field** dialog box that opens up, do the following:

   1. For **Metadata field name** – Add a name for the metadata field you're adding to the index.

   1. For **Data type** – Select the data type you want to assign to the metadata field.

   1. For **Usage type** – Select **Searchable** to mark your field searchable to end users.

   1. Select **Add** to finish adding the metadata field to your index.

   Repeat the previous step to add create and map more metadata fields. Once you add a metadata field, you can't delete it.

1. To save all the metadata fields you added, select **Save**.
**Note**  
If you leave the page without saving your changes, any metadata fields you added won't be saved.

You can update the searchability of a metadata field at any time.

## Using the API


To enable these attributes for search using the API, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation.

The following sections provide AWS CLI examples of how to enable document attributes for search.

**Topics**
+ [

### Making reserved document attributes searchable
](#enable-reserved-attribute-search)
+ [

### Making custom document attributes searchable
](#enable-custom-attribute-search)
+ [

### Checking document attribute search activation
](#check-attribute-search)

### Making reserved document attributes searchable


The following is an example of how to use the AWS CLI to enable for search the `STRING` type reserved document attribute `_category` and the `STRING_LIST` type reserved document attribute `_authors` by using the [UpdateIndex](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation.

```
aws qbusiness update-index \
--application-id APPLICATION_ID \
--index-id INDEX_ID \
--document-attribute-configurations '
          [
            {
              "name": "_category",
              "type": "STRING",
              "search": "ENABLED"
            },
            {
              "name": "_authors",
              "type": "STRING_LIST",
              "search": "ENABLED"
            }
          ]'
```

### Making custom document attributes searchable


You can also enable custom document attributes for search using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeConfiguration.html) object of the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation.

The following is an example of how to use the AWS CLI to enable for search the custom `STRING` and `STRING_LIST` type document attributes using the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_UpdateIndex.html) API operation.

```
aws qbusiness update-index \
--application-id APPLICATION_ID \
--index-id INDEX_ID \
--document-attribute-configurations '
          [
            {
              "name": "custom_string",
              "type": "STRING",
              "search": "ENABLED"
            },
            {
              "name": "custom_string_list",
              "type": "STRING_LIST",
              "search": "ENABLED"
            }
            ]'
```

### Checking document attribute search activation


To check if a `STRING` or `STRING_LIST` type document attribute has been enabled for search successfully, use the [https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetIndex.html](https://docs.aws.amazon.com/amazonq/latest/api-reference/API_GetIndex.html) API operation.

```
aws qbusiness get-index \
--application-id APPLICATION_ID \
--index-id INDEX_ID
```

The AWS CLI returns the following type of response:

```
{
...
    "documentAttributeConfigurations": [
        {
            "name": "_authors",
            "search": "ENABLED",
            "type": "STRING_LIST"
        },
        {
            "name": "_category",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_created_at",
            "search": "DISABLED",
            "type": "DATE"
        },
        {
            "name": "_data_source_id",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_document_title",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_file_type",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_language_code",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_last_updated_at",
            "search": "DISABLED",
            "type": "DATE"
        },
        {
            "name": "_source_uri",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_version",
            "search": "ENABLED",
            "type": "STRING"
        },
        {
            "name": "_view_count",
            "search": "DISABLED",
            "type": "NUMBER"
        }
    ],
...
}
```