Подключиться
Language / Region
© 2021 ООО «Яндекс.Облако»
Yandex Database

Метод Query

Статья создана

Находит элементы на основе заданных значений первичного ключа.

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

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

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

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

Результаты всегда сортируются по значению ключа сортировки. Если у ключа сортировки числовой тип данных, то результаты возвращаются в числовом порядке; в остальных случаях результаты сортируются в порядке байтов UTF-8.
Порядок сортировки задается параметром ScanIndexForward.

За один раз метод считывает максимум 1 Мб данных или то количество элементов, которое указано в параметре Limit. И только затем применяются фильтры, указанные в параметре FilterExpression.

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

Запрос

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

{
   "AttributesToGet": [ "string" ],
   "ConditionalOperator": "string",
   "ConsistentRead": boolean,
   "ExclusiveStartKey": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ExpressionAttributeNames": { 
      "string" : "string" 
   },
   "ExpressionAttributeValues": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "FilterExpression": "string",
   "IndexName": "string",
   "KeyConditionExpression": "string",
   "KeyConditions": { 
      "string" : { 
         "AttributeValueList": [ 
            { 
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [ 
                  "AttributeValue"
               ],
               "M": { 
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string"
      }
   },
   "Limit": number,
   "ProjectionExpression": "string",
   "QueryFilter": { 
      "string" : { 
         "AttributeValueList": [ 
            { 
               "B": blob,
               "BOOL": boolean,
               "BS": [ blob ],
               "L": [ 
                  "AttributeValue"
               ],
               "M": { 
                  "string" : "AttributeValue"
               },
               "N": "string",
               "NS": [ "string" ],
               "NULL": boolean,
               "S": "string",
               "SS": [ "string" ]
            }
         ],
         "ComparisonOperator": "string"
      }
   },
   "ReturnConsumedCapacity": "string",
   "ScanIndexForward": boolean,
   "Select": "string",
   "TableName": "string"
}

Параметры

Параметр Описание
TableName Имя таблицы, содержащей запрашиваемые элементы.
Может содержать путь в иерархии каталогов вида path/to/table.

Тип: Строка
Длина: 3 - 255 символов
Шаблон: [a-zA-Z0-9_.-]+
Обязательно: Да
ConsistentRead Определение модели согласованности чтения.
Если true, то используется строго согласованное чтение; если false (по умолчанию), то используется последовательное чтение.
Параметр не поддерживается для глобальных вторичных индексов. Если попытаться просканировать вторичный индекс со значением true, то метод вернет исключение ValidationException.

Тип: Boolean
Обязательно: Нет
ExclusiveStartKey Первичный ключ элемента, с которого метод начнет поиск.
Если в предыдущем запросе метод вернул LastEvaluatedKey, то используйте это значение чтобы продолжить поиск с того места, на котором метод остановился в прошлый раз.

Тип: Объект типа AttributeValue
Длина ключа: максимальная длина 65535.
Обязательно: Нет
ExpressionAttributeNames Заполнитель (placeholder), который можно использовать в выражении вместо имени атрибута. Заполнитель должен начинаться с символа решетки #.
В каких случаях это может пригодиться:
  • Если нужно указать атрибут, имя которого конфликтует с зарезервированным словом.
  • В качестве переменной, если имя атрибута используется в выражении несколько раз.
  • Для предотвращения неправильной интерпретации специальных символов в имени атрибута.
Например, имя атрибута Percentile конфликтует с зарезервированным словом, и его нельзя в явном виде использовать в выражении. Чтобы обойти эту проблему, нужно в параметре ExpressionAttributeNames указать заполнитель: {"#P":"Percentile"}. И затем вместо настоящего имени атрибута использовать #P.

Тип: Строка
Длина: 1 - 65535 символов.
Обязательно: Нет
ExpressionAttributeValues Заполнитель (placeholder), который можно использовать в выражении вместо значения атрибута, аналогично ExpressionAttributeNames. Заполнитель должен начинаться с символа двоеточия :.
Например, нужно проверить, было ли значение атрибута ProductStatus одним из следующих: Available | Backordered | Discontinued. Для этого сначала объявить заполнители : { ":avail":{"S":"Available"}, ":back":{"S":"Backordered"}, ":disc":{"S":"Discontinued"} }. А потом их можно использовать в выражении: ProductStatus IN (:avail, :back, :disc)

Тип: Строка типа AttributeValue
Обязательно: Нет
FilterExpression Условия, которые применятся после первоначальной выборки данных.
Элементы, не соответствующие этому условию, не вернутся в итоговом ответе.
Тип: Строка
Обязательно: Нет
IndexName Имя глобального вторичного индекса для сканирования. Обратите внимание, что если вы используете этот параметр, вы также должны указать TableName.
Тип: Строка
Длина: 3 - 255 символов
Шаблон: [a-zA-Z0-9_.-]+
Обязательно: Нет
KeyConditionExpression Условие, определяющее значения ключей выбираемых элементов.
Условие должно выполнять проверку на равенство для одного значения ключа раздела.
Дополнительно можно выполнить сравнение для одного значения ключа сортировки. Это позволяет получить элемент с заданным значением ключа раздела и значением ключа сортировки или несколько элементов, которые имеют одинаковое значение ключа раздела, но разные значения ключа сортировки.
Проверку на равенство необходимо указывать в формате: partitionKeyName = :partitionkeyval.
Если нужно указать условие для ключа сортировки, его необходимо объединить с условием для ключа сортировки, например: partitionKeyName = :partitionkeyval AND sortKeyName = :sortkeyval.
Возможные сравнения для условия ключа сортировки:
  • sortKeyName = :sortkeyval — истина, если значение ключа сортировки равно :sortkeyval.
  • sortKeyName < :sortkeyval — истина, если значение ключа сортировки меньше :sortkeyval.
  • sortKeyName <= :sortkeyval — истина, если значение ключа сортировки меньше или равно :sortkeyval.
  • sortKeyName > :sortkeyval — истина, если значение ключа сортировки больше :sortkeyval.
  • sortKeyName >= :sortkeyval — истина, если значение ключа сортировки больше или равно :sortkeyval.
  • sortKeyName BETWEEN :sortkeyval1 AND :sortkeyval2 — истина, если значение ключа сортировки больше или равно :sortkeyval1 и меньше или равно :sortkeyval2.
  • begins_with ( sortKeyName, :sortkeyval ) — истина, если значение ключа сортировки начинается с определенного операнда. Функцию нельзя использовать с ключом сортировки числового типа. Имя функции чувствительно к регистру.

Тип: Строка
Обязательно: Нет
Limit Максимальное количество элементов, которые будут оценены для выборки.
Когда метод обработает указанное количество элементов, он останавливается и возвращает результат до того места, на котором остановился. При этом в параметре LastEvaluatedKey вернется последний ключ, на котором он остановился. Его можно использовать чтобы продолжить сканирование с того места, на котором остановился метод.

Тип: Целое число
Диапазон: минимальное значение 1.
Обязательно: Нет
ProjectionExpression Выражение, определяющие атрибуты для извлечения. Атрибуты в выражении должны быть разделены запятыми.
Если имена атрибутов не указаны явно, то возвращаются все атрибуты элемента.

Тип: Строка
Обязательно: Нет
ReturnConsumedCapacity Нужно ли возвращать информацию о потребляемой мощности.
  • TOTAL - Вернуть информацию.
  • NONE - Не возвращать информацию.

Тип: Строка
Возможные значения: TOTAL | NONE
Обязательно: Нет
ScanIndexForward Задает порядок обхода индекса.
  • true — обход выполняется в возрастающем порядке (по умолчанию)
  • false — обход выполняется в порядке убывания.

Тип: логический
Обязательно: Нет
Select Атрибуты, которые нужно вернуть.
Может принимать значения:
  • ALL_ATTRIBUTES — возвращает все атрибуты элемента из таблицы или индекса (по умолчанию).
  • COUNT — возвращает только количество совпадающих атрибутов.

Тип: Строка
Допустимые значения: ALL_ATTRIBUTES | COUNT
Обязательно: Нет

Ответ

В случае успеха вернется 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
   },
   "Count": number,
   "Items": [ 
      { 
         "string" : { 
            "B": blob,
            "BOOL": boolean,
            "BS": [ blob ],
            "L": [ 
               "AttributeValue"
            ],
            "M": { 
               "string" : "AttributeValue"
            },
            "N": "string",
            "NS": [ "string" ],
            "NULL": boolean,
            "S": "string",
            "SS": [ "string" ]
         }
      }
   ],
   "LastEvaluatedKey": { 
      "string" : { 
         "B": blob,
         "BOOL": boolean,
         "BS": [ blob ],
         "L": [ 
            "AttributeValue"
         ],
         "M": { 
            "string" : "AttributeValue"
         },
         "N": "string",
         "NS": [ "string" ],
         "NULL": boolean,
         "S": "string",
         "SS": [ "string" ]
      }
   },
   "ScannedCount": number
}

Параметры

Параметр Описание
ConsumedCapacity Единицы мощности, потребленные операцией удаления.
Возвращается только в том случае, если в запросе был указан параметр ReturnConsumedCapacity со значением TOTAL.

Тип: объект типа ConsumedCapacity
Count Количество элементов в ответе.
Если в запросе вы использовали FilterExpression, тогда это количество элементов, возвращенных после применения фильтра.

Тип: целое число
Items Массив атрибутов, подходящих под критерии сканирования.
Каждый элемент в массиве состоит из имени и значения этого атрибута.

Тип: массив объектов типа AttributeValue
Длина ключа: 1 - 65535 символов.
LastEvaluatedKey Первичный ключ элемента, на котором остановилось сканирование. Используйте это значение, чтобы продолжить с того места, на котором остановились. Если в LastEvaluatedKey пусто, значит метод обработал все элементы и больше нечего возвращать.

Тип: ассоциативный массив типа AttributeValue
Длина ключа: 1 - 65535 символов.
ScannedCount Количество элементов, найденных до применения фильтров FilterExpression.

Тип: целое число

Ошибки

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

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

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

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

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

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

Language / Region
© 2021 ООО «Яндекс.Облако»
В этой статье: