GetRange - Tablestore

Membaca data dengan nilai kunci primer dalam rentang tertentu.

Sintaksis permintaan

message GetRangeRequest {
    required string table_name = 1;
    required Direction direction = 2;
    repeated string columns_to_get = 3; // Jika Anda tidak menentukan parameter ini, semua kolom akan dibaca. 
    optional TimeRange time_range = 4;
    optional int32 max_versions = 5;
    optional int32 limit = 6;
    required bytes inclusive_start_primary_key = 7; // Informasi kunci primer awal dienkripsi sebagai data biner dalam format PlainBuffer. 
    required bytes exclusive_end_primary_key = 8; // Informasi kunci primer akhir dienkripsi sebagai data biner dalam format PlainBuffer. 
    optional bytes filter = 10;
    optional string start_column = 11;
    optional string end_column = 12;
}

Parameter	Tipe	Diperlukan	Deskripsi
table_name	string	Ya	Nama tabel.
direction	Direction	Ya	Urutan baris yang ingin Anda urutkan dalam respons. Jika Anda mengatur parameter ini ke FORWARD, nilai dari parameter inclusive_start_primary_key harus lebih kecil daripada nilai dari parameter exclusive_end_primary_key, dan baris dalam respons diurutkan secara menaik berdasarkan nilai kunci primer. Jika Anda mengatur parameter ini ke BACKWARD, nilai dari parameter inclusive_start_primary_key harus lebih besar daripada nilai dari parameter exclusive_end_primary_key, dan baris dalam respons diurutkan secara menurun berdasarkan nilai kunci primer.
columns_to_get	repeated string	Tidak	Nama kolom yang ingin Anda kembalikan. Nilai dari parameter ini dapat berisi hingga 128 string. Jika Anda tidak menentukan parameter ini, semua kolom dari baris yang memenuhi kondisi kueri dikembalikan. Jika semua kolom dari sebuah baris tidak memenuhi kondisi kueri, baris tersebut tidak dikembalikan dan nilai pengembaliannya adalah null. Jika sebuah baris berisi beberapa kolom yang memenuhi kondisi kueri, baris tersebut dikembalikan dan hanya kolom yang memenuhi kondisi kueri yang termasuk dalam respons. Jika ada nama kolom yang duplikat, respons mencakup kolom tersebut hanya sekali.
time_range	TimeRange	Tidak. Hanya salah satu dari max_versions dan time_range yang diperlukan.	Rentang waktu dari data yang ingin Anda baca. Nilai valid: 0 hingga `INT64.MAX`. Satuan: milidetik. Jika Anda ingin menanyakan data dalam rentang waktu, tentukan start_time dan end_time. Nilai time_range adalah interval tertutup-kiri, terbuka-kanan. Contoh: `[start_time, end_time)`. Jika Anda mengatur parameter ini ke `[100, 200)`, timestamp dari data dalam kolom yang dikembalikan harus berada dalam rentang `[100, 200)`. Jika Anda ingin menanyakan data pada timestamp tertentu, tentukan specific_time.
max_versions	int32	Tidak. Hanya salah satu dari max_versions dan time_range yang diperlukan.	Jumlah maksimum versi data yang ingin Anda kembalikan. Sebagai contoh, jika nilai max_versions adalah 2, maksimal dua versi data dikembalikan untuk setiap kolom.
limit	int32	Tidak	Jumlah maksimum baris yang ingin Anda kembalikan. Nilai dari parameter ini harus lebih besar dari 0. Jika jumlah baris yang memenuhi kondisi kueri melebihi nilai dari parameter ini, respons berisi titik pemberhentian yang mencatat posisi di mana operasi pembacaan berakhir. Operasi pembacaan berikutnya dimulai dari posisi ini. Tablestore mengembalikan hingga 5.000 baris data terlepas dari apakah Anda menentukan parameter ini. Ukuran total baris yang dikembalikan tidak boleh melebihi 4 MB.
inclusive_start_primary_key	bytes	Ya	Informasi kunci primer tempat operasi pembacaan dimulai. Informasi kunci primer awal dienkripsi dalam format PlainBuffer. Untuk informasi lebih lanjut, lihat PlainBuffer. Jika sebuah baris berisi kolom kunci primer awal, baris tersebut termasuk dalam respons.
exclusive_end_primary_key	bytes	Ya	Informasi kunci primer tempat operasi pembacaan berakhir. Informasi kunci primer akhir dienkripsi dalam format PlainBuffer. Untuk informasi lebih lanjut, lihat PlainBuffer. Jika sebuah baris berisi kolom kunci primer akhir, baris tersebut dikecualikan dari respons. Untuk operasi GetRange, kolom kunci primer dalam nilai inclusive_start_primary_key dan exclusive_end_primary_key dapat berupa salah satu dari jenis berikut yang didedikasikan untuk operasi ini: INF_MIN dan INF_MAX. INF_MIN menunjukkan nilai tak terhingga kecil. Jika tipe kolom kunci primer adalah INF_MIN, nilai kolom tersebut lebih kecil daripada nilai kolom lainnya. INF_MAX menunjukkan nilai tak terhingga besar. Jika tipe kolom kunci primer adalah INF_MAX, nilai kolom tersebut lebih besar daripada nilai kolom lainnya.
filter	bytes	Tidak	Ekspresi kondisi filter. Ekspresi kondisi filter diserialisasi sebagai data biner menggunakan Protobuf. Untuk informasi lebih lanjut, lihat Filter.
start_column	string	Tidak	Kolom tempat operasi pembacaan dimulai dalam sebuah baris. Parameter ini digunakan untuk pembacaan kolom lebar. Respons mencakup kolom awal yang ditentukan. Kolom diurutkan berdasarkan nama mereka dalam urutan abjad. Jika sebuah tabel berisi Kolom a, b, dan c, dan nilai start_column adalah b, operasi pembacaan dimulai dari Kolom b, dan Kolom b dan c dikembalikan.
end_column	string	Tidak	Kolom tempat operasi pembacaan berakhir dalam sebuah baris. Parameter ini digunakan untuk pembacaan kolom lebar. Respons mengecualikan kolom akhir yang ditentukan. Kolom diurutkan berdasarkan nama mereka dalam urutan abjad. Jika sebuah tabel berisi Kolom a, b, dan c, dan nilai end_column adalah b, operasi pembacaan berakhir pada Kolom b, dan hanya Kolom a yang dikembalikan.

