Query

Importante

In questa sezione si fa riferimento alla versione API 2011-12-05, che è obsoleta e non deve essere utilizzata per le nuove applicazioni.

Per informazioni sull'API di basso livello corrente, consulta la Amazon DynamoDB API Reference.

Descrizione

Un'Queryoperazione ottiene i valori di uno o più elementi e i relativi attributi per chiave primaria (Queryè disponibile solo per le tabelle delle chiavi hash-and-range primarie). È necessario fornire un HashKeyValue specifico ed è possibile restringere l'ambito della query utilizzando gli operatori di confronto sul RangeKeyValue della chiave primaria. Utilizza il parametro ScanIndexForward per ottenere risultati in ordine in avanti o all'indietro in base alla chiave di intervallo.

Le query che non restituiscono risultati consumano il numero minimo di unità di capacità di lettura in base al tipo di lettura.

Nota

Se il numero totale di elementi che soddisfano i parametri della query supera il limite di 1 MB, la query si interrompe e i risultati vengono restituiti all'utente con un LastEvaluatedKey per continuare la query in un'operazione successiva. A differenza di un'operazione Scan, un'operazione Query non restituisce mai un set di risultati vuoto e un LastEvaluatedKey. LastEvaluatedKey viene fornito solo se i risultati superano 1 MB o se è stato utilizzato il parametro Limit.

Il risultato può essere impostato per una lettura consistente utilizzando il parametro ConsistentRead.

Richieste

Sintassi

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB di basso livello API.
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	Descrizione	Richiesto
TableName	Il nome della tabella che contiene gli elementi richiesti. ▬Tipo: stringa	Sì
AttributesToGet	Matrice di nomi di attributi. Se i nomi degli attributi non sono specificati, verranno restituiti tutti gli attributi. Se alcuni attributi non vengono trovati, non verranno visualizzati nel risultato. Tipo: Array	No
Limit	Il numero massimo di elementi da restituire (non necessariamente il numero di elementi corrispondenti). Se DynamoDB elabora il numero di elementi fino al limite durante la query sulla tabella, interrompe la query e restituisce i valori corrispondenti fino a quel punto e un LastEvaluatedKey da applicare in un'operazione successiva per continuare la query. Inoltre, se la dimensione del set di risultati supera 1 MB prima che DynamoDB raggiunga questo limite, interrompe la query e restituisce i valori corrispondenti e un LastEvaluatedKey da applicare in un'operazione successiva per continuare la query. Tipo: numero	No
ConsistentRead	Se impostato su true, viene emessa una lettura consistente, altrimenti viene utilizzata la consistenza finale. Tipo: Booleano	No
Count	Se impostato su true, DynamoDB restituisce un numero totale di elementi che corrispondono ai parametri della query e non un elenco degli elementi corrispondenti e dei relativi attributi. È possibile applicare il parametro Limit alle query di solo conteggio. Non impostare Count su true mentre si fornisce un elenco di AttributesToGet; in caso contrario, DynamoDB restituirà un errore di convalida. Per ulteriori informazioni, consulta Conteggio degli elementi nei risultati. Tipo: Booleano	No
HashKeyValue	Valore attributo del componente hash della chiave primaria composita. Tipo: String, Number o Binary	Sì
RangeKeyCondition	Un container per i valori degli attributi e gli operatori di confronto da utilizzare per la query. Una richiesta di query non richiede un RangeKeyCondition. Se si fornisce solo HashKeyValue, DynamoDB restituisce tutti gli elementi con il valore dell'elemento della chiave hash specificato. Tipo: Map	No
RangeKeyCondition:​ AttributeValueList	I valori degli attributi da valutare per i parametri della query. AttributeValueList contiene un valore di attributo, a meno che non sia specificato un confronto BETWEEN. Per il confronto BETWEEN, AttributeValueListcontiene due valori di attributo. Tipo: una mappa di AttributeValue ad un ComparisonOperator.	No
RangeKeyCondition:​ ComparisonOperator	I criteri per valutare gli attributi forniti, come uguale, maggiore di, ecc. Di seguito sono riportati operatori di confronto validi per un'operazione Query. Nota I confronti di valori String per maggiore di, uguale o minore di si basano sui valori del codice di caratteri ASCII. Ad esempio, a è maggiore di A e aa è maggiore di B. Per l'elenco dei valori di codifica, vedi http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters. Per Binary, DynamoDB tratta ciascun byte dei dati binari come non firmato quando confronta i valori binari, ad esempio quando valuta le espressioni di query. Tipo: String o Binary	No
	EQ: uguale. Per EQ, AttributeValueList può contenere solo un AttributeValue di tipo String, Number o Binary (non un set). Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non è uguale a {"N":"6"}. Inoltre, {"N":"6"} non è uguale a {"NS":["6", "2", "1"]}.
	LE: minore o uguale a. Per LE, AttributeValueList può contenere solo un AttributeValue di tipo String, Number o Binary (non un set). Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non è uguale a {"N":"6"}. Inoltre, {"N":"6"} non si confronta con {"NS":["6", "2", "1"]}.
	LT: minore di. Per LT, AttributeValueList può contenere solo un AttributeValue di tipo String, Number o Binary (non un set). Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non è uguale a {"N":"6"}. Inoltre, {"N":"6"} non si confronta con {"NS":["6", "2", "1"]}.
	GE: maggiore o uguale a. Per GE, AttributeValueList può contenere solo un AttributeValue di tipo String, Number o Binary (non un set). Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non è uguale a {"N":"6"}. Inoltre, {"N":"6"} non si confronta con {"NS":["6", "2", "1"]}.
	GT: maggiore di. Per GT, AttributeValueList può contenere solo un AttributeValue di tipo String, Number o Binary (non un set). Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non è uguale a {"N":"6"}. Inoltre, {"N":"6"} non si confronta con {"NS":["6", "2", "1"]}.
	BEGINS_WITH: controlla la presenza di un prefisso. Per BEGINS_WITH, AttributeValueList può contenere solo un AttributeValue di tipo String o Binary (non Number o Set). L'attributo di destinazione del confronto deve essere String o Binary (non Number o un set).
	BETWEEN: maggiore di o uguale a primo valore e minore di o uguale a secondo valore. Per BETWEEN, AttributeValueList deve contenere due elementi AttributeValue dello stesso tipo, String, Number o Binary (non un set). Un attributo di destinazione corrisponde se il valore di destinazione è maggiore o uguale al primo elemento e minore o uguale al secondo elemento. Se un elemento contiene un AttributeValue di un tipo diverso da quello specificato nella richiesta, il valore non corrisponde. Ad esempio, {"S":"6"} non si confronta con {"N":"6"}. Inoltre, {"N":"6"} non si confronta con {"NS":["6", "2", "1"]}.
