Метод Query

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

Обновлена 12 июля 2022 г.

Запрос
- Параметры
Ответ
- Параметры
Ошибки

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

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

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

Метод Query

ЗапросЗапрос

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

ОтветОтвет

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

ОшибкиОшибки

Была ли статья полезна?

Запрос

Параметры

Ответ

Параметры

Ошибки