Note:

You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . qbusiness ]

batch-put-document¶

Description¶

Adds one or more documents to an Amazon Q Business index.

You use this API to:

ingest your structured and unstructured documents and documents stored in an Amazon S3 bucket into an Amazon Q Business index.
add custom attributes to documents in an Amazon Q Business index.
attach an access control list to the documents added to an Amazon Q Business index.

You can see the progress of the deletion, and any error messages related to the process, by using CloudWatch.

Synopsis¶

  batch-put-document
--application-id <value>
--index-id <value>
--documents <value>
[--role-arn <value>]
[--data-source-sync-id <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]

Options¶

--application-id (string)

The identifier of the Amazon Q Business application.

--index-id (string)

The identifier of the Amazon Q Business index to add the documents to.

--documents (list)

One or more documents to add to the index.

(structure)

A document in an Amazon Q Business application.

id -> (string)

The identifier of the document.

attributes -> (list)

Custom attributes to apply to the document for refining Amazon Q Business web experience responses.

(structure)

A document attribute or metadata field.

name -> (string)

The identifier for the attribute.

value -> (tagged union structure)

The value of the attribute.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.

stringValue -> (string)

A string.

stringListValue -> (list)

A list of strings.

(string)

longValue -> (long)

A long integer value.

dateValue -> (timestamp)

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.

content -> (tagged union structure)

The contents of the document.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: blob, s3.

blob -> (blob)

The contents of the document. Documents passed to the blob parameter must be base64 encoded. Your code might not need to encode the document file bytes if you're using an Amazon Web Services SDK to call Amazon Q Business APIs. If you are calling the Amazon Q Business endpoint directly using REST, you must base64 encode the contents before sending.

s3 -> (structure)

The path to the document in an Amazon S3 bucket.

bucket -> (string)

The name of the S3 bucket that contains the file.

key -> (string)

The name of the file.

contentType -> (string)

The file type of the document in the Blob field.

If you want to index snippets or subsets of HTML documents instead of the entirety of the HTML documents, you add the HTML start and closing tags (<HTML>content</HTML> ) around the content.

title -> (string)

The title of the document.

accessConfiguration -> (structure)

Configuration information for access permission to a document.

accessControls -> (list)

A list of AccessControlList objects.

(structure)

A list of principals. Each principal can be either a USER or a GROUP and can be designated document access permissions of either ALLOW or DENY .

principals -> (list)

Contains a list of principals, where a principal can be either a USER or a GROUP . Each principal can be have the following type of document access: ALLOW or DENY .

(tagged union structure)

Provides user and group information used for filtering documents to use for generating Amazon Q Business conversation responses.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: user, group.

user -> (structure)

The user associated with the principal.

id -> (string)

The identifier of the user.

access -> (string)

Provides information about whether to allow or deny access to the principal.

membershipType -> (string)

The type of group.

group -> (structure)

The group associated with the principal.

name -> (string)

The name of the group.

access -> (string)

Provides information about whether to allow or deny access to the principal.

membershipType -> (string)

The type of group.

memberRelation -> (string)

Describes the member relation within a principal list.

memberRelation -> (string)

Describes the member relation within the AccessControlList object.

documentEnrichmentConfiguration -> (structure)

The configuration information for altering document metadata and content during the document ingestion process.

inlineConfigurations -> (list)

Configuration information to alter document attributes or metadata fields and content when ingesting documents into Amazon Q Business.

(structure)

Provides the configuration information for applying basic logic to alter document metadata and content when ingesting documents into Amazon Q Business.

To apply advanced logic, to go beyond what you can do with basic logic, see ` HookConfiguration https://docs.aws.amazon.com/amazonq/latest/api-reference/API_HookConfiguration.html`__ .

For more information, see Custom document enrichment .

condition -> (structure)

The condition used for the target document attribute or metadata field when ingesting documents into Amazon Q Business. You use this with ` DocumentAttributeTarget https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeTarget.html`__ to apply the condition.

For example, you can create the 'Department' target field and have it prefill department names associated with the documents based on information in the 'Source_URI' field. Set the condition that if the 'Source_URI' field contains 'financial' in its URI value, then prefill the target field 'Department' with the target value 'Finance' for the document.

Amazon Q Business can't create a target field if it has not already been created as an index field. After you create your index field, you can create a document metadata field using DocumentAttributeTarget . Amazon Q Business then will map your newly created metadata field to your index field.

key -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently doesn't support _document_body as an attribute key used for the condition.

operator -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently does not support _document_body as an attribute key used for the condition.

value -> (tagged union structure)

The value of a document attribute. You can only provide one value for a document attribute.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.

stringValue -> (string)

A string.

stringListValue -> (list)

A list of strings.

(string)

longValue -> (long)

A long integer value.

dateValue -> (timestamp)

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.

target -> (structure)

The target document attribute or metadata field you want to alter when ingesting documents into Amazon Q Business.

