DynamoDB / Client / batch_execute_statement

batch_execute_statement#

DynamoDB.Client.batch_execute_statement(**kwargs)#

This operation allows you to perform batch reads or writes on data stored in DynamoDB, using PartiQL. Each read statement in a BatchExecuteStatement must specify an equality condition on all key attributes. This enforces that each SELECT statement in a batch returns at most a single item. For more information, see Running batch operations with PartiQL for DynamoDB.

Note

The entire batch must consist of either read statements or write statements, you cannot mix both in one batch.

Warning

A HTTP 200 response does not mean that all statements in the BatchExecuteStatement succeeded. Error details for individual statements can be found under the Error field of the BatchStatementResponse for each statement.

See also: AWS API Documentation

Request Syntax

response = client.batch_execute_statement(
    Statements=[
        {
            'Statement': 'string',
            'Parameters': [
                {
                    'S': 'string',
                    'N': 'string',
                    'B': b'bytes',
                    'SS': [
                        'string',
                    ],
                    'NS': [
                        'string',
                    ],
                    'BS': [
                        b'bytes',
                    ],
                    'M': {
                        'string': {'... recursive ...'}
                    },
                    'L': [
                        {'... recursive ...'},
                    ],
                    'NULL': True|False,
                    'BOOL': True|False
                },
            ],
            'ConsistentRead': True|False,
            'ReturnValuesOnConditionCheckFailure': 'ALL_OLD'|'NONE'
        },
    ],
    ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE'
)
Parameters:

  • Statements (list) –

    [REQUIRED]

    The list of PartiQL statements representing the batch to run.

    • (dict) –

      A PartiQL batch statement request.

      • Statement (string) – [REQUIRED]

        A valid PartiQL statement.

      • Parameters (list) –

        The parameters associated with a PartiQL statement in the batch request.

        • (dict) –

          Represents the data for an attribute.

          Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

          For more information, see Data Types in the Amazon DynamoDB Developer Guide.

          • S (string) –

            An attribute of type String. For example:

            "S": "Hello"

          • N (string) –

            An attribute of type Number. For example:

            "N": "123.45"

            Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

          • B (bytes) –

            An attribute of type Binary. For example:

            "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

          • SS (list) –

            An attribute of type String Set. For example:

            "SS": ["Giraffe", "Hippo" ,"Zebra"]

            • (string) –

          • NS (list) –

            An attribute of type Number Set. For example:

            "NS": ["42.2", "-19", "7.5", "3.14"]

            Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

            • (string) –

          • BS (list) –

            An attribute of type Binary Set. For example:

            "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

            • (bytes) –

          • M (dict) –

            An attribute of type Map. For example:

            "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

            • (string) –

              • (dict) –

                Represents the data for an attribute.

                Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                For more information, see Data Types in the Amazon DynamoDB Developer Guide.

          • L (list) –

            An attribute of type List. For example:

            "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]

            • (dict) –

              Represents the data for an attribute.

              Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

              For more information, see Data Types in the Amazon DynamoDB Developer Guide.

          • NULL (boolean) –

            An attribute of type Null. For example:

            "NULL": true

          • BOOL (boolean) –

            An attribute of type Boolean. For example:

            "BOOL": true

      • ConsistentRead (boolean) –

        The read consistency of the PartiQL batch request.

      • ReturnValuesOnConditionCheckFailure (string) –

        An optional parameter that returns the item attributes for a PartiQL batch request operation that failed a condition check.

        There is no additional cost associated with requesting a return value aside from the small network and processing overhead of receiving a larger response. No read capacity units are consumed.

  • ReturnConsumedCapacity (string) –

    Determines the level of detail about either provisioned or on-demand throughput consumption that is returned in the response:

    • INDEXES - The response includes the aggregate ConsumedCapacity for the operation, together with ConsumedCapacity for each table and secondary index that was accessed. Note that some operations, such as GetItem and BatchGetItem, do not access any indexes at all. In these cases, specifying INDEXES will only return ConsumedCapacity information for table(s).

    • TOTAL - The response includes only the aggregate ConsumedCapacity for the operation.

    • NONE - No ConsumedCapacity details are included in the response.

