# Consultar tabelas no DynamoDB Você pode usar a operação de API `Query` no Amazon DynamoDB para encontrar itens com base nos valores de chave primária. Você deve fornecer o nome do atributo de chave de partição e um único valor para esse atributo. A operação `Query` retorna todos os itens com esse valor de chave de partição. Opcionalmente, você pode fornecer um atributo de chave de classificação e usar um operador de comparação para refinar os resultados da pesquisa. Para obter mais informações sobre como usar `Query`, como a sintaxe de solicitação, parâmetros de resposta e exemplos adicionais, acesse [Consulta](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) na *Referência da API do Amazon DynamoDB*. **Topics** + [Principais expressões de condição para a operação de consulta no DynamoDB](Query.KeyConditionExpressions.md) + [Filtrar expressões para a operação de consulta no DynamoDB](Query.FilterExpression.md) + [Paginar os resultados de consultas à tabela no DynamoDB](Query.Pagination.md) + [Outros aspectos do trabalho com a operação de consulta no DynamoDB](Query.Other.md) # Principais expressões de condição para a operação de consulta no DynamoDB Você pode usar qualquer nome de atributo em uma expressão de condição principal, desde que o primeiro caractere seja `a-z` ou `A-Z` e o restante dos caracteres (a partir do segundo caractere, se houver) seja `a-z`, `A-Z` ou `0-9`. Além disso, o nome do atributo não deve ser uma palavra reservada do DynamoDB. (Para obter uma lista completa dessas palavras reservadas, consulte [Palavras reservadas no DynamoDB](ReservedWords.md).) Se um nome de atributo não atender a esses requisitos, defina um nome de atributo de expressão como um espaço reservado. Para obter mais informações, consulte [Nomes (aliases) de atributo de expressão no DynamoDB](Expressions.ExpressionAttributeNames.md). Para itens com um determinado valor de chave de partição, o DynamoDB armazena esses itens juntos em ordem classificada por valor de chave de classificação. Em uma operação `Query`, o DynamoDB recupera os itens na ordem classificada e, em seguida, processa os itens usando `KeyConditionExpression` e qualquer `FilterExpression` que estiver presente. Somente então os resultados de `Query` são enviados de volta para o cliente. Uma operação `Query` sempre retorna um conjunto de resultados. Se não forem encontrados itens correspondentes, o conjunto de resultados estará vazio. `Query`Os resultados de são sempre classificados pelo valor de chave de classificação. Se o tipo de dados da chave de classificação for `Number`, os resultados serão retornados em ordem numérica. Caso contrário, os resultados serão retornados na ordem de bytes UTF-8. Por padrão, a ordem de classificação é crescente. Para reverter a ordem, defina o parâmetro `ScanIndexForward` como `false`. Uma única operação `Query` pode recuperar um máximo de 1 MB de dados. Esse limite se aplica antes de qualquer expressão `FilterExpression` ou `ProjectionExpression` ser aplicada aos resultados. Se `LastEvaluatedKey` estiver presente na resposta e não for nula, você deverá paginar o conjunto de resultados (consulte [Paginar os resultados de consultas à tabela no DynamoDB](Query.Pagination.md)). ## Exemplos das principais expressões de condição Para especificar os critérios de pesquisa, você deve usar uma *expressão de condição principal* – uma string que determina os itens a serem lidos da tabela ou índice. Você deve especificar o nome e o valor da chave de partição como uma condição de igualdade. Não é possível usar um atributo que não seja de chave em uma expressão de condição de chave. Opcionalmente, você pode fornecer uma segunda condição para a chave de classificação (se houver). A condição de chave de classificação deve usar um dos seguintes operadores de comparação: + `a = b` - verdadeiro se o atributo *a* for igual ao valor *b* + `a < b`: verdadeiro se *a* for menor que *b* + `a <= b`: verdadeiro se *a* for menor que ou igual a *b* + `a > b`: verdadeiro se *a* for maior que *b* + `a >= b`: verdadeiro se *a* for maior ou igual a *b* + `a BETWEEN b AND c` - verdadeiro se *a* for maior ou igual a *b*e menor ou igual a *c*. A função a seguir também tem suporte: + `begins_with (a, substr)`- verdadeiro se o valor do atributo `a` começa com uma determinada substring. Os seguintes exemplos da AWS Command Line Interface (AWS CLI) demonstram o uso das expressões de condição de chave. Essas expressões usam espaços reservados (como `:name` e `:sub`), em vez de valores reais. Para obter mais informações, consulte [Nomes (aliases) de atributo de expressão no DynamoDB](Expressions.ExpressionAttributeNames.md) e [Usar valores de atributos de expressão no DynamoDB](Expressions.ExpressionAttributeValues.md). **Example** Consulte a tabela `Thread` para encontrar um `ForumName` específico (chave de partição). Todos os itens com esse valor de `ForumName` são lidos pela consulta, porque a chave de classificação (`Subject`) não está incluída na `KeyConditionExpression`. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name" \ --expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}' ``` **Example** Consulte a tabela `Thread` para encontrar um `ForumName` específico (chave de partição), mas, desta vez, retornar apenas os itens com um determinado `Subject` (chave de classificação). ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :name and Subject = :sub" \ --expression-attribute-values file://values.json ``` Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`. ``` { ":name":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"} } ``` **Example** Consulte a tabela `Reply` para encontrar um `Id` específico (chave de partição), mas retornar apenas os itens cuja `ReplyDateTime` (chave de classificação) começa com determinados caracteres. ``` aws dynamodb query \ --table-name Reply \ --key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \ --expression-attribute-values file://values.json ``` Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`. ``` { ":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"}, ":dt":{"S":"2015-09"} } ``` # Filtrar expressões para a operação de consulta no DynamoDB Se você precisar refinar ainda mais os resultados de `Query`, existe a opção de utilizar uma expressão de filtro. Uma *expressão de filtro* determina quais itens dos resultados de `Query` devem ser retornados para você. Todos os outros resultados serão descartados. Uma expressão de filtro é aplicada depois que uma operação `Query` é concluída, mas antes que os resultados sejam retornados. Portanto, uma operação `Query` consome a mesma quantidade de capacidade de leitura, independentemente de uma expressão de filtro estar presente. Uma operação `Query` pode recuperar um máximo de 1 MB de dados. Esse limite se aplica antes de a expressão de filtro ser avaliada. Uma expressão de filtro não pode conter atributos de chave de partição ou de chave de classificação. É necessário especificar esses atributos na expressão de condição principal, não na de filtro. A sintaxe de uma expressão de filtro é semelhante à de uma expressão de condição de chave. As expressões de filtro podem usar os mesmos comparadores, funções e operadores lógicos que uma expressão de condição principal. Além disso, as expressões de filtro podem usar o operador diferente de (`<>`), bem como os operadores `OR`, `CONTAINS`, `IN`, `BEGINS_WITH`, `BETWEEN`, `EXISTS` e `SIZE`. Para obter mais informações, consulte [Principais expressões de condição para a operação de consulta no DynamoDB](Query.KeyConditionExpressions.md) e [Sintaxe para expressões de filtro e de condição](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax). **Example** O exemplo da AWS CLI a seguir consulta a tabela `Thread` para encontrar um `ForumName` (chave de partição) e um `Subject` (chave de classificação) específicos. Dos itens que são encontrados, somente os threads de discussão mais populares são retornados – em outras palavras, apenas os threads com mais de um determinado número de `Views`. ``` aws dynamodb query \ --table-name Thread \ --key-condition-expression "ForumName = :fn and Subject begins_with :sub" \ --filter-expression "#v >= :num" \ --expression-attribute-names '{"#v": "Views"}' \ --expression-attribute-values file://values.json ``` Os argumentos de `--expression-attribute-values` são armazenados no arquivo `values.json`. ``` { ":fn":{"S":"Amazon DynamoDB"}, ":sub":{"S":"DynamoDB Thread 1"}, ":num":{"N":"3"} } ``` Observe que `Views` é uma palavra reservada no DynamoDB (consulte [Palavras reservadas no DynamoDB](ReservedWords.md)), portanto, este exemplo usa `#v` como um espaço reservado. Para obter mais informações, consulte [Nomes (aliases) de atributo de expressão no DynamoDB](Expressions.ExpressionAttributeNames.md). **nota** Uma expressão de filtro remove itens do conjunto de resultados de `Query`. Se possível, evite usar `Query` onde você espera recuperar um grande número de itens, mas também precisa descartar a maioria desses itens. # Paginar os resultados de consultas à tabela no DynamoDB O DynamoDB *pagina* os resultados das operações `Query`. Com a paginação, os resultados de `Query` são divididos em "páginas" de dados com 1 MB de tamanho (ou menos). Uma aplicação pode processar a primeira página de resultados e, em seguida, a segunda página, e assim por diante. Uma única operação `Query` retorna apenas um conjunto de resultados que estão dentro do limite de tamanho de 1 MB. Para determinar se há mais resultados e para recuperá-los em uma página por vez, os aplicativos devem fazer o seguinte: 1. Examine o resultado de `Query` de baixo nível: + Se o resultado contiver um elemento `LastEvaluatedKey` e ele não for nulo, prossiga para a etapa 2. + Se *não* houver um `LastEvaluatedKey` no resultado, não haverá mais itens a serem recuperados. 1. Crie uma `Query` com a mesma `KeyConditionExpression`. No entanto, desta vez, use o valor de `LastEvaluatedKey` da etapa 1 como o parâmetro `ExclusiveStartKey` na nova solicitação de `Query`. 1. Execute a nova solicitação de `Query`. 1. Vá para a etapa 1. Em outras palavras, o valor `LastEvaluatedKey` de uma resposta de `Query` deve ser usado como `ExclusiveStartKey` da próxima solicitação de `Query`. Se não houver um elemento `LastEvaluatedKey` em uma resposta de `Query`, então, você recuperou a página de resultados final. Se `LastEvaluatedKey` não está vazio, isso não necessariamente significa que há mais dados no conjunto de resultados. A única maneira de saber quando você atingiu o final do conjunto de resultados é quando `LastEvaluatedKey` estiver vazio. Você pode usar a AWS CLI para visualizar esse comportamento. A AWS CLI envia repetidamente solicitações `Query` de baixo nível ao DynamoDB até que `LastEvaluatedKey` não esteja mais presente nos resultados. Considere o seguinte exemplo da AWS CLI que recupera títulos de filmes de um determinado ano. ``` aws dynamodb query --table-name Movies \ --projection-expression "title" \ --key-condition-expression "#y = :yyyy" \ --expression-attribute-names '{"#y":"year"}' \ --expression-attribute-values '{":yyyy":{"N":"1993"}}' \ --page-size 5 \ --debug ``` Normalmente, a AWS CLI lida com a paginação automaticamente. No entanto, neste exemplo, o parâmetro AWS CLI da `--page-size` limita o número de itens por página. O parâmetro de `--debug` imprime as informações de baixo nível sobre solicitações e respostas. Se você executar o exemplo, a primeira resposta do DynamoDB será semelhante a esta. ``` 2017-07-07 11:13:15,603 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":5,"Items":[{"title":{"S":"A Bronx Tale"}}, {"title":{"S":"A Perfect World"}},{"title":{"S":"Addams Family Values"}}, {"title":{"S":"Alive"}},{"title":{"S":"Benny & Joon"}}], "LastEvaluatedKey":{"year":{"N":"1993"},"title":{"S":"Benny & Joon"}}, "ScannedCount":5}' ``` O `LastEvaluatedKey` na resposta indica que nem todos os itens foram recuperados. A AWS CLI emite outra solicitação de `Query` para o DynamoDB. Essa solicitação e o padrão de resposta continuam, até a resposta final. ``` 2017-07-07 11:13:16,291 - MainThread - botocore.parsers - DEBUG - Response body: b'{"Count":1,"Items":[{"title":{"S":"What\'s Eating Gilbert Grape"}}],"ScannedCount":1}' ``` A ausência de `LastEvaluatedKey` indica que não há mais itens a serem recuperados. **nota** Os AWS SDKs lidam com as respostas de baixo nível do DynamoDB (incluindo a presença ou a ausência de `LastEvaluatedKey`) e fornecem várias abstrações para paginar os resultados de `Query` Por exemplo, a interface do documento SDK para Java fornece o suporte a `java.util.Iterator` para que você possa abordar um resultado de cada vez. Para obter exemplos de código em várias linguagens de programação, consulte o [Guia de conceitos básicos do Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) e a documentação do AWS SDK para sua linguagem. Você também pode reduzir o tamanho da página limitando o número de itens no conjunto de resultados, com o parâmetro `Limit` da operação `Query`. Para obter mais informações sobre como realizar consultas com o DynamoDB, veja [Consultar tabelas no DynamoDB](Query.md). # Outros aspectos do trabalho com a operação de consulta no DynamoDB Esta seção aborda aspectos adicionais da operação de consulta do DynamoDB, incluindo a limitação do tamanho dos resultados, a contagem de itens varridos versus retornados, o monitoramento do consumo da capacidade de leitura e o controle da consistência de leitura. ## Limitar o número de itens no conjunto de resultados Com a operação `Query`, você pode limitar o número de itens lidos. Para fazer isso, defina o parâmetro `Limit` com o número máximo de itens que você deseja. Por exemplo, suponha que você execute a operação `Query` em uma tabela, com um valor de `Limit` igual a `6` e sem uma expressão de filtro. O resultado de `Query` contém os primeiros seis itens da tabela que correspondem à expressão de condição da chave da solicitação. Agora suponha que você adicione uma expressão de filtro à operação `Query`. Nesse caso, o DynamoDB lê até seis itens e retorna somente aqueles que correspondem à expressão do filtro. O resultado final de `Query` contém seis itens ou menos, mesmo que mais itens tivessem correspondido à expressão do filtro se o DynamoDB continuasse lendo mais itens. ## Contar os itens nos resultados Além dos itens que correspondem aos seus critérios, a resposta de `Query` contém os elementos a seguir: + `ScannedCount`: o número de itens que corresponderam à expressão de condição principal, *antes* que uma expressão de filtro (se alguma) fosse aplicada. + `Count`: o número de itens que permaneceram *depois* que uma expressão de filtro (se alguma) foi aplicada. **nota** Se você não usar uma expressão de filtro, `ScannedCount` e `Count` terão o mesmo valor. Se o tamanho do conjunto de resultados de `Query` for maior que 1 MB, `ScannedCount` e `Count` representarão apenas uma contagem parcial do total de itens. Você precisa executar várias operações `Query` para recuperar todos os resultados (consulte [Paginar os resultados de consultas à tabela no DynamoDB](Query.Pagination.md)). Cada resposta de `Query` contém os valores de `ScannedCount` e de `Count` dos itens que foram processados pela solicitação de `Query` específica. Para obter os totais gerais de todas as solicitações de `Query`, você pode manter um total em execução de `ScannedCount` e `Count`. ## Unidades de capacidade consumidas por consulta Você pode usar `Query` em qualquer tabela ou índice secundário, desde que forneça o nome do atributo da chave de partição e um valor único para esse atributo. `Query` retorna todos os itens com esse valor de chave de partição. Opcionalmente, você pode fornecer um atributo de chave de classificação e usar um operador de comparação para refinar os resultados da pesquisa. `Query` As operações de API consomem unidades de capacidade de leitura da seguinte forma: **** | Se você executar uma operação `Query`... | O DynamoDB consumirá unidades de capacidade de leitura de... | | --- | --- | | Tabela | A capacidade de leitura provisionada da tabela. | | Índice secundário global | A capacidade de leitura provisionada do índice. | | Índice secundário local | A capacidade de leitura provisionada da tabela-base. | Por padrão, uma operação `Query` não retorna quaisquer dados sobre quanta capacidade de leitura ela consome. Entretanto, você pode especificar o parâmetro `ReturnConsumedCapacity` em uma solicitação de `Query` para obter essas informações. A seguir estão as configurações válidas de `ReturnConsumedCapacity`: + `NONE`: nenhum dado de capacidade consumida é retornado. (Esse é o padrão.) + `TOTAL`: a resposta inclui o número agregado de unidades de capacidade de leitura consumidas. + `INDEXES`: a resposta mostra o número agregado de unidades de capacidade de leitura consumidas, junto com a capacidade consumida para cada tabela e índice acessados. O DynamoDB calcula o número de unidades de capacidade de leitura consumidas com base na quantidade e no tamanho desses itens, não na quantidade de dados exibidos para uma aplicação. Por esse motivo, o número de unidades de capacidade consumidas será o mesmo, independentemente de você solicitar todos os atributos (o comportamento padrão) ou apenas alguns deles (usando uma expressão de projeção). O número também é o mesmo, independentemente de você usar ou não uma expressão de filtro. `Query` consome uma unidade de capacidade mínima de leitura para realizar uma leitura altamente consistente por segundo ou duas leituras finais consistentes por segundo para um item de até 4 KB. Se você precisar ler um item com mais de 4 KB, o DynamoDB precisará de unidades de solicitação de leitura adicionais. Tabelas vazias e tabelas muito grandes que têm uma quantidade esparsa de chaves de partição podem ter algumas RCUs adicionais cobradas além da quantidade de dados consultados. Isso cobre o custo de atender à solicitação `Query`, mesmo que não existam dados. ## Consistência de leitura para consulta Uma operação `Query` executa leituras finais consistentes, por padrão. Isso significa que os resultados de `Query` talvez não reflitam as alterações causadas pelas operações `PutItem` ou `UpdateItem` concluídas recentemente. Para obter mais informações, consulte [Consistência de leitura do DynamoDB](HowItWorks.ReadConsistency.md). Se você precisar de leituras fortemente consistentes, defina o parâmetro `ConsistentRead` como `true` na solicitação de `Query`.