For example, you can delete all customer identification numbers associated with the documents, stored in the document metadata field called 'Customer_ID' by setting the target key as 'Customer_ID' and the deletion flag to TRUE . This removes all customer ID values in the field 'Customer_ID'. This would scrub personally identifiable information from each document's metadata.

Amazon Q Business can't create a target field if it has not already been created as an index field. After you create your index field, you can create a document metadata field using ` DocumentAttributeTarget https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeTarget.html`__ . Amazon Q Business will then map your newly created document attribute to your index field.

You can also use this with ` DocumentAttributeCondition https://docs.aws.amazon.com/amazonq/latest/api-reference/API_DocumentAttributeCondition.html`__ .

key -> (string)

The identifier of the target document attribute or metadata field. For example, 'Department' could be an identifier for the target attribute or metadata field that includes the department names associated with the documents.

value -> (tagged union structure)

The value of a document attribute. You can only provide one value for a document attribute.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.

stringValue -> (string)

A string.

stringListValue -> (list)

A list of strings.

(string)

longValue -> (long)

A long integer value.

dateValue -> (timestamp)

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.

attributeValueOperator -> (string)

TRUE to delete the existing target value for your specified target attribute key. You cannot create a target value and set this to TRUE .

documentContentOperator -> (string)

TRUE to delete content if the condition used for the target attribute is met.

preExtractionHookConfiguration -> (structure)

Provides the configuration information for invoking a Lambda function in Lambda to alter document metadata and content when ingesting documents into Amazon Q Business.

You can configure your Lambda function using the PreExtractionHookConfiguration parameter if you want to apply advanced alterations on the original or raw documents.

If you want to apply advanced alterations on the Amazon Q Business structured documents, you must configure your Lambda function using PostExtractionHookConfiguration .

You can only invoke one Lambda function. However, this function can invoke other functions it requires.

For more information, see Custom document enrichment .

invocationCondition -> (structure)

The condition used for when a Lambda function should be invoked.

For example, you can specify a condition that if there are empty date-time values, then Amazon Q Business should invoke a function that inserts the current date-time.

key -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently doesn't support _document_body as an attribute key used for the condition.

operator -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently does not support _document_body as an attribute key used for the condition.

value -> (tagged union structure)

The value of a document attribute. You can only provide one value for a document attribute.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.

stringValue -> (string)

A string.

stringListValue -> (list)

A list of strings.

(string)

longValue -> (long)

A long integer value.

dateValue -> (timestamp)

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.

lambdaArn -> (string)

The Amazon Resource Name (ARN) of a role with permission to run a Lambda function during ingestion. For more information, see IAM roles for Custom Document Enrichment (CDE) .

s3BucketName -> (string)

Stores the original, raw documents or the structured, parsed documents before and after altering them. For more information, see Data contracts for Lambda functions .

roleArn -> (string)

The Amazon Resource Name (ARN) of a role with permission to run PreExtractionHookConfiguration and PostExtractionHookConfiguration for altering document metadata and content during the document ingestion process.

postExtractionHookConfiguration -> (structure)

Provides the configuration information for invoking a Lambda function in Lambda to alter document metadata and content when ingesting documents into Amazon Q Business.

You can configure your Lambda function using the PreExtractionHookConfiguration parameter if you want to apply advanced alterations on the original or raw documents.

If you want to apply advanced alterations on the Amazon Q Business structured documents, you must configure your Lambda function using PostExtractionHookConfiguration .

You can only invoke one Lambda function. However, this function can invoke other functions it requires.

For more information, see Custom document enrichment .

invocationCondition -> (structure)

The condition used for when a Lambda function should be invoked.

For example, you can specify a condition that if there are empty date-time values, then Amazon Q Business should invoke a function that inserts the current date-time.

key -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently doesn't support _document_body as an attribute key used for the condition.

operator -> (string)

The identifier of the document attribute used for the condition.

For example, 'Source_URI' could be an identifier for the attribute or metadata field that contains source URIs associated with the documents.

Amazon Q Business currently does not support _document_body as an attribute key used for the condition.

value -> (tagged union structure)

The value of a document attribute. You can only provide one value for a document attribute.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, stringListValue, longValue, dateValue.

stringValue -> (string)

A string.

stringListValue -> (list)

A list of strings.

(string)

longValue -> (long)

A long integer value.

dateValue -> (timestamp)

A date expressed as an ISO 8601 string.

It's important for the time zone to be included in the ISO 8601 date-time format. For example, 2012-03-25T12:30:10+01:00 is the ISO 8601 date-time format for March 25th 2012 at 12:30PM (plus 10 seconds) in Central European Time.

lambdaArn -> (string)

The Amazon Resource Name (ARN) of a role with permission to run a Lambda function during ingestion. For more information, see IAM roles for Custom Document Enrichment (CDE) .

s3BucketName -> (string)

Stores the original, raw documents or the structured, parsed documents before and after altering them. For more information, see Data contracts for Lambda functions .

