Связаться с намиПодключиться

Метод BatchWriteItem

Статья создана
Обновлена 12 июля 2022 г.

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

BatchWriteItem не может обновлять элементы. Для этого используется метод UpdateItem.

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

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

Вся операция пакетной записи может быть отклонена:

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

Запрос

Запрос содержит данные в формате 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 Ассоциативный массив таблиц и запросов к ним, которые необходимо выполнить.
Каждая запись состоит из имени таблицы и списка операций, которые необходимо выполнить (DeleteRequest или PutRequest).
  • DeleteRequest — выполнить операцию DeleteItem для указанного элемента. Удаляемый элемент идентифицируется параметром Key и вложенным элементом:
    • Key — ассоциативный массив значений атрибутов первичного ключа, которые однозначно идентифицируют элемент. Каждая запись состоит из имени и значения атрибута.
      Для каждого первичного ключа нужно указать все его ключевые атрибуты. Для простого первичного ключа нужно указать только его значение. Для составного первичного ключа нужно указать значение ключа раздела и ключа сортировки.
  • PutRequest — выполнить операцию PutItem для указанного элемента. Вставляемый элемент идентифицируется параметром Item и вложенным элементом:
    • Item — ассоциативный массив атрибутов и их значений. Каждая запись состоит из имени и значения атрибута. Значения атрибутов не должны быть нулевыми; атрибуты строкового и двоичного типов должны иметь длину больше нуля; и атрибуты типа набор не должны быть пустыми. Запросы, содержащие пустые значения, отклоняются с исключением ValidationException.
    Тип: ассоциативный массив типа WriteRequest.
    Кол-во записей: максимум 25 элементов.
    Длина ключа: 3 - 255 символов.
    Шаблон: [a-zA-Z0-9_.-]+
    Размер массива: 1 - 25 элементов.
    Обязательно: Да
ReturnConsumedCapacity Нужно ли возвращать информацию о потребляемой мощности.
  • TOTAL — возвращать информацию.
  • NONE — не возвращать информацию.

Тип: Строка
Возможные значения: TOTAL | NONE
Обязательно: Нет

Ответ

В случае успеха вернется HTTP с кодом 200.
Запрос возвращает данные в формате 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 Потребленные единицы мощности.
Возвращается только в том случае, если в запросе был указан параметр ReturnConsumedCapacity со значением TOTAL.
Состоит из:
  • TableName — таблица, потребляющая выделенную пропускную способность.
  • CapacityUnits — общее количество потребленных единиц мощности.

Тип: Массив объектов типа ConsumedCapacity
UnprocessedItems Ассоциативный массив таблиц и запросов к ним, которые не были обработаны. Записи приходят в том же виде, как были заданы в запросе в параметре RequestItems. Следовательно, эти значения можно повторно использовать в следующем запросе.
Если необработанных элементов не осталось, то UnprocessedItems будет пустой.

Тип: ассоциативный массив типа WriteRequest.
Кол-во записей: максимум 25 элементов.
Длина ключа: 3 - 255 символов.
Шаблон: [a-zA-Z0-9_.-]+
Размер массива: 1 - 25 элементов.

Ошибки

Параметр Описание
InternalServerError Произошла внутренняя ошибка на стороне сервера.

Код состояния HTTP: 500
ProvisionedThroughputExceededException Вы слишком часто отправляете запросы. Попробуйте увеличить интервалы между запросами.
Если таких запросов будет не слишком много, Managed Service for YDB постарается обработать их все.

Код состояния HTTP: 400
RequestLimitExceeded Пропускная способность превышает квоту.

Код состояния HTTP: 400
ResourceNotFoundException Указанная таблица не существует.

Код состояния HTTP: 400

Также могут возникать Общие ошибки, одинаковые для всех методов.

Предыдущая
BatchGetItem
Следующая
CreateTable