batch-write-item

Описание

Операция BatchWriteItem добавляет или удаляет несколько элементов в одной или нескольких таблицах. Один вызов BatchWriteItem может передавать до 16 МБ данных по сети, состоящих из до 25 операций добавления или удаления элементов. Хотя отдельные элементы могут быть до 400 КБ после хранения, важно отметить, что представление элемента может быть больше 400 КБ при отправке в формате JSON DynamoDB для вызова API. Более подробную информацию об этом различии см. в разделе Правила именования и типы данных .

Отдельные операции PutItem и DeleteItem, указанные в BatchWriteItem, являются атомарными; однако операция BatchWriteItem в целом не является атомарной. Если какие-либо запрошенные операции завершатся неудачно из-за превышения выделенного пропускной способности таблицы или внутренней ошибки обработки, неудачные операции возвращаются в параметре ответа UnprocessedItems. Вы можете исследовать их и, при необходимости, повторить запросы. Обычно вы вызываете BatchWriteItem в цикле. Каждый итерация проверяет наличие необработанных элементов и отправляет новый запрос BatchWriteItem с этими необработанными элементами до тех пор, пока все элементы не будут обработаны.

Для таблиц и индексов с выделенной емкостью, если ни один из элементов не может быть обработан из-за недостаточной выделенной пропускной способности во всех таблицах в запросе, тогда BatchWriteItem возвращает ProvisionedThroughputExceededException . Для всех таблиц и индексов, если ни один из элементов не может быть обработан из-за других сценариев ограничения (таких как превышение ограничений уровня разбиения), то BatchWriteItem возвращает ThrottlingException .

С помощью BatchWriteItem вы можете эффективно записывать или удалять большие объемы данных, например, из Amazon EMR, или копировать данные из другой базы данных в DynamoDB. Для повышения производительности при этих масштабных операциях, BatchWriteItem не ведет себя так же, как отдельные вызовы PutItem и DeleteItem. Например, вы не можете указать условия для отдельных запросов добавления и удаления, и BatchWriteItem не возвращает удаленные элементы в ответе.

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

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

Если выполняется одно или несколько из следующих условий, DynamoDB отклонит всю операцию пакетной записи:

• Одна или несколько таблиц, указанные в запросе BatchWriteItem, не существуют.
• Атрибуты первичного ключа, указанные для элемента в запросе, не соответствуют схеме первичного ключа соответствующей таблицы.
• Вы пытаетесь выполнить несколько операций над одним элементом в одном запросе BatchWriteItem. Например, вы не можете добавить и удалить один и тот же элемент в одном запросе BatchWriteItem.
• Ваш запрос содержит по крайней мере два элемента с идентичными хэш- и диапазонными ключами (что по сути является двумя операциями добавления).
• В пакетной обработке более 25 запросов.
• Любой отдельный элемент в пакетной обработке превышает 400 КБ.
• Общий размер запроса превышает 16 МБ.
• Любые отдельные элементы с ключами, превышающими пределы длины ключей. Для ключа разбиения предел составляет 2048 байтов, а для ключа сортировки – 1024 байта.

См. также: Документация AWS API

Синтаксис

  batch-write-item
--request-items <value>
[--return-consumed-capacity <value>]
[--return-item-collection-metrics <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]
[--cli-binary-format <value>]
[--no-cli-pager]
[--cli-auto-prompt]
[--no-cli-auto-prompt]

Параметры

--request-items (отображение)

Синтаксис JSON:

