[Документация Yandex Cloud](../../../../index.md) > [Yandex Managed Service for YDB](../../../index.md) > Document API, совместимый с Amazon DynamoDB > [Справочник Document API](../index.md) > Actions > BatchGetItem

# Метод BatchGetItem

Возвращает атрибуты одного или нескольких элементов из одной или нескольких таблиц. Запрашиваемые элементы нужно указать по первичному ключу.

За один раз вернется до 16 Мб данных или до 100 записей. Например, если запросить 100 записей по 300 Кб каждая, то вернется только 52 записи (чтобы не превышать ограничение в 16 Мб).
Если возвращается частичный (неполный) результат, то оставшиеся записи вернутся в параметре `UnprocessedKeys`. Их можно использовать для повторного запроса.
Если из-за недостаточной пропускной способности не вернется ни один элемент, то метод вернет ошибку `ProvisionedThroughputExceededException`. Если будет обработан хотя бы один элемент, то метод завершится успешно, а необработанные ключи вернутся в параметре `UnprocessedKeys`.

По умолчанию метод выполняет последовательное чтение из каждой таблицы. Если нужно использовать строгое согласованное чтение, то необходимо установить параметр `ConsistentRead=true`.

## Запрос

Запрос содержит данные в формате JSON.

```json
{
   "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"
}
```

### Параметры

Параметр | Описание
----- | -----
`RequestItems` | Ассоциативный массив с названиями таблиц, где для каждой таблицы также указан ассоциативный массив с извлекаемыми элементами.<br/>Каждый элемент состоит из:<ul><li>`ConsistentRead` — если `true`, то используется строго согласованное чтение; если `false` (по умолчанию), то используется последовательное чтение.<br/><li> `ExpressionAttributeNames` — заполнитель(placeholder), который можно использовать в выражении вместо имени атрибута. Заполнитель должен начинаться с символа решетки `#`.<br/>Это может пригодиться в нескольких случаях:<ul><li>Нужно указать атрибут, имя которого конфликтует с зарезервированным словом.<li>В качестве переменной, если имя атрибута используется в выражении несколько раз.<li>Для предотвращения неправильной интерпретации специальных символов в имени атрибута.</ul>Например, имя атрибута `Percentile` конфликтует с зарезервированным словом, и его нельзя в явном виде использовать в выражении. Чтобы обойти эту проблему, нужно в параметре `ExpressionAttributeNames` указать заполнитель: `{"#P":"Percentile"}`. И затем вместо настоящего имени атрибута  использовать `#P`.<li>`Keys` — массив значений атрибутов первичного ключа, которые необходимо извлечь. Для каждого первичного ключа необходимо указать все ключевые атрибуты. Для простого первичного ключа нужно указать только его значение. Для составного первичного ключа нужно указать значение ключа раздела и ключа сортировки.<li>`ProjectionExpression` — атрибуты, которые нужно извлечь. Атрибуты должны быть разделены запятыми.<br/>Если имена атрибутов не указаны явно, то возвращаются все атрибуты.</ul><br/>**Тип**: Строка типа `KeysAndAttributes`<br/>**Кол-во записей**: максимум 100 элементов.<br/>**Длина ключа**: 3 - 255 символов.<br/>**Шаблон**: [a-zA-Z0-9_.-]+<br/>**Обязательно**: Да
`ReturnConsumedCapacity` | Нужно ли возвращать информацию о потребляемой мощности.<ul><li>`TOTAL` — возвращать информацию.<li>`NONE` — не возвращать информацию.</ul><br/>**Тип**: Строка<br/>**Возможные значения**: `TOTAL` \| `NONE`<br/>**Обязательно**: Нет

## Ответ

В случае успеха вернется HTTP с кодом 200.
Запрос возвращает данные в формате JSON.

```json
{
   "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"
      }
   }
}
```

### Параметры

Параметр | Описание
----- | -----
`ConsumedCapacity` | Потребленные единицы мощности.<br/>Возвращается только в том случае, если в запросе был указан параметр `ReturnConsumedCapacity` со значением `TOTAL`.<br/>Состоит из:<ul><li>`TableName` — таблица, потребляющая выделенную пропускную способность.<li>`CapacityUnits` — общее количество потребленных единиц мощности.</ul><br/>**Тип**: Массив объектов типа `ConsumedCapacity`
`Responses` | Ассоциативный массив таблиц, в котором находятся извлеченные записи.<br/><br/>**Тип**: Ассоциативный массив типа `AttributeValue`.<br/>**Длина ключа**: 3 - 255 символов.<br/>**Шаблон**: [a-zA-Z0-9_.-]+
`UnprocessedKeys` | Ассоциативный массив таблиц, в котором находятся необработанные записи. Записи приходят в том же виде, как были заданы в запросе в параметре `RequestItems`. Следовательно, эти значения можно повторно использовать в следующем запросе.<br/>Каждый элемент состоит из:<ul><li>`Keys` — массив значений атрибутов первичного ключа.<li>`ProjectionExpression` — извлеченные атрибуты.<li>`ConsistentRead` — если `true`, то используется строго согласованное чтение; если `false` (по умолчанию), то используется последовательное чтение.</ul>Если необработанных элементов не осталось, то `UnprocessedKeys` будет пустой.<br/><br/>**Тип**: ассоциативный массив типа `KeysAndAttributes`.<br/>**Кол-во записей**: максимум 100 элементов.<br/>**Длина ключа**: 3 - 255 символов.<br/>**Шаблон**: [a-zA-Z0-9_.-]+

## Ошибки

Параметр | Описание
----- | -----
`InternalServerError` | Произошла внутренняя ошибка на стороне сервера.<br/><br/>**Код состояния HTTP**: 500
`ProvisionedThroughputExceededException` | Вы слишком часто отправляете запросы. Попробуйте увеличить интервалы между запросами.<br/>Если таких запросов будет не слишком много, Managed Service for YDB постарается обработать их все.<br/><br/>**Код состояния HTTP**: 400
`RequestLimitExceeded` | Пропускная способность превышает квоту.<br/><br/>**Код состояния HTTP**: 400
`ResourceNotFoundException` | Указанная таблица не существует.<br/><br/>**Код состояния HTTP**: 400

Также могут возникать [Общие ошибки](../../common-errors.md), одинаковые для всех методов.