Sintaksis respons

message GetRangeResponse {
    required ConsumedCapacity consumed = 1;
    required bytes rows = 2; 
    optional bytes next_start_primary_key = 3; 
}

Parameter	Tipe	Deskripsi
consumed	ConsumedCapacity	Jumlah unit kapasitas (CUs) yang dikonsumsi oleh operasi. Untuk informasi lebih lanjut, lihat Konsumsi CU.
rows	bytes	Baris yang dikembalikan oleh operasi. Baris dienkripsi dalam format PlainBuffer. Untuk informasi lebih lanjut, lihat PlainBuffer. Jika direction dalam permintaan diatur ke FORWARD, baris dalam respons diurutkan secara menaik berdasarkan nilai kunci primer. Jika direction dalam permintaan diatur ke BACKWARD, baris dalam respons diurutkan secara menurun berdasarkan nilai kunci primer. Kolom kunci primer dan kolom atribut untuk setiap baris dalam respons mencakup hanya kolom yang Anda tentukan untuk columns_to_get dalam permintaan. Urutan kolom dalam respons mungkin berbeda dari urutan kolom yang Anda tentukan untuk columns_to_get dalam permintaan. Urutan kolom kunci primer dalam respons mungkin berbeda dari urutan kolom kunci primer yang ditentukan saat tabel dibuat. Jika nilai columns_to_get dalam permintaan tidak berisi kolom kunci primer, baris yang tidak berisi kolom atribut yang ditentukan dalam columns_to_get dikecualikan dari respons meskipun nilai kunci primer dari baris tersebut berada dalam rentang kueri.
next_start_primary_key	bytes	Titik pemberhentian yang mencatat posisi di mana operasi pembacaan berakhir. Titik pemberhentian dienkripsi dalam format PlainBuffer. Untuk informasi lebih lanjut, lihat PlainBuffer. Jika nilai pengembalian kosong, operasi GetRange mengembalikan semua data yang memenuhi kondisi kueri. Jika nilai pengembalian tidak kosong, operasi GetRange mengembalikan hanya data dalam rentang `[inclusive_start_primary_key, next_start_primary_key)`. Jika Anda ingin mendapatkan sisa data, atur inclusive_start_primary_key ke nilai next_start_primary_key dan pertahankan nilai exclusive_end_primary_key dalam permintaan asli untuk memanggil operasi GetRange lagi. Catatan Operasi GetRange dapat mengembalikan hingga 5.000 baris untuk setiap permintaan. Ukuran total data dalam baris tidak boleh melebihi 4 MB. Respons terhadap permintaan GetRange mungkin berisi nilai next_start_primary_key meskipun Anda tidak menentukan batas dalam permintaan. Saat Anda memanggil operasi GetRange, Anda harus memeriksa apakah respons berisi next_start_primary_key.

Menggunakan SDK Tablestore

Gunakan SDK Tablestore berikut untuk membaca data dengan nilai kunci primer dalam rentang tertentu:

SDK Tablestore untuk Java: Baca data dengan nilai kunci primer dalam rentang tertentu
SDK Tablestore untuk Go: Baca data dengan nilai kunci primer dalam rentang tertentu
SDK Tablestore untuk Python: Baca data dengan nilai kunci primer dalam rentang tertentu
SDK Tablestore untuk Node.js: Baca data dengan nilai kunci primer dalam rentang tertentu
SDK Tablestore untuk .NET: Baca data dengan nilai kunci primer dalam rentang tertentu
SDK Tablestore untuk PHP: Baca data dengan nilai kunci primer dalam rentang tertentu

Konsumsi CU

Jumlah CU baca yang dikonsumsi untuk operasi GetRange dibulatkan ke atas dari hasil perhitungan rumus berikut: Jumlah CU baca yang dikonsumsi = (Ukuran data di semua kolom kunci primer dari baris yang memenuhi kondisi kueri + Ukuran data di kolom atribut yang dibaca)/4 KB. Untuk informasi lebih lanjut tentang cara menghitung ukuran data, lihat Penggunaan Penyimpanan.
Jika permintaan habis waktu dan hasilnya tidak terdefinisi, CUs mungkin atau mungkin tidak dikonsumsi.
Jika kode status HTTP 5xx dikembalikan, yang menunjukkan bahwa kesalahan internal terjadi, operasi tidak mengonsumsi CU. Jika kesalahan lain dikembalikan, satu CU baca dikonsumsi.