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

Метод BatchGetItem

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

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

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

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

Запрос

Запрос содержит данные в формате 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 Ассоциативный массив с названиями таблиц, где для каждой таблицы также указан ассоциативный массив с извлекаемыми элементами.
Каждый элемент состоит из:
  • ConsistentRead — если true, то используется строго согласованное чтение; если false (по умолчанию), то используется последовательное чтение.
  • ExpressionAttributeNames — заполнитель(placeholder), который можно использовать в выражении вместо имени атрибута. Заполнитель должен начинаться с символа решетки #.
    Это может пригодиться в нескольких случаях:
    • Нужно указать атрибут, имя которого конфликтует с зарезервированным словом.
    • В качестве переменной, если имя атрибута используется в выражении несколько раз.
    • Для предотвращения неправильной интерпретации специальных символов в имени атрибута.
    Например, имя атрибута Percentile конфликтует с зарезервированным словом, и его нельзя в явном виде использовать в выражении. Чтобы обойти эту проблему, нужно в параметре ExpressionAttributeNames указать заполнитель: {"#P":"Percentile"}. И затем вместо настоящего имени атрибута использовать #P.
  • Keys — массив значений атрибутов первичного ключа, которые необходимо извлечь. Для каждого первичного ключа необходимо указать все ключевые атрибуты. Для простого первичного ключа нужно указать только его значение. Для составного первичного ключа нужно указать значение ключа раздела и ключа сортировки.
  • ProjectionExpression — атрибуты, которые нужно извлечь. Атрибуты должны быть разделены запятыми.
    Если имена атрибутов не указаны явно, то возвращаются все атрибуты.

Тип: Строка типа KeysAndAttributes
Кол-во записей: максимум 100 элементов.
Длина ключа: 3 - 255 символов.
Шаблон: [a-zA-Z0-9_.-]+
Обязательно: Да
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
      }
   ],
   "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 Потребленные единицы мощности.
Возвращается только в том случае, если в запросе был указан параметр ReturnConsumedCapacity со значением TOTAL.
Состоит из:
  • TableName — таблица, потребляющая выделенную пропускную способность.
  • CapacityUnits — общее количество потребленных единиц мощности.

Тип: Массив объектов типа ConsumedCapacity
Responses Ассоциативный массив таблиц, в котором находятся извлеченные записи.

Тип: Ассоциативный массив типа AttributeValue.
Длина ключа: 3 - 255 символов.
Шаблон: [a-zA-Z0-9_.-]+
UnprocessedKeys Ассоциативный массив таблиц, в котором находятся необработанные записи. Записи приходят в том же виде, как были заданы в запросе в параметре RequestItems. Следовательно, эти значения можно повторно использовать в следующем запросе.
Каждый элемент состоит из:
  • Keys — массив значений атрибутов первичного ключа.
  • ProjectionExpression — извлеченные атрибуты.
  • ConsistentRead — если true, то используется строго согласованное чтение; если false (по умолчанию), то используется последовательное чтение.
Если необработанных элементов не осталось, то UnprocessedKeys будет пустой.

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

Ошибки

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

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

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

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

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

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

Предыдущая
Все методы
Следующая
BatchWriteItem