Baca data dari secondary index - Tablestore SDK for Java - Tablestore

Gunakan Tablestore SDK for Java untuk membaca data melalui secondary index global atau lokal.

Prasyarat

Instal Tablestore SDK for Java dan inisialisasi klien.

Deskripsi fitur

Secondary index menyusun ulang kolom kunci primer dan kolom pradefinisi dari tabel data untuk menyediakan jalur baca alternatif. Tabel indeks bersifat read-only dan berisi kunci primer indeks, kolom kunci primer yang secara otomatis ditambahkan oleh Tablestore dari tabel data, serta kolom atribut yang ditentukan saat pembuatan indeks. Untuk mengambil kolom atribut yang tidak termasuk dalam tabel indeks, gunakan kunci primer tabel data yang dikembalikan untuk melakukan kueri terhadap tabel data. Untuk informasi selengkapnya, lihat Secondary indexes.

Saat membaca tabel indeks, nama dan urutan kolom kunci primernya harus sesuai dengan skema kunci primer tabel indeks. Misalnya, asumsikan sebuah tabel data menggunakan user_id dan order_id sebagai kunci primernya, dan category ditambahkan sebagai kolom indeks. Tabel berikut membandingkan urutan kunci primer lengkap dari secondary index global dan lokal.

Jenis indeks	Kunci primer indeks yang ditentukan saat pembuatan indeks	Urutan kunci primer lengkap tabel indeks
Global secondary index	`category`	`category`, `user_id`, dan `order_id`. Tablestore menambahkan kolom kunci primer tabel data yang tidak ditentukan ke kunci primer indeks.
Local secondary index	`user_id` dan `category`	`user_id`, `category`, dan `order_id`. Kolom pertama kunci primer indeks harus sama dengan kolom kunci primer pertama tabel data.

Penting

Saat global secondary index dibuat untuk menyertakan data yang sudah ada, tabel indeks tidak dapat dibaca hingga proses pembangunan dan sinkronisasi data selesai. Tunggu hingga sinkronisasi selesai sebelum membaca tabel indeks.

Panggil getRow untuk membaca satu baris menggunakan kunci primer lengkap tabel indeks.

public GetRowResponse getRow(GetRowRequest getRowRequest)
        throws TableStoreException, ClientException

Panggil getRange untuk membaca data dalam rentang kunci primer tabel indeks.

public GetRangeResponse getRange(GetRangeRequest getRangeRequest)
        throws TableStoreException, ClientException

Contoh berikut membaca satu baris dari secondary index global example_global_index menggunakan kunci primer lengkapnya dan hanya mengembalikan kolom atribut status.

PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.fromString("user-1"))
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.fromLong(101L))
        .build();

SingleRowQueryCriteria criteria =
        new SingleRowQueryCriteria("example_global_index", primaryKey);
criteria.addColumnsToGet("status");
criteria.setMaxVersions(1);

GetRowResponse response = client.getRow(new GetRowRequest(criteria));
System.out.println(response.getRow());

Parameter

Parameter untuk membaca satu baris

GetRowRequest berisi parameter berikut.

Nama	Tipe	Deskripsi
rowQueryCriteria (wajib)	`SingleRowQueryCriteria`	Kondisi untuk membaca satu baris.

Kondisi baca satu baris

rowQueryCriteria bertipe SingleRowQueryCriteria dan berisi parameter berikut.