{"string": [
      {
        "PutRequest": {
          "Item": {"string": {
                "S": "string",
                "N": "string",
                "B": blob,
                "SS": ["string", ...],
                "NS": ["string", ...],
                "BS": [blob, ...],
                "M": {"string": {
                      "S": "string",
                      "N": "string",
                      "B": blob,
                      "SS": ["string", ...],
                      "NS": ["string", ...],
                      "BS": [blob, ...],
                      "M": {"string": { ... recursive ... }
                        ...},
                      "L": [
                        { ... recursive ... }
                        ...
                      ],
                      "NULL": true|false,
                      "BOOL": true|false
                    }
                  ...},
                "L": [
                  {
                    "S": "string",
                    "N": "string",
                    "B": blob,
                    "SS": ["string", ...],
                    "NS": ["string", ...],
                    "BS": [blob, ...],
                    "M": {"string": { ... recursive ... }
                      ...},
                    "L": [
                      { ... recursive ... }
                      ...
                    ],
                    "NULL": true|false,
                    "BOOL": true|false
                  }
                  ...
                ],
                "NULL": true|false,
                "BOOL": true|false
              }
            ...}
        },
        "DeleteRequest": {
          "Key": {"string": {
                "S": "string",
                "N": "string",
                "B": blob,
                "SS": ["string", ...],
                "NS": ["string", ...],
                "BS": [blob, ...],
                "M": {"string": {
                      "S": "string",
                      "N": "string",
                      "B": blob,
                      "SS": ["string", ...],
                      "NS": ["string", ...],
                      "BS": [blob, ...],
                      "M": {"string": { ... recursive ... }
                        ...},
                      "L": [
                        { ... recursive ... }
                        ...
                      ],
                      "NULL": true|false,
                      "BOOL": true|false
                    }
                  ...},
                "L": [
                  {
                    "S": "string",
                    "N": "string",
                    "B": blob,
                    "SS": ["string", ...],
                    "NS": ["string", ...],
                    "BS": [blob, ...],
                    "M": {"string": { ... recursive ... }
                      ...},
                    "L": [
                      { ... recursive ... }
                      ...
                    ],
                    "NULL": true|false,
                    "BOOL": true|false
                  }
                  ...
                ],
                "NULL": true|false,
                "BOOL": true|false
              }
            ...}
        }
      }
      ...
    ]
  ...}

--return-consumed-capacity (строка)

--return-item-collection-metrics (строка)

--cli-input-json | --cli-input-yaml (строка) Читает аргументы из предоставленной строки JSON. Строка JSON следует формату, предоставленному --generate-cli-skeleton. Если другие аргументы указаны в командной строке, эти значения переопределят значения, указанные в JSON. Невозможно передавать произвольные двоичные значения с помощью значения, предоставленного в JSON, так как строка будет принята буквально. Это не может быть указано вместе с --cli-input-yaml.

--generate-cli-skeleton (строка) Выводит JSON-скелет в стандартный вывод без отправки запроса API. Если предоставлено значение без значения или значение input, выводится пример JSON входных данных, который может быть использован как аргумент для --cli-input-json. Аналогично, если предоставлено значение yaml-input, будет выведен пример входных данных YAML, который можно использовать с --cli-input-yaml. Если предоставлено значение output, он валидирует входные данные команд и возвращает пример выходных данных JSON для этой команды. Сгенерированный JSON-скелет не является стабильным между версиями AWS CLI, и нет гарантий обратной совместимости в сгенерированном JSON-скелете.

Общие параметры

--debug (boolean)

Включить отладовую запись журнала.

--endpoint-url (string)

Переопределить значение по умолчанию URL команды заданным URL.

--no-verify-ssl (boolean)

По умолчанию AWS CLI использует SSL при общении с AWS-сервисами. Для каждого SSL-соединения AWS CLI проверяет SSL-сертификаты. Этот параметр переопределяет поведение проверки SSL-сертификатов по умолчанию.

--no-paginate (boolean)

Отключить автоматическую постраничную навигацию. Если автоматическая постраничная навигация отключена, AWS CLI выполнит только один вызов для первой страницы результатов.

--output (string)

Стиль форматирования вывода команд.

• json
• text
• table
• yaml
• yaml-stream

--query (string)

Запрос JMESPath для фильтрации данных ответа.

--profile (string)

Использование определенного профиля из файла аутентификации.

--region (string)

Регион для использования. Переопределяет параметры конфигурации/среды.

--version (string)

Отобразить версию этого инструмента.

--color (string)

Включить/отключить цветной вывод.

• on
• off
• auto

