Kueri - Amazon DynamoDB
DeskripsiPermintaanResponsKesalahan khususContohTindakan terkait

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Kueri

penting

Bagian ini mengacu pada API versi 2011-12-05, yang sudah usang dan tidak boleh digunakan untuk aplikasi baru.

Untuk dokumentasi tentang API tingkat rendah saat ini, lihat Referensi API Amazon DynamoDB.

Deskripsi

Sebuah Query operasi mendapatkan nilai dari satu atau lebih item dan atributnya dengan kunci primer (hanya Query tersedia untuk tabel kunci hash-and-range primer). Anda harus memberikan HashKeyValue spesifik, dan dapat mempersempit ruang lingkup kueri menggunakan operator perbandingan pada RangeKeyValue kunci primer. Gunakan parameter ScanIndexForward untuk mendapatkan hasil dalam urutan maju atau mundur dengan kunci rentang.

Kueri yang tidak mengembalikan hasil menggunakan unit kapasitas baca minimum sesuai dengan jenis baca.

catatan

Jika jumlah total item yang memenuhi parameter kueri melampaui batas 1 MB, kueri berhenti dan hasilnya dikembalikan ke pengguna dengan LastEvaluatedKey untuk melanjutkan kueri dalam operasi berikutnya. Tidak seperti operasi Scan, operasi Kueri tidak pernah mengembalikan set hasil kosong dan sebuah LastEvaluatedKey. LastEvaluatedKey hanya diberikan jika hasil melampaui 1 MB, atau jika Anda telah menggunakan parameter Limit.

Hasilnya dapat diatur untuk bacaan yang konsisten menggunakan parameter ConsistentRead.

Permintaan

Sintaks

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB tingkat rendah 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"]},
}
Nama Deskripsi Wajib
TableName

Nama tabel yang berisi item yang diminta.

Jenis: String

 Ya
AttributesToGet

Array Nama atribut. Jika nama atribut tidak ditentukan, semua atribut akan dikembalikan. Jika beberapa atribut tidak ditemukan, atribut tersebut tidak akan muncul dalam hasil.

Jenis: Array

 Tidak
Limit

Jumlah maksimum item untuk dikembalikan (tidak selalu merupakan jumlah item yang cocok). Jika DynamoDB memproses jumlah item hingga batasnya sekaligus mengajukan kueri tabel, layanan ini menghentikan kueri dan mengembalikan nilai-nilai yang cocok hingga titik tersebut, dan LastEvaluatedKey untuk diterapkan dalam operasi berikutnya guna melanjutkan kueri. Selain itu, jika ukuran set hasil melampaui 1 MB sebelum DynamoDB mencapai batas ini, layanan ini akan menghentikan kueri dan mengembalikan nilai-nilai yang cocok, serta LastEvaluatedKey untuk diterapkan dalam operasi berikutnya guna melanjutkan kueri.

Jenis: Angka

 Tidak
ConsistentRead

Jika diatur ke true, bacaan yang konsisten akan diterbitkan. Jika tidak, bacaan akhir konsisten akan digunakan.

Jenis: Boolean

 Tidak
Count

Jika diatur ke true, DynamoDB mengembalikan jumlah total item yang cocok dengan parameter kueri, bukan daftar item yang cocok dan atributnya. Anda dapat menerapkan parameter Limit pada kueri hanya-hitung.

Jangan atur Count ke true saat menyediakan daftar AttributesToGet, karena ini membuat DynamoDB mengembalikan kesalahan validasi. Untuk informasi selengkapnya, lihat Menghitung item dalam hasil.

Jenis: Boolean

 Tidak
HashKeyValue

Nilai atribut komponen hash dari kunci primer komposit.

Jenis: String, Angka, atau Biner

 Ya
RangeKeyCondition

Sebuah kontainer untuk nilai atribut dan operator perbandingan untuk digunakan dalam kueri. Permintaan kueri tidak memerlukan RangeKeyCondition. Jika Anda hanya memberikan HashKeyValue, DynamoDB mengembalikan semua item dengan nilai elemen kunci hash yang ditentukan.

Jenis: Peta

 Tidak
RangeKeyCondition:​ AttributeValueList

Nilai atribut yang akan dievaluasi untuk parameter kueri. AttributeValueList berisi satu nilai atribut, kecuali jika perbandingan BETWEEN ditentukan. Untuk perbandingan BETWEEN, AttributeValueList berisi dua nilai atribut.

Jenis: Peta AttributeValue ke ComparisonOperator.

Tidak
RangeKeyCondition:​ ComparisonOperator

Kriteria untuk mengevaluasi atribut yang disediakan, seperti sama dengan, lebih besar dari, dll. Berikut ini adalah operator perbandingan yang valid untuk operasi Kueri.

catatan

Perbandingan nilai string untuk lebih besar dari, sama dengan, atau kurang dari didasarkan pada nilai-nilai kode karakter ASCII. Sebagai contoh, a lebih besar dari A, dan aa lebih besar dari B. Untuk daftar nilai kode, lihat http://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters.