Nama	Tipe	Deskripsi
tableName (wajib)	`String`	Nama tabel indeks.
primaryKey (wajib)	`PrimaryKey`	Kunci primer lengkap baris dalam tabel indeks. Kunci primer harus berisi kolom kunci primer indeks yang ditentukan saat pembuatan indeks dan kolom kunci primer tabel data yang secara otomatis ditambahkan oleh Tablestore. Nama dan urutan kolomnya harus sesuai dengan skema tabel indeks.
columnsToGet (opsional)	`Set<String>`	Nama kolom atribut yang akan dikembalikan. Anda dapat menentukan hingga 128 kolom. Jika parameter ini tidak ditentukan, semua kolom atribut baris dalam tabel indeks akan dikembalikan. Kolom atribut yang tidak termasuk dalam tabel indeks tidak dikembalikan dan harus diambil dari tabel data.
maxVersions (wajib bersyarat)	`int`	Jumlah maksimum versi yang dikembalikan untuk setiap kolom atribut. Nilainya harus lebih besar dari 0. Secondary index hanya menyimpan versi terbaru. Dalam kebanyakan kasus, atur parameter ini ke `1`. Tentukan salah satu dari `maxVersions` atau `timeRange`, tetapi tidak keduanya.
timeRange (wajib bersyarat)	`TimeRange`	Rentang waktu versi kolom atribut, dalam milidetik. Rentang ini tertutup di kiri dan terbuka di kanan. Tentukan salah satu dari `timeRange` atau `maxVersions`, tetapi tidak keduanya.
filter (opsional)	`Filter`	Filter sisi server. Baris tidak dikembalikan jika tidak memenuhi kondisi filter.
startColumn (opsional)	`String`	Nama kolom atribut pertama yang dikembalikan dalam urutan leksikografis. Kolom yang ditentukan termasuk dalam hasil. Parameter ini ditujukan untuk membaca baris lebar (wide rows).
endColumn (opsional)	`String`	Nama kolom atribut terakhir dalam urutan leksikografis. Kolom yang ditentukan tidak termasuk dalam hasil. Parameter ini ditujukan untuk membaca baris lebar (wide rows).

Parameter untuk membaca rentang baris

GetRangeRequest berisi parameter berikut.

Nama	Tipe	Deskripsi
rangeRowQueryCriteria (wajib)	`RangeRowQueryCriteria`	Kondisi untuk membaca rentang baris.

Kondisi baca rentang

rangeRowQueryCriteria bertipe RangeRowQueryCriteria dan berisi parameter berikut.

Nama	Tipe	Deskripsi
tableName (wajib)	`String`	Nama tabel indeks.
inclusiveStartPrimaryKey (wajib)	`PrimaryKey`	Kunci primer awal rentang. Kunci primer ini termasuk dalam hasil dan harus berisi semua kolom kunci primer tabel indeks. Anda dapat menggunakan `INF_MIN` dan `INF_MAX` untuk merepresentasikan nilai minimum dan maksimum kolom kunci primer.
exclusiveEndPrimaryKey (wajib)	`PrimaryKey`	Kunci primer akhir rentang. Kunci primer ini tidak termasuk dalam hasil dan harus berisi semua kolom kunci primer tabel indeks. Anda dapat menggunakan `INF_MIN` dan `INF_MAX` untuk merepresentasikan nilai minimum dan maksimum kolom kunci primer.
direction (opsional)	`Direction`	Arah pembacaan. Nilai yang valid adalah `FORWARD` dan `BACKWARD`. Nilai default: `FORWARD`. Untuk pembacaan maju, kunci primer awal harus lebih kecil daripada kunci primer akhir. Untuk pembacaan mundur, kunci primer awal harus lebih besar daripada kunci primer akhir.
limit (opsional)	`int`	Jumlah maksimum baris yang dikembalikan dalam satu permintaan. Nilainya harus lebih besar dari 0. Nilai default adalah `-1`, yang berarti client tidak membatasi jumlah baris yang dikembalikan. Server mengembalikan paling banyak 5.000 baris dan data sebesar 4 MB dalam satu respons.
columnsToGet (opsional)	`Set<String>`	Nama kolom atribut yang akan dikembalikan. Anda dapat menentukan hingga 128 kolom. Jika parameter ini tidak ditentukan, semua kolom atribut setiap baris dalam tabel indeks akan dikembalikan. Jika tidak ada kolom atribut yang ditentukan dalam suatu baris, baris tersebut tidak dikembalikan. Sebelum melakukan kueri terhadap tabel data, baca kolom yang ada dalam tabel indeks atau biarkan parameter ini tidak ditentukan.
maxVersions (wajib bersyarat)	`int`	Jumlah maksimum versi yang dikembalikan untuk setiap kolom atribut. Nilainya harus lebih besar dari 0. Secondary index hanya menyimpan versi terbaru. Dalam kebanyakan kasus, atur parameter ini ke `1`. Tentukan salah satu dari `maxVersions` atau `timeRange`, tetapi tidak keduanya.
timeRange (wajib bersyarat)	`TimeRange`	Rentang waktu versi kolom atribut, dalam milidetik. Rentang ini tertutup di kiri dan terbuka di kanan. Tentukan salah satu dari `timeRange` atau `maxVersions`, tetapi tidak keduanya.
filter (opsional)	`Filter`	Filter sisi server. Hanya baris yang memenuhi kondisi filter yang dikembalikan.
startColumn (opsional)	`String`	Nama kolom atribut pertama yang dikembalikan dalam urutan leksikografis. Kolom yang ditentukan termasuk dalam hasil. Parameter ini ditujukan untuk membaca baris lebar (wide rows).
endColumn (opsional)	`String`	Nama kolom atribut terakhir dalam urutan leksikografis. Kolom yang ditentukan tidak termasuk dalam hasil. Parameter ini ditujukan untuk membaca baris lebar (wide rows).

