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.
Topics
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:
-
You create an index by calling the CreateIndex API operation.
-
Then, you create index fields using the UpdateIndex operation. You use this method to map both reserved and custom document attributes to index fields.
-
Optionally, you can test and view the index fields that you’ve added by using the GetIndex operation.
-
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 usesAttributes
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" }