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.

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"]},
}

Name (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. Type: 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 mais informações, consulte Contar os itens nos resultados. Type: 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. nota 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#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. Type: booliano O 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
}

Name (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 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 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 obter mais informações, consulte Gerenciar configurações em tabelas com 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 Operações de consulta 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
}

Ações relacionadas

• Scan