Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Menanyakan tabel di DynamoDB
Anda dapat menggunakan operasi API `Query` di Amazon DynamoDB untuk menemukan item berdasarkan nilai kunci primer.
Anda harus memberikan nama atribut kunci partisi dan satu nilai untuk atribut tersebut. `Query` mengembalikan semua item dengan nilai kunci partisi tersebut. Secara opsional, Anda dapat memberikan atribut kunci urutan dan menggunakan operator perbandingan untuk menyaring hasil pencarian.
Untuk informasi selengkapnya tentang cara menggunakan `Query`, seperti sintaks permintaan, parameter respons, dan contoh tambahan, lihat [Kueri](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) di *Referensi API Amazon DynamoDB*.
**Topics**
+ [Ekspresi kondisi kunci untuk operasi Query di DynamoDB](Query.KeyConditionExpressions.md)
+ [Ekspresi filter untuk operasi Query di DynamoDB](Query.FilterExpression.md)
+ [Hasil query tabel paginasi di DynamoDB](Query.Pagination.md)
+ [Aspek lain dari bekerja dengan operasi Query di DynamoDB](Query.Other.md)
# Ekspresi kondisi kunci untuk operasi Query di DynamoDB
Anda dapat menggunakan nama atribut apa pun dalam ekspresi kondisi kunci, asalkan karakter pertama adalah `a-z` atau `A-Z` dan karakter lainnya (mulai dari karakter kedua, jika ada) adalah `a-z`, `A-Z`, or `0-9`. Selain itu, nama atribut tidak boleh berupa kata khusus DynamoDB. (Untuk daftar lengkapnya, lihat [Kata-kata penggunaan khusus di DynamoDB](ReservedWords.md).) Jika nama atribut tidak memenuhi persyaratan ini, Anda harus menentukan nama atribut ekspresi sebagai placeholder. Untuk informasi selengkapnya, lihat [Nama atribut ekspresi (alias) di DynamoDB](Expressions.ExpressionAttributeNames.md).
Untuk item dengan nilai kunci partisi tertentu, DynamoDB menyimpan item ini berdekatan, dalam urutan berdasarkan nilai kunci urutan. Dalam operasi `Query`, DynamoDB mengambil item dalam urutan yang diurutkan, lalu memproses item menggunakan `KeyConditionExpression` dan `FilterExpression` apa pun yang mungkin ada. Baru setelah itu hasil `Query` dikirim kembali ke klien.
Operasi `Query` selalu mengembalikan kumpulan hasil. Jika tidak ditemukan item yang cocok, set hasil kosong.
Hasil `Query` selalu diurutkan berdasarkan nilai kunci urutan. Jika jenis daya kunci urutan adalah `Number`, hasilnya dikembalikan dalam urutan numerik. Jika tidak, hasilnya akan dikembalikan dalam urutan UTF-8 byte. Secara default, urutannya menaik. Untuk membalikkan urutan, atur parameter `ScanIndexForward` ke `false`.
Operasi `Query` tunggal dapat mengambil data maksimum 1 MB. Batas ini berlaku sebelum `FilterExpression` atau `ProjectionExpression` diterapkan pada hasil. Jika `LastEvaluatedKey` ada dalam respons dan bukan null, Anda harus memberi nomor halaman pada kumpulan hasil (lihat [Hasil query tabel paginasi di DynamoDB](Query.Pagination.md)).
## Contoh ekspresi kondisi kunci
Untuk menentukan kriteria pencarian, Anda menggunakan *ekspresi kondisi kunci*—string yang menentukan item yang akan dibaca dari tabel atau indeks.
Anda harus menentukan nama dan nilai kunci partisi sebagai syarat kesetaraan. Anda tidak dapat menggunakan atribut bukan kunci dalam ekspresi kondisi kunci.
Anda juga dapat memberikan kondisi kedua untuk kunci urutan (jika ada). Kondisi kunci urutan harus menggunakan salah satu operator perbandingan berikut:
+ `a = b`— true jika atribut *a* sama dengan nilai *b*
+ `a < b`— benar *a* jika kurang dari *b*
+ `a <= b`— benar jika *a* kurang dari atau sama dengan *b*
+ `a > b`Benar jika *a* lebih besar dari *b*
+ `a >= b`— benar jika *a* lebih besar dari atau sama dengan *b*
+ `a BETWEEN b AND c`— benar jika *a* lebih besar dari atau sama dengan*b*, dan kurang dari atau sama dengan*c*.
Fungsi berikut ini juga didukung:
+ `begins_with (a, substr)`— true jika nilai atribut `a` dimulai dengan substring tertentu.
Contoh berikut AWS Command Line Interface (AWS CLI) menunjukkan penggunaan ekspresi kondisi kunci. Ekspresi ini menggunakan placeholder (seperti `:name` dan `:sub`) dan bukan nilai aktual. Untuk informasi selengkapnya, lihat [Nama atribut ekspresi (alias) di DynamoDB](Expressions.ExpressionAttributeNames.md) dan [Menggunakan nilai atribut ekspresi di DynamoDB](Expressions.ExpressionAttributeValues.md).
**Example**
Ajukan kueri tabel `Thread` untuk `ForumName` (kunci partisi) tertentu. Semua item dengan nilai `ForumName` tersebut dibaca oleh kueri karena kunci urutan (`Subject`) tidak termasuk dalam`KeyConditionExpression`.
```
aws dynamodb query \
--table-name Thread \
--key-condition-expression "ForumName = :name" \
--expression-attribute-values '{":name":{"S":"Amazon DynamoDB"}}'
```
**Example**
Ajukan kueri tabel `Thread` untuk `ForumName` kunci partisi), tetapi kali ini hanya mengembalikan item dengan `Subject`(kunci urutan) tertentu.
```
aws dynamodb query \
--table-name Thread \
--key-condition-expression "ForumName = :name and Subject = :sub" \
--expression-attribute-values file://values.json
```
Argumen untuk `--expression-attribute-values` disimpan dalam file `values.json`.
```
{
":name":{"S":"Amazon DynamoDB"},
":sub":{"S":"DynamoDB Thread 1"}
}
```
**Example**
Kueri tabel `Reply` untuk `Id` tertentu (kunci partisi), tetapi hanya kembalikan item yang `ReplyDateTime` (kunci urutan) dimulai dengan karakter tertentu.
```
aws dynamodb query \
--table-name Reply \
--key-condition-expression "Id = :id and begins_with(ReplyDateTime, :dt)" \
--expression-attribute-values file://values.json
```
Argumen untuk `--expression-attribute-values` disimpan dalam file `values.json`.
```
{
":id":{"S":"Amazon DynamoDB#DynamoDB Thread 1"},
":dt":{"S":"2015-09"}
}
```
# Ekspresi filter untuk operasi Query di DynamoDB
Jika Anda perlu menyempurnakan hasil `Query` lebih lanjut, Anda dapat memberikan ekspresi filter secara opsional. *Ekspresi filter* menentukan item mana dalam hasil `Query` yang harus dikembalikan kepada Anda. Semua hasil lainnya dibuang.
Filter ekspresi diterapkan setelah `Query` selesai, namun sebelum hasilnya dikembalikan. Oleh karena itu, `Query` menggunakan jumlah kapasitas baca yang sama, terlepas dari apakah ada ekspresi filter.
Operasi `Query` dapat mengambil data maksimal 1 MB. Batasan ini berlaku sebelum ekspresi filter dievaluasi.
Filter ekspresi tidak boleh berisi atribut kunci partisi atau kunci urutan. Anda perlu menentukan atribut tersebut dalam ekspresi kondisi kunci, bukan ekspresi filter.
Sintaks untuk ekspresi filter mirip dengan ekspresi kondisi kunci. Ekspresi filter dapat menggunakan pembanding, fungsi, dan operator logika yang sama sebagai ekspresi kondisi utama. Selain itu, ekspresi filter dapat menggunakan operator tak sama dengan `<>`(), operator `OR`, operator `CONTAINS`, operator `IN`, operator `BEGINS_WITH`, operator `BETWEEN`, operator `EXISTS`, dan operator `SIZE`. Untuk informasi selengkapnya, lihat [Ekspresi kondisi kunci untuk operasi Query di DynamoDB](Query.KeyConditionExpressions.md) dan [Sintaks untuk ekspresi filter dan kondisi](Expressions.OperatorsAndFunctions.md#Expressions.OperatorsAndFunctions.Syntax).
**Example**
AWS CLI Contoh berikut query `Thread` tabel untuk tertentu `ForumName` (kunci partisi) dan `Subject` (sort key). Dari item yang ditemukan, hanya rangkaian diskusi terpopuler yang dikembalikan—dengan kata lain, hanya rangkaian diskusi yang memiliki jumlah `Views` lebih dari tertentu.
```
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
```
Argumen untuk `--expression-attribute-values` disimpan dalam file `values.json`.
```
{
":fn":{"S":"Amazon DynamoDB"},
":sub":{"S":"DynamoDB Thread 1"},
":num":{"N":"3"}
}
```
Perhatikan bahwa `Views` adalah kata yang dicadangkan di DynamoDB (lihat [Kata-kata penggunaan khusus di DynamoDB](ReservedWords.md)), sehingga contoh ini menggunakan `#v` sebagai placeholder. Untuk informasi selengkapnya, lihat [Nama atribut ekspresi (alias) di DynamoDB](Expressions.ExpressionAttributeNames.md).
**catatan**
Ekspresi filter menghapus item dari set hasil `Query`. Jika memungkinkan, hindari penggunaan `Query` saat Anda ingin mengambil item dalam jumlah besar namun juga harus membuang sebagian besar item tersebut.
# Hasil query tabel paginasi di DynamoDB
DynamoDB *memberi nomor halaman* hasil dari operasi `Query`. Dengan pemberian nomor halaman, hasil `Query` dibagi menjadi "halaman" data berukuran 1 MB (atau kurang). Aplikasi bisa memproses halaman pertama hasil, lalu halaman kedua, dan seterusnya.
`Query` tunggal hanya mengembalikan set hasil yang sesuai dalam batas ukuran 1 MB. Untuk menentukan apakah terdapat lebih banyak hasil, dan untuk mengambilkan satu halaman sekaligus, aplikasi harus melakukan hal berikut:
1. Periksa hasil `Query` tingkat rendah:
+ Jika hasilnya berisi elemen `LastEvaluatedKey` dan elemen tersebut non-null, lanjutkan ke langkah 2.
+ Jika *tidak ada* `LastEvaluatedKey` pada hasilnya, tidak ada lagi item yang dapat diambil.
1. Membangun `Query` dengan yang sama`KeyConditionExpression`. Namun, kali ini, ambil nilai `LastEvaluatedKey` dari langkah 1 dan gunakan sebagai parameter `ExclusiveStartKey` dalam permintaan `Query` baru.
1. Jalankan permintaan `Query` baru.
1. Lanjutkan ke langkah 1.
Dengan kata lain, `LastEvaluatedKey` dari respons `Query` harus digunakan sebagai `ExclusiveStartKey` untuk permintaan `Query` berikutnya. Jika tidak ada elemen `LastEvaluatedKey` dalam respons `Query`, maka Anda telah mengambil halaman hasil akhir. Jika `LastEvaluatedKey` tidak kosong, bukan berarti ada lebih banyak data di set hasil. Satu-satunya cara untuk mengetahui kapan Anda telah mencapai akhir kumpulan hasil adalah ketika `LastEvaluatedKey` kosong.
Anda dapat menggunakan AWS CLI untuk melihat perilaku ini. AWS CLI Mengirimkan `Query` permintaan tingkat rendah ke DynamoDB berulang kali, `LastEvaluatedKey` hingga tidak ada lagi dalam hasil. Perhatikan AWS CLI contoh berikut yang mengambil judul film dari tahun tertentu.
```
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
```
Biasanya, AWS CLI menangani pagination secara otomatis. Namun, dalam contoh ini, AWS CLI `--page-size` parameter membatasi jumlah item per halaman. Parameter `--debug` mencetak informasi tingkat rendah tentang permintaan dan respons.
Jika Anda menjalankan contoh ini, respons pertama dari DynamoDB terlihat serupa dengan yang berikut ini.
```
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}'
```
`LastEvaluatedKey` dalam responsnya menunjukkan bahwa tidak semua item telah diambil. AWS CLI Kemudian mengeluarkan `Query` permintaan lain ke DynamoDB. Pola permintaan dan respons ini berlanjut hingga respons akhir.
```
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}'
```
Tidak adanya `LastEvaluatedKey` menunjukkan bahwa tidak ada lagi item yang dapat diambil.
**catatan**
AWS SDKs Menangani respons DynamoDB tingkat rendah (termasuk ada atau tidak adanya) dan memberikan berbagai `LastEvaluatedKey` abstraksi untuk hasil paginasi. `Query` Misalnya, antarmuka dokumen SDK untuk Java menyediakan dukungan `java.util.Iterator` sehingga Anda dapat mempelajari hasilnya satu per satu.
Untuk contoh kode dalam berbagai bahasa pemrograman, lihat [Panduan Memulai Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/gettingstartedguide/) dan dokumentasi AWS SDK untuk bahasa Anda.
Anda juga dapat mengurangi ukuran halaman dengan membatasi jumlah item dalam set hasil, dengan parameter `Limit` operasi `Query`.
Untuk informasi selengkapnya tentang pembuatan kueri dengan DynamoDB, lihat [Menanyakan tabel di DynamoDB](Query.md).
# Aspek lain dari bekerja dengan operasi Query di DynamoDB
Bagian ini mencakup aspek tambahan dari operasi Query DynamoDB, termasuk membatasi ukuran hasil, menghitung item yang dipindai vs. dikembalikan, memantau konsumsi kapasitas baca, dan mengontrol konsistensi baca.
## Membatasi jumlah item dalam set hasil
Dengan operasi `Query`, Anda dapat membatasi jumlah item yang dibaca. Untuk melakukannya, tetapkan parameter `Limit` ke jumlah maksimum item yang Anda inginkan.
Misalnya, anggaplah bahwa Anda `Query` tabel, dengan nilai `Limit` dari `6`, dan tanpa ekspresi filter. Hasil `Query` berisi enam item pertama dari tabel yang cocok dengan ekspresi kondisi kunci dari permintaan.
Sekarang anggap bahwa Anda menambahkan ekspresi filter ke `Query`. Dalam kasus ini, DynamoDB membaca hingga enam item, lalu hanya mengembalikan item yang cocok dengan ekspresi filter. Hasil `Query` akhir berisi enam item atau lebih sedikit, meskipun lebih banyak item akan cocok dengan ekspresi filter jika DynamoDB terus membaca lebih banyak item.
## Menghitung item dalam hasil
Selain item yang sesuai dengan kriteria Anda, respons `Query` berisi elemen berikut:
+ `ScannedCount` — Jumlah item yang cocok dengan ekspresi kondisi kunci *sebelum* ekspresi filter (jika ada) diterapkan.
+ `Count` — Jumlah item yang tersisa *setelah* ekspresi filter (jika ada) diterapkan.
**catatan**
Jika Anda tidak menggunakan ekspresi filter, `ScannedCount` dan `Count` memiliki nilai yang sama.
Jika ukuran set hasil `Query` lebih besar dari 1 MB, `ScannedCount` dan `Count` mewakili hanya jumlah parsial dari total item. Anda harus melakukan beberapa operasi `Query` untuk mengambil semua hasil (lihat [Hasil query tabel paginasi di DynamoDB](Query.Pagination.md)).
Setiap respons `Query` berisi `ScannedCount` dan `Count` untuk item yang diproses oleh permintaan `Query` khusus. Untuk mendapatkan total keseluruhan untuk semua permintaan `Query`, Anda dapat menyimpan penghitungan `ScannedCount` dan `Count`.
## Unit kapasitas yang digunakan oleh kueri
Anda dapat melakukan `Query` tabel atau indeks sekunder apa pun, selama Anda memberikan nama atribut kunci partisi dan satu nilai untuk atribut tersebut. `Query` mengembalikan semua item dengan nilai kunci partisi tersebut. Secara opsional, Anda dapat memberikan atribut kunci urutan dan menggunakan operator perbandingan untuk menyaring hasil pencarian. `Query` Operasi API menggunakan unit kapasitas baca, sebagai berikut.
****
| Jika Anda `Query`... | DynamoDB menggunakan unit kapasitas baca dari... |
| --- | --- |
| Tabel | Kapasitas baca yang ditetapkan tabel. |
| Indeks sekunder global | Kapasitas baca yang ditetapkan indeks. |
| Indeks sekunder lokal | Kapasitas baca yang ditetapkan tabel dasar. |
Secara default, operasi `Query` tidak menampilkan data tentang berapa banyak kapasitas baca yang digunakan. Namun, Anda dapat menentukan parameter `ReturnConsumedCapacity` dalam sebuah permintaan `Query` untuk mendapatkan informasi ini. Berikut ini adalah pengaturan yang valid untuk `ReturnConsumedCapacity`:
+ `NONE` — Tidak ada penggunaan data kapasitas yang ditampilkan. (Ini menjadi opsi default.)
+ `TOTAL` — Respons mencakup jumlah agregat unit kapasitas baca yang digunakan.
+ `INDEXES` — Respons menunjukkan jumlah agregat unit kapasitas baca yang digunakan, beserta dengan kapasitas yang digunakan untuk setiap tabel dan indeks yang diakses.
DynamoDB menghitung jumlah unit kapasitas baca yang dikonsumsi berdasarkan jumlah item dan ukuran item tersebut, bukan pada jumlah data yang dikembalikan ke aplikasi. Dengan alasan ini, jumlah unit kapasitas yang digunakan adalah sama, entah Anda meminta semua atribut (perilaku default) atau hanya beberapa dari atribut tersebut (menggunakan ekspresi proyeksi). Jumlahnya juga sama apakah Anda menggunakan ekspresi filter atau tidak. `Query`mengkonsumsi unit kapasitas baca minimum untuk melakukan satu pembacaan yang sangat konsisten per detik, atau dua pembacaan yang konsisten per detik untuk item hingga 4 KB. Jika Anda perlu membaca item yang lebih besar dari 4 KB, DynamoDB memerlukan unit permintaan baca tambahan. Tabel kosong dan tabel yang sangat besar yang memiliki jumlah kunci partisi yang jarang mungkin melihat beberapa tambahan RCUs dibebankan di luar jumlah data yang ditanyakan. Ini mencakup biaya melayani `Query` permintaan, bahkan jika tidak ada data.
## Konsistensi baca untuk kueri
Operasi `Query` melakukan bacaan akhir konsisten, secara default. Ini berarti bahwa hasil `Query` mungkin tidak mencerminkan perubahan karena operasi `PutItem` atau `UpdateItem` baru saja selesai. Untuk informasi selengkapnya, lihat [DynamoDB membaca konsistensi](HowItWorks.ReadConsistency.md).
Jika Anda memerlukan bacaan sangat konsisten, atur parameter `ConsistentRead` ke `true` dalam permintaan `Query`.