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

# Метод BatchWriteItem

Записывает или удаляет элементы из таблиц.
Один вызов может записать до 16 Мб данных, что может включать до 25 запросов на размещение или удаление. Каждый элемент может иметь размер до 400 Кб.

`BatchWriteItem` не может обновлять элементы. Для этого используется метод [UpdateItem](updateItem.md).

Отдельно операции `PutItem` и `DeleteItem`, используемые в `BatchWriteItem` - атомарны. Но весь метод в целом - нет.

Если из-за недостаточной пропускной способности не обработается ни один элемент, то метод вернет ошибку `ProvisionedThroughputExceededException`. Если будет обработан хотя бы один элемент, то метод завершится успешно, а необработанные элементы вернутся в параметре `UnprocessedItems`.

Вся операция пакетной записи может быть отклонена:
- Указанная в запросе таблица не существует.
- Атрибуты первичного ключа, указанные в запросе, не соответствуют атрибутам в схеме первичного ключа таблицы.
- Вы пытаетесь выполнить несколько операций с одним и тем же элементом в одном запросе.
- Запрос содержит как минимум два элемента с одинаковыми hash- и range-ключами.
- В пакете более 25 запросов.
- Размер любого отдельного элемента в пакете превышает 400 Кб.
- Общий размер запроса превышает 16 Мб.

## Запрос

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

```json
{
   "RequestItems": { 
      "string" : [ 
         { 
            "DeleteRequest": { 
               "Key": { 
                  "string" : { 
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [ 
                        "AttributeValue"
                     ],
                     "M": { 
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            },
            "PutRequest": { 
               "Item": { 
                  "string" : { 
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [ 
                        "AttributeValue"
                     ],
                     "M": { 
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            }
         }
      ]
   },
   "ReturnConsumedCapacity": "string"
}
```

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

Параметр | Описание
----- | -----
`RequestItems` | Ассоциативный массив таблиц и запросов к ним, которые необходимо выполнить.<br/> Каждая запись состоит из имени таблицы и списка операций, которые необходимо выполнить (`DeleteRequest` или `PutRequest`).<ul> <li>`DeleteRequest` — выполнить операцию `DeleteItem` для указанного элемента. Удаляемый элемент идентифицируется параметром `Key` и вложенным элементом:<ul><li>`Key` — ассоциативный массив значений атрибутов первичного ключа, которые однозначно идентифицируют элемент. Каждая запись состоит из имени и значения атрибута.<br/>Для каждого первичного ключа нужно указать все его ключевые атрибуты. Для простого первичного ключа нужно указать только его значение. Для составного первичного ключа нужно указать значение ключа раздела и ключа сортировки.</ul><li>`PutRequest` — выполнить операцию `PutItem` для указанного элемента. Вставляемый элемент идентифицируется параметром `Item` и вложенным элементом:<ul><li>`Item` — ассоциативный массив атрибутов и их значений. Каждая запись состоит из имени и значения атрибута. Значения атрибутов не должны быть нулевыми; атрибуты строкового и двоичного типов должны иметь длину больше нуля; и атрибуты типа набор не должны быть пустыми. Запросы, содержащие пустые значения, отклоняются с исключением `ValidationException`.<br/></ul>**Тип**: ассоциативный массив типа `WriteRequest`.<br/>**Кол-во записей**: максимум 25 элементов.<br/>**Длина ключа**: 3 - 255 символов.<br/>**Шаблон**: [a-zA-Z0-9_.-]+<br/>**Размер массива**: 1 - 25 элементов.<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
      }
   ],
   "UnprocessedItems": { 
      "string" : [ 
         { 
            "DeleteRequest": { 
               "Key": { 
                  "string" : { 
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [ 
                        "AttributeValue"
                     ],
                     "M": { 
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            },
            "PutRequest": { 
               "Item": { 
                  "string" : { 
                     "B": blob,
                     "BOOL": boolean,
                     "BS": [ blob ],
                     "L": [ 
                        "AttributeValue"
                     ],
                     "M": { 
                        "string" : "AttributeValue"
                     },
                     "N": "string",
                     "NS": [ "string" ],
                     "NULL": boolean,
                     "S": "string",
                     "SS": [ "string" ]
                  }
               }
            }
         }
      ]
   }
}
```

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

Параметр | Описание
----- | -----
`ConsumedCapacity` | Потребленные единицы мощности.<br/>Возвращается только в том случае, если в запросе был указан параметр `ReturnConsumedCapacity` со значением `TOTAL`.<br/>Состоит из:<ul><li>`TableName` — таблица, потребляющая выделенную пропускную способность.<li>`CapacityUnits` — общее количество потребленных единиц мощности.</ul><br/>**Тип**: Массив объектов типа `ConsumedCapacity`
`UnprocessedItems` | Ассоциативный массив таблиц и запросов к ним, которые не были обработаны. Записи приходят в том же виде, как были заданы в запросе в параметре `RequestItems`. Следовательно, эти значения можно повторно использовать в следующем запросе.<br/>Если необработанных элементов не осталось, то `UnprocessedItems` будет пустой.<br/><br/>**Тип**: ассоциативный массив типа `WriteRequest`.<br/>**Кол-во записей**: максимум 25 элементов.<br/>**Длина ключа**: 3 - 255 символов.<br/>**Шаблон**: [a-zA-Z0-9_.-]+<br/>**Размер массива**: 1 - 25 элементов.

## Ошибки

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

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