BatchGetItem method

Written by

Updated at April 24, 2026

Request
- Parameters
Response
- Parameters
Errors

Returns the attributes of one or multiple items from one or multiple tables. Specify the items by primary key in your request.

You may get up to 16 MB of data with as many as 100 items in a single response. For example, if you request 100 items of 300 KB each, you will only get 52 items to stay within the 16 MB limit.
If you get a partial (incomplete) result, the remaining items will be returned under UnprocessedKeys. You can use them to repeat the request.
If you do not get any items because there is not enough throughput, the method will return the ProvisionedThroughputExceededException error. If at least one item is processed, the method will complete successfully, while unprocessed keys will be returned under UnprocessedKeys.

By default, the method performs sequential reads from each table. To use strongly consistent reads, set ConsistentRead=true.

Request

The request contains data in JSON format.

{
   "RequestItems": {
      "string" : {
         "AttributesToGet": [ "string" ],
         "ConsistentRead": boolean,
         "ExpressionAttributeNames": {
            "string" : "string"
         },
         "Keys": [
            {
               "string" : {
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [
                     "AttributeValue"
                  ],
                  "M": {
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            }
         ],
         "ProjectionExpression": "string"
      }
   },
   "ReturnConsumedCapacity": "string"
}

Parameters

Parameter Description

Parameter	Description
`RequestItems`	Associative array of table names, where an associative array of items to retrieve is also specified for each table. Each item consists of: `ConsistentRead`: `true` enables strongly consistent reads; `false` (by default) enables sequential reads. `ExpressionAttributeNames`: Placeholder for an attribute name in an expression. The placeholder must start with the hash character, `#`. You can use it in the following cases: To specify an attribute whose name conflicts with a reserved word. As a variable, if the attribute name is used multiple times in an expression. To prevent incorrect interpretation of special characters in the attribute name. For example, the `Percentile` attribute name conflicts with the reserved word, so you cannot use it explicitly in an expression. To fix this issue, specify the `{"#P":"Percentile"}` placeholder in the `ExpressionAttributeNames` parameter, and then, further on, use `#P` instead of the real attribute name. `Keys`: Array of primary key attribute values to retrieve. For each primary key, specify all the key attributes. For a simple primary key, you only need to specify its value. For a composite primary key, specify values for both the partition key and the sort key. `ProjectionExpression`: Attributes to retrieve. List the attributes separated with commas. If you do not explicitly specify the attribute names, all item attributes will be returned. Type: String of the `KeysAndAttributes` type Number of records type: Up to 100 items. Key length: 3 to 255 characters. Template: [a-zA-Z0-9_.-]+ Required: Yes
`ReturnConsumedCapacity`	Sets whether to return information about the consumed capacity. `TOTAL`: Return. `NONE`: Do not return. Type: String Possible values: `TOTAL` \| `NONE` Required: No

RequestItems

Associative array of table names, where an associative array of items to retrieve is also specified for each table.
Each item consists of:

ConsistentRead: true enables strongly consistent reads; false (by default) enables sequential reads.
ExpressionAttributeNames: Placeholder for an attribute name in an expression. The placeholder must start with the hash character, #.
You can use it in the following cases:
- To specify an attribute whose name conflicts with a reserved word.
- As a variable, if the attribute name is used multiple times in an expression.
- To prevent incorrect interpretation of special characters in the attribute name.
For example, the Percentile attribute name conflicts with the reserved word, so you cannot use it explicitly in an expression. To fix this issue, specify the {"#P":"Percentile"} placeholder in the ExpressionAttributeNames parameter, and then, further on, use #P instead of the real attribute name.
Keys: Array of primary key attribute values to retrieve. For each primary key, specify all the key attributes. For a simple primary key, you only need to specify its value. For a composite primary key, specify values for both the partition key and the sort key.
ProjectionExpression: Attributes to retrieve. List the attributes separated with commas.
If you do not explicitly specify the attribute names, all item attributes will be returned.

Type: String of the KeysAndAttributes type
Number of records type: Up to 100 items.
Key length: 3 to 255 characters.
Template: [a-zA-Z0-9_.-]+
Required: Yes

ReturnConsumedCapacity

Sets whether to return information about the consumed capacity.

TOTAL: Return.
NONE: Do not return.

Type: String
Possible values: TOTAL | NONE
Required: No

Response

If successful, HTTP code 200 is returned.
You will get data in JSON format.

{
   "ConsumedCapacity": [
      {
         "CapacityUnits": number,
         "GlobalSecondaryIndexes": {
            "string" : {
               "CapacityUnits": number,
               "ReadCapacityUnits": number,
               "WriteCapacityUnits": number
            }
         },
         "LocalSecondaryIndexes": {
            "string" : {
               "CapacityUnits": number,
               "ReadCapacityUnits": number,
               "WriteCapacityUnits": number
            }
         },
         "ReadCapacityUnits": number,
         "Table": {
            "CapacityUnits": number,
            "ReadCapacityUnits": number,
            "WriteCapacityUnits": number
         },
         "TableName": "string",
         "WriteCapacityUnits": number
      }
   ],
   "Responses": {
      "string" : [
         {
            "string" : {
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [
                  "AttributeValue"
               ],
               "M": {
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         }
      ]
   },
   "UnprocessedKeys": {
      "string" : {
         "AttributesToGet": [ "string" ],
         "ConsistentRead": boolean,
         "ExpressionAttributeNames": {
            "string" : "string"
         },
         "Keys": [
            {
               "string" : {
                  "B": blob,
                  "BOOL": boolean,
                  "BS": [ blob ],
                  "L": [
                     "AttributeValue"
                  ],
                  "M": {
                     "string" : "AttributeValue"
                  },
                  "N": "string",
                  "NS": [ "string" ],
                  "NULL": boolean,
                  "S": "string",
                  "SS": [ "string" ]
               }
            }
         ],
         "ProjectionExpression": "string"
      }
   }
}

Parameters

Parameter	Description
`ConsumedCapacity`	Consumed capacity units. It is returned only if you provide `ReturnConsumedCapacity` set to `TOTAL` in the request. It consists of: `TableName`: Table that consumes the provisioned throughput capacity. `CapacityUnits`: Total number of capacity units consumed. Type: Array of `ConsumedCapacity` objects
`Responses`	Associative array of tables with retrieved items. Type: Associative array of the `AttributeValue` type. Key length: 3 to 255 characters. Template: [a-zA-Z0-9_.-]+
`UnprocessedKeys`	Associative array of tables with unprocessed items. The values have the format you set in the `RequestItems` parameter. You can reuse these values in a subsequent request. Each item consists of: `Keys`: Array of primary key attribute values. `ProjectionExpression`: Attributes you retrieved. `ConsistentRead`: `true` enables strongly consistent reads; `false` (by default) enables sequential reads. If there are no unprocessed items left, the `UnprocessedKeys` response parameter will be empty. Type: Associative array of the `KeysAndAttributes` type. Number of records: Up to 100 items. Key length: 3 to 255 characters. Template: [a-zA-Z0-9_.-]+

Errors

Parameter	Description
`InternalServerError`	An internal error occurred on the server side. HTTP status code: 500
`ProvisionedThroughputExceededException`	Your request rate is too high. Try to reduce the frequency of requests. If their number is not too large, Managed Service for YDB will try to process them all. HTTP status code: 400
`RequestLimitExceeded`	The throughput capacity exceeds the set quota. HTTP status code: 400
`ResourceNotFoundException`	The requested table does not exist. HTTP status code: 400

There may be some common errors as well shared by all methods.

BatchGetItem method

RequestRequest

ParametersParameters

ResponseResponse

ParametersParameters

ErrorsErrors

Was the article helpful?

Request

Parameters

Response

Parameters

Errors