Return type:

dict

Returns:

Response Syntax

{
    'Responses': [
        {
            'Error': {
                'Code': 'ConditionalCheckFailed'|'ItemCollectionSizeLimitExceeded'|'RequestLimitExceeded'|'ValidationError'|'ProvisionedThroughputExceeded'|'TransactionConflict'|'ThrottlingError'|'InternalServerError'|'ResourceNotFound'|'AccessDenied'|'DuplicateItem',
                'Message': 'string',
                'Item': {
                    'string': {
                        'S': 'string',
                        'N': 'string',
                        'B': b'bytes',
                        'SS': [
                            'string',
                        ],
                        'NS': [
                            'string',
                        ],
                        'BS': [
                            b'bytes',
                        ],
                        'M': {
                            'string': {'... recursive ...'}
                        },
                        'L': [
                            {'... recursive ...'},
                        ],
                        'NULL': True|False,
                        'BOOL': True|False
                    }
                }
            },
            'TableName': 'string',
            'Item': {
                'string': {
                    'S': 'string',
                    'N': 'string',
                    'B': b'bytes',
                    'SS': [
                        'string',
                    ],
                    'NS': [
                        'string',
                    ],
                    'BS': [
                        b'bytes',
                    ],
                    'M': {
                        'string': {'... recursive ...'}
                    },
                    'L': [
                        {'... recursive ...'},
                    ],
                    'NULL': True|False,
                    'BOOL': True|False
                }
            }
        },
    ],
    'ConsumedCapacity': [
        {
            'TableName': 'string',
            'CapacityUnits': 123.0,
            'ReadCapacityUnits': 123.0,
            'WriteCapacityUnits': 123.0,
            'Table': {
                'ReadCapacityUnits': 123.0,
                'WriteCapacityUnits': 123.0,
                'CapacityUnits': 123.0
            },
            'LocalSecondaryIndexes': {
                'string': {
                    'ReadCapacityUnits': 123.0,
                    'WriteCapacityUnits': 123.0,
                    'CapacityUnits': 123.0
                }
            },
            'GlobalSecondaryIndexes': {
                'string': {
                    'ReadCapacityUnits': 123.0,
                    'WriteCapacityUnits': 123.0,
                    'CapacityUnits': 123.0
                }
            }
        },
    ]
}