ScanIndexForward	Specifica l'attraversamento ascendente o discendente dell'indice. DynamoDB restituisce risultati che riflettono l'ordine richiesto determinato dalla chiave di intervallo: se il tipo di dati è Number, i risultati vengono restituiti in ordine numerico. In caso contrario, l'attraversamento si basa sui valori del codice di caratteri ASCII. Tipo: Booleano L'impostazione predefinita è true (ascendente).	No
ExclusiveStartKey	La chiave primaria dell'elemento da cui continuare una query precedente. Una query precedente potrebbe fornire questo valore come LastEvaluatedKey se l'operazione di query è stata interrotta prima di completare la query a causa della dimensione del set di risultati o del parametro Limit. LastEvaluatedKey può essere re-inviato in una nuova richiesta di query per continuare l'operazione da quel punto. Tipo: HashKeyElement, HashKeyElement e RangeKeyElement per una chiave primaria composita.	No

Risposte

Sintassi

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	Descrizione
Items	Attributi dell'elemento che soddisfano i parametri della query. Tipo: mappa di nomi degli attributi e dei relativi tipi di dati e valori.
Count	Il numero di elementi nella risposta. Per ulteriori informazioni, consulta Conteggio degli elementi nei risultati. Tipo: numero
LastEvaluatedKey	La chiave primaria dell'elemento per cui l'operazione di query è stata interrotta, incluso il set di risultati precedente. Utilizza questo valore per avviare una nuova operazione escludendo questo valore nella nuova richiesta. LastEvaluatedKey è null quando l'intero set di risultati della query è completo (cioè l'operazione ha elaborato l'ultima pagina). Tipo: HashKeyElement o HashKeyElement e RangeKeyElement per una chiave primaria composita.
ConsumedCapacityUnits	Il numero di unità di capacità di scrittura utilizzate dall'operazione. Questo valore mostra il numero applicato alla velocità effettiva assegnata. Per ulteriori informazioni, consulta Modalità di capacità fornita da DynamoDB. Tipo: numero

Errori speciali

Errore	Descrizione
ResourceNotFoundException	La tabella specificata non è stata trovata.

Esempi

Per esempi di utilizzo dell' AWS SDK, consultaInterrogazione di tabelle in DynamoDB.

Richiesta di esempio

// This header is abbreviated. For a sample of a complete header, see DynamoDB di basso livello API.
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"}
	}
}

Risposta di esempio

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
}

Richiesta di esempio

// This header is abbreviated. For a sample of a complete header, see DynamoDB di basso livello API.
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}

Risposta di esempio

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
}

Operazioni correlate

• Scan