Importante
Esta seção refere-se à versão de API 2011-12-05, que está obsoleta e não deve ser usada para novos aplicativos.
Para obter a documentação da API de baixo nível atual, consulte a Referência da API do Amazon DynamoDB.
Descrição
Uma operação Query
obtém os valores de um ou mais itens e seus atributos por chave primária (Query
só está disponível para tabelas de chave primária de hash e intervalo). Você deve fornecer um HashKeyValue
específico e pode restringir o escopo da consulta usando operadores de comparação no RangeKeyValue
da chave primária. Use o parâmetro ScanIndexForward
para obter resultados em ordem progressiva ou inversa, por chave de intervalo.
Consultas que não retornam resultados consomem as unidades de capacidade de leitura mínimas de acordo com o tipo de leitura.
nota
Se o número total de itens que atendem aos parâmetros de consulta exceder o limite de 1 MB, a consulta será interrompida e os resultados serão retornados ao usuário com uma LastEvaluatedKey
para continuar a consulta em uma operação subsequente. Ao contrário de uma operação de Verificação, uma operação de Consulta nunca retorna um conjunto de resultados vazio e uma LastEvaluatedKey
. A LastEvaluatedKey
apenas será fornecida se o resultado exceder 1 MB, ou se você tiver usado o parâmetro Limit
.
O resultado pode ser definido para uma leitura consistente usando o parâmetro ConsistentRead
.
Solicitações
Sintaxe
// This header is abbreviated. // For a sample of a complete header, see API de baixo nível do DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Limit":2, "ConsistentRead":true, "HashKeyValue":{"S":"AttributeValue1":}, "RangeKeyCondition": {"AttributeValueList":[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"} "ScanIndexForward":true, "ExclusiveStartKey":{ "HashKeyElement":{"S":"AttributeName1"}, "RangeKeyElement":{"N":"AttributeName2"} }, "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, }
Nome | Descrição | Obrigatório |
---|---|---|
TableName
|
O nome da tabela que contém os itens solicitados. Tipo: string |
Sim |
AttributesToGet
|
Matriz de nomes de atributos. Se os nomes de atributos não forem especificados, todos os atributos serão retornados. Se alguns atributos não forem encontrados, eles não serão exibidos no resultado. Tipo: matriz |
Não |
Limit
|
O número máximo de itens a serem retornados (não necessariamente o número de itens correspondentes). Se o DynamoDB processar o número de itens até o limite enquanto consulta a tabela, ele interromperá essa consulta e retornará os valores correspondentes até esse ponto, bem como uma Tipo: número |
Não |
ConsistentRead
|
Se definido como Tipo: booliano |
Não |
Count
|
Se definido como Não defina Tipo: booliano |
Não |
HashKeyValue
|
O valor do atributo do componente de hash da chave primária composta. Tipo: String, número ou binário |
Sim |
RangeKeyCondition
|
Um contêiner dos valores de atributos e operadores de comparação a serem usados para a consulta. Uma solicitação de consulta não requer uma Tipo: mapa |
Não |
RangeKeyCondition :
AttributeValueList |
Os valores de atributos a serem avaliados para os parâmetros de consulta. O Tipo: Um mapa de |
Não |
RangeKeyCondition :
ComparisonOperator |
Os critérios para avaliar os atributos fornecidos, como igual a, maior que etc. Veja a seguir os operadores de comparação válidos para uma operação de Consulta. notaAs comparações de valor de string para maior que, igual a ou menor que são baseadas em valores de código de caracteres ASCII. Por exemplo, Para Binary, o DynamoDB trata cada byte dos dados binários como não atribuído ao comparar valores binários, por exemplo, ao avaliar as expressões de consulta. Tipo: string ou binário |
Não |
Para |
||
Para |
||
Para |
||
Para |
||
Para |
||
Para |
||
Para |
||
ScanIndexForward |
Especifica o percurso crescente ou decrescente do índice. O DynamoDB retornará resultados que refletem a ordem solicitada determinada pela chave de intervalo: se o tipo de dados for Number, os resultados serão retornados em ordem numérica. Caso contrário, o percurso se baseará em valores do código de caracteres ASCII. Tipo: booliano O padrão é |
Não |
ExclusiveStartKey |
A chave primária do item a partir do qual a consulta anterior deve continuar. Uma consulta anterior poderá fornecer esse valor como a Tipo: |
Não |
Respostas
Sintaxe
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 308
{"Count":2,"Items":[{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"N":"AttributeValue2"},
"AttributeName3":{"S":"AttributeValue3"}
},{
"AttributeName1":{"S":"AttributeValue3"},
"AttributeName2":{"N":"AttributeValue4"},
"AttributeName3":{"S":"AttributeValue3"},
"AttributeName5":{"B":"dmFsdWU="}
}],
"LastEvaluatedKey":{"HashKeyElement":{"AttributeValue3":"S"},
"RangeKeyElement":{"AttributeValue4":"N"}
},
"ConsumedCapacityUnits":1
}
Nome | Descrição |
---|---|
Items
|
Atributos do item que atendem aos parâmetros de consulta. Tipo: mapa de nomes de atributo e seus tipos de dados e valores. |
Count
|
Número de itens na resposta. Para ter mais informações, consulte Contar os itens nos resultados. Tipo: número |
LastEvaluatedKey |
Chave primária do item no qual a operação de consulta foi interrompida, incluindo o conjunto de resultados anterior. Use esse valor para iniciar uma nova operação, excluindo o valor na nova solicitação. A Tipo: |
ConsumedCapacityUnits |
O número de unidades de capacidade de leitura consumidas pela operação. Esse valor mostra o número utilizado no throughput provisionado. Para ter mais informações, consulte Modo de capacidade provisionada do DynamoDB. Tipo: número |
Erros especiais
Erro | Descrição |
---|---|
ResourceNotFoundException
|
A tabela especificada não foi encontrada. |
Exemplos
Para obter exemplos sobre o uso do AWS SDK, consulte Consultar tabelas no DynamoDB.
Exemplo de solicitação
// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"John"}, "ScanIndexForward":false, "ExclusiveStartKey":{ "HashKeyElement":{"S":"John"}, "RangeKeyElement":{"S":"The Matrix"} } }
Exemplo de resposta
HTTP/1.1 200
x-amzn-RequestId: 3647e778-71eb-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 308
{"Count":2,"Items":[{
"fans":{"SS":["Jody","Jake"]},
"name":{"S":"John"},
"rating":{"S":"***"},
"title":{"S":"The End"}
},{
"fans":{"SS":["Jody","Jake"]},
"name":{"S":"John"},
"rating":{"S":"***"},
"title":{"S":"The Beatles"}
}],
"LastEvaluatedKey":{"HashKeyElement":{"S":"John"},"RangeKeyElement":{"S":"The Beatles"}},
"ConsumedCapacityUnits":1
}
Exemplo de solicitação
// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.Query content-type: application/x-amz-json-1.0 {"TableName":"1-hash-rangetable", "Limit":2, "HashKeyValue":{"S":"Airplane"}, "RangeKeyCondition":{"AttributeValueList":[{"N":"1980"}],"ComparisonOperator":"EQ"}, "ScanIndexForward":false}
Exemplo de resposta
HTTP/1.1 200
x-amzn-RequestId: 8b9ee1ad-774c-11e0-9172-d954e38f553a
content-type: application/x-amz-json-1.0
content-length: 119
{"Count":1,"Items":[{
"fans":{"SS":["Dave","Aaron"]},
"name":{"S":"Airplane"},
"rating":{"S":"***"},
"year":{"N":"1980"}
}],
"ConsumedCapacityUnits":1
}