Response Structure

  • (dict) –

    • Responses (list) –

      The response to each PartiQL statement in the batch. The values of the list are ordered according to the ordering of the request statements.

      • (dict) –

        A PartiQL batch statement response..

        • Error (dict) –

          The error associated with a failed PartiQL batch statement.

          • Code (string) –

            The error code associated with the failed PartiQL batch statement.

          • Message (string) –

            The error message associated with the PartiQL batch response.

          • Item (dict) –

            The item which caused the condition check to fail. This will be set if ReturnValuesOnConditionCheckFailure is specified as ALL_OLD.

            • (string) –

              • (dict) –

                Represents the data for an attribute.

                Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                For more information, see Data Types in the Amazon DynamoDB Developer Guide.

                • S (string) –

                  An attribute of type String. For example:

                  "S": "Hello"

                • N (string) –

                  An attribute of type Number. For example:

                  "N": "123.45"

                  Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

                • B (bytes) –

                  An attribute of type Binary. For example:

                  "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

                • SS (list) –

                  An attribute of type String Set. For example:

                  "SS": ["Giraffe", "Hippo" ,"Zebra"]

                  • (string) –

                • NS (list) –

                  An attribute of type Number Set. For example:

                  "NS": ["42.2", "-19", "7.5", "3.14"]

                  Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

                  • (string) –

                • BS (list) –

                  An attribute of type Binary Set. For example:

                  "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

                  • (bytes) –

                • M (dict) –

                  An attribute of type Map. For example:

                  "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

                  • (string) –

                    • (dict) –

                      Represents the data for an attribute.

                      Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                      For more information, see Data Types in the Amazon DynamoDB Developer Guide.

                • L (list) –

                  An attribute of type List. For example:

                  "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]

                  • (dict) –

                    Represents the data for an attribute.

                    Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                    For more information, see Data Types in the Amazon DynamoDB Developer Guide.

                • NULL (boolean) –

                  An attribute of type Null. For example:

                  "NULL": true

                • BOOL (boolean) –

                  An attribute of type Boolean. For example:

                  "BOOL": true

        • TableName (string) –

          The table name associated with a failed PartiQL batch statement.

        • Item (dict) –

          A DynamoDB item associated with a BatchStatementResponse

          • (string) –

            • (dict) –

              Represents the data for an attribute.

              Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

              For more information, see Data Types in the Amazon DynamoDB Developer Guide.

              • S (string) –

                An attribute of type String. For example:

                "S": "Hello"

              • N (string) –

                An attribute of type Number. For example:

                "N": "123.45"

                Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

              • B (bytes) –

                An attribute of type Binary. For example:

                "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"

              • SS (list) –

                An attribute of type String Set. For example:

                "SS": ["Giraffe", "Hippo" ,"Zebra"]

                • (string) –

              • NS (list) –

                An attribute of type Number Set. For example:

                "NS": ["42.2", "-19", "7.5", "3.14"]

                Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.

                • (string) –

              • BS (list) –

                An attribute of type Binary Set. For example:

                "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]

                • (bytes) –

              • M (dict) –

                An attribute of type Map. For example:

                "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}

                • (string) –

                  • (dict) –

                    Represents the data for an attribute.

                    Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                    For more information, see Data Types in the Amazon DynamoDB Developer Guide.

              • L (list) –

                An attribute of type List. For example:

                "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]

                • (dict) –

                  Represents the data for an attribute.

                  Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.

                  For more information, see Data Types in the Amazon DynamoDB Developer Guide.

              • NULL (boolean) –

                An attribute of type Null. For example:

                "NULL": true

              • BOOL (boolean) –

                An attribute of type Boolean. For example:

                "BOOL": true

    • ConsumedCapacity (list) –

      The capacity units consumed by the entire operation. The values of the list are ordered according to the ordering of the statements.

      • (dict) –

        The capacity units consumed by an operation. The data returned includes the total provisioned throughput consumed, along with statistics for the table and any indexes involved in the operation. ConsumedCapacity is only returned if the request asked for it. For more information, see Provisioned capacity mode in the Amazon DynamoDB Developer Guide.

        • TableName (string) –

          The name of the table that was affected by the operation. If you had specified the Amazon Resource Name (ARN) of a table in the input, you’ll see the table ARN in the response.

        • CapacityUnits (float) –

          The total number of capacity units consumed by the operation.

        • ReadCapacityUnits (float) –

          The total number of read capacity units consumed by the operation.

        • WriteCapacityUnits (float) –

          The total number of write capacity units consumed by the operation.

        • Table (dict) –

          The amount of throughput consumed on the table affected by the operation.

          • ReadCapacityUnits (float) –

            The total number of read capacity units consumed on a table or an index.

          • WriteCapacityUnits (float) –

            The total number of write capacity units consumed on a table or an index.

          • CapacityUnits (float) –

            The total number of capacity units consumed on a table or an index.

        • LocalSecondaryIndexes (dict) –

          The amount of throughput consumed on each local index affected by the operation.

          • (string) –

            • (dict) –

              Represents the amount of provisioned throughput capacity consumed on a table or an index.

              • ReadCapacityUnits (float) –

                The total number of read capacity units consumed on a table or an index.

              • WriteCapacityUnits (float) –

                The total number of write capacity units consumed on a table or an index.

              • CapacityUnits (float) –

                The total number of capacity units consumed on a table or an index.

        • GlobalSecondaryIndexes (dict) –

          The amount of throughput consumed on each global index affected by the operation.

          • (string) –

            • (dict) –

              Represents the amount of provisioned throughput capacity consumed on a table or an index.

              • ReadCapacityUnits (float) –

                The total number of read capacity units consumed on a table or an index.

              • WriteCapacityUnits (float) –

                The total number of write capacity units consumed on a table or an index.

              • CapacityUnits (float) –

                The total number of capacity units consumed on a table or an index.

Exceptions