:doc:`DynamoDB <../../dynamodb>` / Client / batch_execute_statement

***********************
batch_execute_statement
***********************



.. py:method:: 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.multiplestatements.batching.html>`__.

   

  .. 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 <https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchStatementResponse.html#DDB-Type-BatchStatementResponse-Error>`__ field of the ``BatchStatementResponse`` for each statement.

    

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/dynamodb-2012-08-10/BatchExecuteStatement>`_  


  **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'
    )
    
  :type Statements: list
  :param Statements: **[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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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.

        

      
    

  :type ReturnConsumedCapacity: string
  :param ReturnConsumedCapacity: 

    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.
    

    

  
  
  :rtype: 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes>`__ 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 <https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/provisioned-capacity-mode.html>`__ 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**
  
  *   :py:class:`DynamoDB.Client.exceptions.RequestLimitExceeded`

  
  *   :py:class:`DynamoDB.Client.exceptions.InternalServerError`

  
  *   :py:class:`DynamoDB.Client.exceptions.ThrottlingException`

  