Метод 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 .Возможные сравнения для условия ключа сортировки:
Тип: Строка Обязательно: Нет |
Limit |
Максимальное количество элементов, которые будут оценены для выборки. Когда метод обработает указанное количество элементов, он останавливается и возвращает результат до того места, на котором остановился. При этом в параметре LastEvaluatedKey вернется последний ключ, на котором он остановился. Его можно использовать чтобы продолжить сканирование с того места, на котором остановился метод.Тип: Целое число Диапазон: минимальное значение 1. Обязательно: Нет |
ProjectionExpression |
Выражение, определяющие атрибуты для извлечения. Атрибуты в выражении должны быть разделены запятыми. Если имена атрибутов не указаны явно, то возвращаются все атрибуты элемента. Тип: Строка Обязательно: Нет |
ReturnConsumedCapacity |
Нужно ли возвращать информацию о потребляемой мощности.
Тип: Строка Возможные значения: TOTAL | NONE Обязательно: Нет |
ScanIndexForward |
Задает порядок обхода индекса.
Тип: логический Обязательно: Нет |
Select |
Атрибуты, которые нужно вернуть. Может принимать значения:
Тип: Строка Допустимые значения: 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 |
Также могут возникать Общие ошибки, одинаковые для всех методов.