--no-sign-request (boolean)

Не подписывать запросы. Кредиты не будут загружены, если этот аргумент указан.

--ca-bundle (string)

Файл сертификатов CA для проверки SSL-сертификатов. Переопределяет параметры конфигурации/среды.

--cli-read-timeout (int)

Максимальное время чтения сокета в секундах. Если значение установлено в 0, чтение сокета будет выполняться блокирующим образом без таймаута. Значение по умолчанию составляет 60 секунд.

--cli-connect-timeout (int)

Максимальное время подключения сокета в секундах. Если значение установлено в 0, подключение сокета будет выполняться блокирующим образом без таймаута. Значение по умолчанию составляет 60 секунд.

--cli-binary-format (string)

Стиль форматирования для двоичных блоков. Формат по умолчанию — base64. Формат base64 ожидает, что двоичные блоки будут представлены как закодированная строка base64. Формат raw-in-base64-out сохраняет совместимость с поведением AWS CLI V1, а двоичные значения должны быть переданы буквально. При предоставлении содержимого из файла, которое соответствует двоичному блоку, fileb:// всегда будет обрабатываться как двоичное и использовать содержимое файла напрямую независимо от параметра cli-binary-format. При использовании file:// содержимое файла должно быть должным образом отформатировано для настроенного параметра cli-binary-format.

• base64
• raw-in-base64-out

--no-cli-pager (boolean)

Отключить вывод кли-пайпера.

--cli-auto-prompt (boolean)

Автоматически запрашивать параметры ввода CLI.

--no-cli-auto-prompt (boolean)

Отключить автоматическое запросы параметров ввода CLI.

Примеры

Для добавления нескольких элементов в таблицу

Следующий batch-write-item пример добавляет три новых элемента в таблицу MusicCollection, используя пакет из трех PutItem запросов. Также запрашивается информация о количестве потребленных единиц пропускной способности записи операцией и о любых измененных коллекциях элементов операцией.

aws dynamodb batch-write-item \
    --request-items file://request-items.json \
    --return-consumed-capacity INDEXES \
    --return-item-collection-metrics SIZE

Содержание request-items.json:

{
    "MusicCollection": [
        {
            "PutRequest": {
                "Item": {
                    "Artist": {"S": "No One You Know"},
                    "SongTitle": {"S": "Call Me Today"},
                    "AlbumTitle": {"S": "Somewhat Famous"}
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "Artist": {"S": "Acme Band"},
                    "SongTitle": {"S": "Happy Day"},
                    "AlbumTitle": {"S": "Songs About Life"}
                }
            }
        },
        {
            "PutRequest": {
                "Item": {
                    "Artist": {"S": "No One You Know"},
                    "SongTitle": {"S": "Scared of My Shadow"},
                    "AlbumTitle": {"S": "Blue Sky Blues"}
                }
            }
        }
    ]
}

Вывод:

{
    "UnprocessedItems": {},
    "ItemCollectionMetrics": {
        "MusicCollection": [
            {
                "ItemCollectionKey": {
                    "Artist": {
                        "S": "No One You Know"
                    }
                },
                "SizeEstimateRangeGB": [
                    0.0,
                    1.0
                ]
            },
            {
                "ItemCollectionKey": {
                    "Artist": {
                        "S": "Acme Band"
                    }
                },
                "SizeEstimateRangeGB": [
                    0.0,
                    1.0
                ]
            }
        ]
    },
    "ConsumedCapacity": [
        {
            "TableName": "MusicCollection",
            "CapacityUnits": 6.0,
            "Table": {
                "CapacityUnits": 3.0
            },
            "LocalSecondaryIndexes": {
                "AlbumTitleIndex": {
                    "CapacityUnits": 3.0
                }
            }
        }
    ]
}

Для получения дополнительной информации см. раздел «Операции пакетной записи» в Руководстве разработчика Amazon DynamoDB.

Вывод

UnprocessedItems -> (отображение)

ItemCollectionMetrics -> (карта)

ConsumedCapacity -> (список)