roleArn -> (string)

The Amazon Resource Name (ARN) of a role with permission to run PreExtractionHookConfiguration and PostExtractionHookConfiguration for altering document metadata and content during the document ingestion process.

JSON Syntax:

[
  {
    "id": "string",
    "attributes": [
      {
        "name": "string",
        "value": {
          "stringValue": "string",
          "stringListValue": ["string", ...],
          "longValue": long,
          "dateValue": timestamp
        }
      }
      ...
    ],
    "content": {
      "blob": blob,
      "s3": {
        "bucket": "string",
        "key": "string"
      }
    },
    "contentType": "PDF"|"HTML"|"MS_WORD"|"PLAIN_TEXT"|"PPT"|"RTF"|"XML"|"XSLT"|"MS_EXCEL"|"CSV"|"JSON"|"MD",
    "title": "string",
    "accessConfiguration": {
      "accessControls": [
        {
          "principals": [
            {
              "user": {
                "id": "string",
                "access": "ALLOW"|"DENY",
                "membershipType": "INDEX"|"DATASOURCE"
              },
              "group": {
                "name": "string",
                "access": "ALLOW"|"DENY",
                "membershipType": "INDEX"|"DATASOURCE"
              }
            }
            ...
          ],
          "memberRelation": "AND"|"OR"
        }
        ...
      ],
      "memberRelation": "AND"|"OR"
    },
    "documentEnrichmentConfiguration": {
      "inlineConfigurations": [
        {
          "condition": {
            "key": "string",
            "operator": "GREATER_THAN"|"GREATER_THAN_OR_EQUALS"|"LESS_THAN"|"LESS_THAN_OR_EQUALS"|"EQUALS"|"NOT_EQUALS"|"CONTAINS"|"NOT_CONTAINS"|"EXISTS"|"NOT_EXISTS"|"BEGINS_WITH",
            "value": {
              "stringValue": "string",
              "stringListValue": ["string", ...],
              "longValue": long,
              "dateValue": timestamp
            }
          },
          "target": {
            "key": "string",
            "value": {
              "stringValue": "string",
              "stringListValue": ["string", ...],
              "longValue": long,
              "dateValue": timestamp
            },
            "attributeValueOperator": "DELETE"
          },
          "documentContentOperator": "DELETE"
        }
        ...
      ],
      "preExtractionHookConfiguration": {
        "invocationCondition": {
          "key": "string",
          "operator": "GREATER_THAN"|"GREATER_THAN_OR_EQUALS"|"LESS_THAN"|"LESS_THAN_OR_EQUALS"|"EQUALS"|"NOT_EQUALS"|"CONTAINS"|"NOT_CONTAINS"|"EXISTS"|"NOT_EXISTS"|"BEGINS_WITH",
          "value": {
            "stringValue": "string",
            "stringListValue": ["string", ...],
            "longValue": long,
            "dateValue": timestamp
          }
        },
        "lambdaArn": "string",
        "s3BucketName": "string",
        "roleArn": "string"
      },
      "postExtractionHookConfiguration": {
        "invocationCondition": {
          "key": "string",
          "operator": "GREATER_THAN"|"GREATER_THAN_OR_EQUALS"|"LESS_THAN"|"LESS_THAN_OR_EQUALS"|"EQUALS"|"NOT_EQUALS"|"CONTAINS"|"NOT_CONTAINS"|"EXISTS"|"NOT_EXISTS"|"BEGINS_WITH",
          "value": {
            "stringValue": "string",
            "stringListValue": ["string", ...],
            "longValue": long,
            "dateValue": timestamp
          }
        },
        "lambdaArn": "string",
        "s3BucketName": "string",
        "roleArn": "string"
      }
    }
  }
  ...
]

--role-arn (string)

The Amazon Resource Name (ARN) of an IAM role with permission to access your S3 bucket.

--data-source-sync-id (string)

The identifier of the data source sync during which the documents were added.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

Global Options¶

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command's default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination.

--output (string)

The formatting style for command output.

json
text
table

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

on
off
auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

Output¶

failedDocuments -> (list)

A list of documents that were not added to the Amazon Q Business index because the document failed a validation check. Each document contains an error message that indicates why the document couldn't be added to the index.

(structure)

A list of documents that could not be removed from an Amazon Q Business index. Each entry contains an error message that indicates why the document couldn't be removed from the index.

id -> (string)

The identifier of the document that couldn't be removed from the Amazon Q Business index.

error -> (structure)

An explanation for why the document couldn't be removed from the index.

errorMessage -> (string)

The message explaining the data source sync error.

errorCode -> (string)

The code associated with the data source sync error.

dataSourceId -> (string)

The identifier of the Amazon Q Business data source connector that contains the failed document.

Table Of Contents

Feedback

User Guide

Note:

batch-put-document¶

Description¶

Synopsis¶

Options¶

Note

Note

Note

Note

Note

Note

Note

Global Options¶

Output¶