Nilai kembalian

Nilai kembalian untuk membaca satu baris

GetRowResponse berisi parameter respons berikut.

Nama	Tipe	Deskripsi
row	`Row`	Baris yang dikembalikan. Jika baris tidak ada, `null` dikembalikan.
consumedCapacity	`ConsumedCapacity`	Unit kapasitas yang dikonsumsi oleh operasi.

Nilai kembalian untuk membaca rentang baris

GetRangeResponse berisi parameter respons berikut.

Nama	Tipe	Deskripsi
rows	`List<Row>`	Baris yang dikembalikan oleh permintaan.
nextStartPrimaryKey	`PrimaryKey`	Kunci primer awal untuk permintaan berikutnya. Jika parameter ini bukan `null`, gunakan sebagai `inclusiveStartPrimaryKey` dalam permintaan berikutnya. Jika parameter ini `null`, semua baris dalam rentang yang ditentukan telah dibaca. Parameter ini mungkin dikembalikan ketika respons mencapai batas server meskipun `limit` tidak ditentukan.
consumedCapacity	`ConsumedCapacity`	Unit kapasitas yang dikonsumsi oleh operasi.

Skenario

Baca rentang baris dari global secondary index

Contoh berikut membaca baris-baris yang memiliki nilai category sebesar books dari secondary index global example_global_index dan menangani token pagination nextStartPrimaryKey.

PrimaryKey startPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MIN)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MIN)
        .build();
PrimaryKey endPrimaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
        .addPrimaryKeyColumn("category", PrimaryKeyValue.fromString("books"))
        .addPrimaryKeyColumn("user_id", PrimaryKeyValue.INF_MAX)
        .addPrimaryKeyColumn("order_id", PrimaryKeyValue.INF_MAX)
        .build();

RangeRowQueryCriteria rangeCriteria =
        new RangeRowQueryCriteria("example_global_index");
rangeCriteria.setInclusiveStartPrimaryKey(startPrimaryKey);
rangeCriteria.setExclusiveEndPrimaryKey(endPrimaryKey);
rangeCriteria.setMaxVersions(1);
rangeCriteria.setLimit(100);

List<Row> rows = new ArrayList<>();
while (true) {
    GetRangeResponse response =
            client.getRange(new GetRangeRequest(rangeCriteria));
    rows.addAll(response.getRows());

    if (response.getNextStartPrimaryKey() == null) {
        break;
    }
    rangeCriteria.setInclusiveStartPrimaryKey(
            response.getNextStartPrimaryKey());
}
rows.forEach(System.out::println);

Kueri tabel data untuk kolom atribut

Contoh berikut menggunakan rows yang dikembalikan pada contoh sebelumnya. Contoh ini mengekstrak kunci primer tabel data dari setiap kunci primer tabel indeks dan melakukan kueri terhadap tabel data example_table untuk kolom atribut detail, yang tidak termasuk dalam tabel indeks.

for (Row indexRow : rows) {
    PrimaryKey indexPrimaryKey = indexRow.getPrimaryKey();
    PrimaryKey primaryKey = PrimaryKeyBuilder.createPrimaryKeyBuilder()
            .addPrimaryKeyColumn(
                    "user_id",
                    indexPrimaryKey.getPrimaryKeyColumn("user_id").getValue())
            .addPrimaryKeyColumn(
                    "order_id",
                    indexPrimaryKey.getPrimaryKeyColumn("order_id").getValue())
            .build();

    SingleRowQueryCriteria rowCriteria =
            new SingleRowQueryCriteria("example_table", primaryKey);
    rowCriteria.addColumnsToGet("detail");
    rowCriteria.setMaxVersions(1);

    GetRowResponse response =
            client.getRow(new GetRowRequest(rowCriteria));
    System.out.println(response.getRow());
}