Untuk Biner, DynamoDB memperlakukan setiap byte data biner sebagai tidak bertanda ketika membandingkan nilai-nilai biner, contohnya ketika mengevaluasi ekspresi kueri.

Jenis: String atau Biner

 Tidak
 

EQ: Sama dengan.

Untuk EQ, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String, Angka, atau Biner (bukan jenis set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Sebagai contoh, {"S":"6"} tidak sama dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sama dengan {"NS":["6", "2", "1"]}.

  
 

LE: Kurang dari atau sama dengan.

Untuk LE, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String, Angka, atau Biner (bukan jenis set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Sebagai contoh, {"S":"6"} tidak sama dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sebanding dengan {"NS":["6", "2", "1"]}.

  
 

LT: Kurang dari.

Untuk LT, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String, Angka, atau Biner (bukan jenis set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Sebagai contoh, {"S":"6"} tidak sama dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sebanding dengan {"NS":["6", "2", "1"]}.

  
 

GE: Lebih besar dari atau sama dengan.

Untuk GE, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String, Angka, atau Biner (bukan jenis set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Sebagai contoh, {"S":"6"} tidak sama dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sebanding dengan {"NS":["6", "2", "1"]}.

  
 

GT: Lebih besar dari.

Untuk GT, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String, Angka, atau Biner (bukan jenis set). Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Sebagai contoh, {"S":"6"} tidak sama dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sebanding dengan {"NS":["6", "2", "1"]}.

  
 

BEGINS_WITH: memeriksa prefiks.

Untuk BEGINS_WITH, AttributeValueList hanya dapat berisi satu AttributeValue berjenis String atau Biner (bukan jenis Angka atau set). Atribut target perbandingan harus berupa String atau Biner (bukan Angka atau set).

  
 

BETWEEN: Lebih besar dari, atau sama dengan, nilai pertama dan kurang dari, atau sama dengan, nilai kedua.

Untuk BETWEEN, AttributeValueList harus berisi dua elemen AttributeValue berjenis yang sama, baik String, Angka, atau Biner (bukan set). Suatu atribut target cocok jika nilai target lebih besar dari, atau sama dengan, elemen pertama dan kurang dari, atau sama dengan, elemen kedua. Jika item berisi AttributeValue dengan jenis berbeda dari yang ditentukan dalam permintaan, nilainya tidak cocok. Misalnya, {"S":"6"} tidak sebanding dengan {"N":"6"}. Selain itu, {"N":"6"} tidak sebanding dengan {"NS":["6", "2", "1"]}.

  
ScanIndexForward

Menentukan traversal naik atau turun indeks. DynamoDB mengembalikan hasil yang mencerminkan urutan yang diminta, yang ditentukan oleh kunci rentang: Jika jenis data adalah Angka, hasilnya dikembalikan dalam urutan numerik; jika tidak, traversal didasarkan pada nilai kode karakter ASCII.

Jenis: Boolean

Default-nya adalah true (naik).

 Tidak
ExclusiveStartKey

Kunci primer dari item untuk melanjutkan kueri sebelumnya. Kueri sebelumnya mungkin memberikan nilai ini sebagai LastEvaluatedKey jika operasi kueri terinterupsi sebelum menyelesaikan kueri; baik karena ukuran set hasil maupun parameter Limit. LastEvaluatedKey dapat diteruskan kembali dalam permintaan kueri baru untuk melanjutkan operasi dari titik tersebut.

Jenis: HashKeyElement, atau HashKeyElement dan RangeKeyElement untuk kunci primer komposit.

 Tidak

Respons

Sintaks

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
}
Nama Deskripsi
Items

Atribut item yang memenuhi parameter kueri.

Jenis: Peta nama atribut serta nilai dan jenis data.
Count

Jumlah item dalam respons. Untuk informasi selengkapnya, lihat Menghitung item dalam hasil.

Jenis: Angka
LastEvaluatedKey Kunci primer dari item di mana operasi kueri berhenti, termasuk set hasil sebelumnya. Gunakan nilai ini untuk memulai operasi baru dengan mengecualikan nilai ini dalam permintaan baru.

LastEvaluatedKey adalah null ketika seluruh set hasil kueri selesai (yaitu operasi memproses “halaman terakhir”).

Jenis: HashKeyElement, atau HashKeyElement dan RangeKeyElement untuk kunci primer komposit.
ConsumedCapacityUnits

Jumlah unit kapasitas baca yang digunakan dalam operasi. Nilai ini menunjukkan jumlah yang diterapkan pada throughput yang disediakan. Untuk informasi selengkapnya, lihat DynamoDB menyediakan mode kapasitas.

Jenis: Angka

Kesalahan khusus

Kesalahan Deskripsi
ResourceNotFoundException Tabel yang ditentukan tidak ditemukan.

Contoh

Untuk contoh menggunakan AWS SDK, lihatMenanyakan tabel di DynamoDB.

Permintaan sampel


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

Respons sampel


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
}

Permintaan sampel

// This header is abbreviated. For a sample of a complete header, see DynamoDB tingkat rendah 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}

Respons sampel

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
}