Mapping document attributes in Amazon Q Business

An Amazon Q Business index has field you can map your document attributes to. Once mapped to document attributes, these index fields can be used by admin to boost results from specific sources, or by end users to filter and scope their chat results to specific data.

Mapping document attributes from your documents to index fields is a multi-step process that depends on the document upload method you use.

Note

Filtering using document attributes in chat is only supported through the API. Boosting search results using document attributes is supported on both the console and the API.

Mapping document attributes directly to index fields

When you use the API, you must first map your document attributes to index fields before you can use them for filtering in chat. You use the following process to map document attributes to your index field:

1. You create an index by calling the CreateIndex API operation.

2. Then, you create index fields using the UpdateIndex operation. You use this method to map both reserved and custom document attributes to index fields.

3. Optionally, you can test and view the index fields that you’ve added by using the GetIndex operation.

4. Then, when you use the BatchPutDocument operation to ingest documents into your index, Amazon Q Business extracts your reserved or custom document attributes and maps them to the index fields that you have already created.

After you map document attributes directly to index fields using the API, you can select specific attributes for your end user to use for filtering chat responses. With the UpdateIndex API operation, you add custom fields or attributes using the documentAttributeConfigurations parameter.

The following JSON example uses documentAttributeConfigurations to add a field called "Department" to the index.

"DocumentmetadataConfigurationUpdates": [
   {
       "Name": "Department",
       "Type": "STRING_VALUE"
   }
]

Mapping data source document attributes to index fields

If you use an Amazon Q Business data source connector, you can map default document attributes attached to documents in your data source to fields in your Amazon Q Business index. You can use these document attributes to help your end user filter and scope chat responses.

Important

Filtering using data source document attributes in chat is only supported through the API.

Each data source connector is designed to crawl the default document attributes in your data source automatically. For example, if you have a field in your data source named dept that contains department information for a document, you can map it to an index field named Department. You can't change or customize default data source attributes that are mapped to an index.

You can also map any Amazon Q Business reserved fields such as _created_at. If your data source has a field named creation_date, you can map this field to the equivalent Amazon Q reserved field named _created_at.

You can also choose to add custom document attributes and map them to custom fields that you create in your index. Most data sources support field mappings and follow a specific configuration format, except Amazon S3 and database data sources. The following outlines how Amazon S3 and database data sources configure mappings:

• If you store your documents in an Amazon S3 bucket or Amazon S3 data source, you can either use the console to specify field mappings or specify fields using a JSON metadata file.

  When you use an Amazon S3 bucket as a data source for your index, you use companion metadata files to add metadata to the documents. You place the metadata JSON files in a directory structure that is parallel to your documents. For more information, see S3 document metadata.

  You specify custom fields or attributes in the Attributes JSON structure. You can create up to 50 custom fields or attributes. The following example uses Attributes to define three custom fields or attributes and one reserved field.

  "Attributes": {
          "brand": "Amazon Basics",
          "price": 1595,
          "_category": "sports",
          "subcategories": ["outdoors", "electronics"]
      }

• For database data sources, if the name of the database column matches the name of a reserved field, the field and column are mapped automatically.

If you use the console, you select default field mappings or create custom mappings when you configure your connector. On the console, if a default field or a default field property can’t be edited, it will appear grayed out.

If you use the API, you use the configuration parameter of the CreateDataSource API operation to map default document attributes in your data source to index fields.

If you want to map custom document attributes in your data source to Amazon Q index fields, use the DocumentAttribute parameter of the UpdateIndex operation to first create the custom field matching the custom document attribute. By doing so, you can specify and map your reserved or custom data source document attribute to a reserved or custom index field.

Ingesting attributes using the BatchPutDocument API operation

When you use the BatchPutDocument API operation to add a document to your index, you can specify document attributes—both reserved and custom—as part of Attributes. You can add multiple fields or attributes when you call the API operation. You can create up to 50 custom fields or attributes. The following example is a custom field or attribute that adds "Department" to a document.

"Attributes": 
    {
        "Department": "HR",
        "_category": "Vacation policy"
    }