Amazon Q Business - Document Attributes

---

---

In this chapter we are going to understand about what document attributes are, how they work in Amazon Q Business, and what they can help you do for your chat solution. This chapter also lists the document types supported by Amazon Q Business.

Document Attributes

Every document has information about itself attached to it, like the title, author, creation date, last update, and type of document.

Amazon Q Business index allows you to connect document attributes to fields. These fields help admins to improve search results from specific sources. End users can also filter and narrow down their search results by using these fields.

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.

Types of Document Attributes

Amazon Q Business supports two types of document attributes.

• Reserved Document Attributes
• Custom Document Attributes

Reserved Document Attributes

Amazon Q Business has Reserved or default document attributes to create mappings for common document attributes to help you index documents efficiently.

Amazon Q Business offers the following reserved document attributes or index fields that you can map your metadata to:

• _authors: A list of one or more authors responsible for the content of the document.
• _category: A category that places a document in a specific group.
• _created_at: The date and time in ISO 8601 format that the document was created. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25, 2012 at 12:30 PM (plus 10 seconds) in Central European Time.
• _data_source_id: The identifier of the data source that contains the document.
• _document_body: The content of the document.
• _document_id: A unique identifier for the document.
• _document_title: The title of the document.
• _file_type: The file type of the document, such as .pdf or .docx.
• _last_updated_at: The date and time in ISO 8601 format that the document was last updated. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25, 2012 at 12:30 PM (plus 10 seconds) in Central European Time.
• _source_uri: The URI where the document is available. For example, the URI of the document on a company website.
• _version: An identifier for the specific version of a document.
• _view_count: The number of times that the document has been viewed.
• _language_code (String): The code for a language that applies to the document. This defaults to English if you don't specify a language.

Custom Document Attributes

Custom attributes are used to link unique information in your documents to index fields.

You can create custom attributes based on your own data, and map them to custom index fields to create a more tailored chat experience for end users.

For example, you can create a custom field or attribute called "Department" with the values of "HR", "Sales", and "Manufacturing". Then, you can use these fields or attributes to allow your end users to filter their chat results to documents in the "HR" department, or restrict response generation to specific data stores.

Once created, you can't delete or rename any attributes.

Mapped Document Attributes

When you map a document attribute to an index field, you can decide how that field will be used during chat. For now, you can configure index fields to do the following:

• Search: Allows end users the ability to search data with the specified attributes.

Document Attribute Data Types

Document attributesreserved or customcan only be the data types that are shown in the following table. Additionally, document attributes can be used to perform the operations outlined.

You cant change an index field type after it has been created.

Mapping Document Attributes to Index Filed

Mapping document attributes directly to index fields. Before using the API for filtering in chat, map your document attributes to index fields

• You create an index by calling the CreateIndex API operation.
• Then, create index fields using the UpdateIndex operation. This is where you link your document details to index fields.
• Add documents to your index using BatchPutDocument. Amazon Q Business matches document details to index fields.

After you Map document attributes to index fields using the API. Then, choose which attributes to use for filtering chat responses. Use UpdateIndex API to add custom fields.

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

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

Mapping Data Source to Index Filed

Mapping data source document attributes to index fields. If you use an Amazon Q Business data source connector, you can map default document attributes to index fields. These attributes help users filter and narrow chat responses.

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

Data source connectors automatically find default document attributes. You can map these attributes to index fields. For example, map a 'dept' field to a 'Department' index field. Note: You can't change default attributes once they're mapped.

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 add custom document attributes and map them to custom index fields. Most data sources allow field mappings, except Amazon S3 and database data sources. These two have special mapping configurations. The following outlines how Amazon S3 and database data sources configure mappings:

• If you store documents in Amazon S3, you can map fields in two ways. You can use the console to specify field mappings or use a JSON metadata file. To add metadata to your documents, create a directory structure with metadata JSON files alongside your documents. Then, in the Attributes JSON structure, you can add 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"]
}

If a database column has the same name as a reserved field, they connect automatically.

When setting up your connector, you can map fields in two ways. On the console, you can choose default field mappings or create custom ones, but note that some default fields can't be edited and will appear grayed out. Alternatively, you can use the API to map fields, where you use the CreateDataSource operation to map default attributes and the UpdateIndex operation to create and map custom fields.

Ingesting Attributes using BatchPutDocument API Operation

When adding a document to your index using the BatchPutDocument API, you can specify attributes, including both reserved and custom ones. You can add multiple fields or attributes in a single API call, with a limit of up to 50 custom fields.

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