# Consulta **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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).** ## 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 `LastEvaluatedKey` a ser aplicada em uma operação subsequente para continuar a consulta. Além disso, se o conjunto de resultados exceder 1 MB antes que o DynamoDB atinja esse limite, ele interromperá a consulta e retornará os valores correspondentes, bem como uma `LastEvaluatedKey` a ser aplicada a uma operação subsequente para continuar a consulta.Tipo: número | Não | | ConsistentRead | Se definido como `true`, uma leitura consistente será emitida; caso contrário, uma leitura eventualmente consistente será usada.Tipo: booliano | Não | | Count | Se definido como `true`, o DynamoDB retornará um número total de itens que correspondem aos parâmetros de consulta, em vez de uma lista dos itens correspondentes e seus atributos. É possível aplicar o parâmetro `Limit` a consultas somente de contagem. Não defina `Count` como `true` ao fornecer uma lista de `AttributesToGet`. Caso contrário, o DynamoDB retornará um erro de validação. Para ter mais informações, consulte [Contar os itens nos resultados](Query.Other.md#Query.Count).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 `RangeKeyCondition`. Se você fornecer apenas o `HashKeyValue`, o DynamoDB retornará todos os itens com o valor do elemento de chave de hash especificado.Tipo: mapa | Não | | RangeKeyCondition:​ AttributeValueList | Os valores de atributos a serem avaliados para os parâmetros de consulta. O `AttributeValueList` contém um valor de atributo, a menos que uma comparação `BETWEEN` seja especificada. Para a comparação `BETWEEN`, o `AttributeValueList` contém dois valores de atributo. Tipo: Um mapa de `AttributeValue` para uma `ComparisonOperator`. | 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. As 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, `a` é maior que `A`, e `aa` é maior que `B`. Para obter uma lista de valores de código, consulte [http://en.wikipedia.org/wiki/ASCII\$1ASCII\$1printable\$1characters](http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters). 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 | |   | `EQ` : Igual. Para `EQ`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (e não um conjunto). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não é igual a `{"NS":["6", "2", "1"]}`. |   | |   | `LE` : Menor ou igual a. Para `LE`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (e não um conjunto). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`. |   | |   | `LT` : Menor que. Para `LT`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (e não um conjunto). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`. |   | |   | `GE` : Maior ou igual a. Para `GE`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (e não um conjunto). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`. |   | |   | `GT` : Maior que. Para `GT`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String, Number ou Binary (e não um conjunto). Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não é igual a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`. |   | |   | `BEGINS_WITH` : procura um prefixo. Para `BEGINS_WITH`, `AttributeValueList` pode conter apenas um `AttributeValue` do tipo String ou Binary (e não um Number ou conjunto). O atributo de destino da comparação deve ser String ou Binary (não Number ou um conjunto). |   | |   | `BETWEEN` : Maior ou igual ao primeiro valor e menor que ou igual ao segundo valor. Para `BETWEEN`, `AttributeValueList` deve conter dois elementos `AttributeValue` do mesmo tipo, seja String, Number ou Binary (e não um conjunto). Um atributo de destino corresponderá se o valor de destino for maior que ou igual ao primeiro elemento e menor que ou igual ao segundo elemento. Se um item contém um `AttributeValue` de um valor diferente do especificado na solicitação, os valores não coincidem. Por exemplo, `{"S":"6"}` não se compara a `{"N":"6"}`. Além disso, `{"N":"6"}` não se compara a `{"NS":["6", "2", "1"]}`. |   | | 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: boolianoO padrão é `true` (crescente). | 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 `LastEvaluatedKey` se essa operação de consulta tiver sido interrompida antes da conclusão da consulta, seja devido ao tamanho do conjunto de resultados ou ao parâmetro `Limit`. A `LastEvaluatedKey` pode ser retornada em uma nova solicitação de consulta para continuar a operação a partir desse ponto.Tipo: `HashKeyElement` ou `HashKeyElement` e `RangeKeyElement` para uma chave primária composta. | 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](Query.Other.md#Query.Count). 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 `LastEvaluatedKey` é `null` quando o conjunto inteiro de resultados da consulta está completo (ou seja, a operação processou a "última página"). Tipo: `HashKeyElement` ou `HashKeyElement` e `RangeKeyElement` para uma chave primária composta. | | 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](provisioned-capacity-mode.md). 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](Query.md). ### 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 } ``` ## Ações relacionadas + [Verificar](API_Scan_v20111205.md)