Bagaimana cara menggunakan SDK untuk Node.js untuk membaca satu baris data, membaca beberapa baris data sekaligus, atau membaca data yang nilai kunci primernya berada dalam rentang tertentu? - Tablestore

Tablestore menyediakan berbagai operasi untuk membaca data. Anda dapat menggunakan operasi GetRow untuk membaca satu baris data, BatchGetRow untuk membaca beberapa baris sekaligus, dan GetRange untuk membaca data dengan nilai kunci primer dalam rentang tertentu.

Metode Kueri

Tablestore menyediakan operasi GetRow, BatchGetRow, dan GetRange untuk membaca data. Pilih metode kueri yang sesuai berdasarkan skenario penggunaan Anda.

Penting

Untuk membaca data dari tabel dengan kolom kunci primer auto-increment, pastikan semua nilai kolom kunci primer termasuk nilai kolom auto-increment telah ditentukan. Untuk informasi lebih lanjut, lihat Konfigurasi kolom kunci primer auto-increment. Jika nilai kolom auto-increment tidak tersedia, gunakan operasi GetRange untuk menentukan rentang pembacaan berdasarkan nilai kunci primer kolom pertama.

Metode Kueri	Deskripsi	Skenario
Membaca satu baris data	Gunakan operasi GetRow untuk membaca satu baris data.	Cocok untuk skenario di mana semua kolom kunci primer dapat ditentukan dan jumlah baris yang dibaca sedikit.
Membaca beberapa baris data sekaligus	Gunakan operasi BatchGetRow untuk membaca beberapa baris data dari satu atau lebih tabel sekaligus. Operasi BatchGetRow terdiri dari beberapa operasi GetRow. Proses pembuatan suboperasi sama dengan pemanggilan operasi GetRow.	Cocok untuk skenario di mana semua kolom kunci primer dapat ditentukan dan jumlah baris yang dibaca besar atau data harus dibaca dari beberapa tabel.
Membaca data dalam rentang tertentu	Gunakan operasi GetRange untuk membaca data dengan nilai kunci primer dalam rentang tertentu. Operasi GetRange memungkinkan pembacaan data ke arah maju atau mundur dengan batasan jumlah baris. Jika rentang besar dan melebihi batas atas, pemindaian berhenti, dan baris yang dibaca serta informasi kunci primer baris berikutnya dikembalikan. Permintaan baru dapat dimulai dari posisi terakhir.	Cocok untuk skenario di mana rentang atau awalan kolom kunci primer dapat ditentukan. Penting Jika awalan kolom kunci primer tidak dapat ditentukan, gunakan INF_MIN dan INF_MAX untuk menentukan rentang semua kolom kunci primer. Operasi ini memindai seluruh tabel tetapi mengonsumsi banyak sumber daya komputasi. Gunakan dengan hati-hati.

Prasyarat

Instansi OTSClient harus diinisialisasi. Untuk informasi lebih lanjut, lihat Inisialisasi instansi OTSClient.
Tabel data harus dibuat dan data telah ditulis ke tabel. Untuk informasi lebih lanjut, lihat Buat tabel data dan Tulis data.

Membaca satu baris data

Gunakan operasi GetRow untuk membaca satu baris data. Setelah memanggil operasi GetRow, salah satu hasil berikut mungkin dikembalikan:

Operasi API

/*
 * Membaca satu baris data berdasarkan informasi kunci primer yang ditentukan. 
 */
getRow(params, callback)

Parameter

Parameter	Deskripsi
tableName	Nama tabel.
primaryKey	Informasi kunci primer dari baris. Informasi kunci primer terdiri dari nama kolom kunci primer, tipe kunci primer, dan nilai kunci primer. Penting Jumlah dan tipe kolom kunci primer yang Anda tentukan harus sama dengan jumlah dan tipe kolom kunci primer aktual dalam tabel.
columnsToGet	Kolom yang ingin Anda baca. Anda dapat menentukan nama kolom kunci primer atau kolom atribut. Jika Anda tidak menentukan kolom, semua data dalam baris dikembalikan. Jika Anda menentukan kolom tetapi baris tidak berisi kolom yang ditentukan, nilai pengembalian adalah null. Jika baris berisi beberapa dari kolom yang ditentukan, data dalam beberapa kolom yang ditentukan dari baris tersebut dikembalikan. Catatan Secara default, Tablestore mengembalikan data dari semua kolom baris saat Anda menanyakan baris tersebut. Anda dapat menggunakan parameter columnsToGet untuk mengembalikan data dari kolom tertentu. Jika col0 dan col1 ditambahkan ke parameter columnsToGet, hanya nilai kolom col0 dan col1 yang dikembalikan. Jika Anda menentukan parameter columnsToGet dan columnFilter, Tablestore menanyakan kolom yang ditentukan oleh parameter columnsToGet, lalu mengembalikan baris yang memenuhi kondisi filter.
maxVersions	Jumlah maksimum versi data yang dapat Anda baca. Penting Anda harus menentukan setidaknya salah satu parameter maxVersions dan timeRange. Jika Anda hanya menentukan parameter maxVersions, data dari jumlah versi yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Jika Anda hanya menentukan parameter timeRange, semua data yang versinya berada dalam rentang waktu yang ditentukan atau data dari versi yang ditentukan dikembalikan. Jika Anda menentukan kedua parameter maxVersions dan timeRange, data dari jumlah versi yang ditentukan dalam rentang waktu yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama.
timeRange	Rentang waktu versi atau versi spesifik yang ingin Anda baca. Untuk informasi lebih lanjut, lihat TimeRange. Penting Anda harus menentukan setidaknya salah satu parameter maxVersions dan timeRange. Jika Anda hanya menentukan parameter maxVersions, data dari jumlah versi yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Jika Anda hanya menentukan parameter timeRange, semua data yang versinya berada dalam rentang waktu yang ditentukan atau data dari versi yang ditentukan dikembalikan. Jika Anda menentukan kedua parameter maxVersions dan timeRange, data dari jumlah versi yang ditentukan dalam rentang waktu yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Untuk menanyakan data yang versinya berada dalam rentang waktu tertentu, Anda harus menentukan parameter start_time dan end_time. Parameter start_time menentukan timestamp awal. Parameter end_time menentukan timestamp akhir. Rentang yang ditentukan adalah interval tertutup-kiri, terbuka-kanan dalam format `[start_time, end_time)`. Untuk menanyakan data dari versi tertentu, Anda harus menentukan parameter specific_time. Parameter specific_time menentukan timestamp tertentu. Hanya salah satu dari specific_time dan `[start_time, end_time)` yang diperlukan. Nilai valid parameter timeRange: 0 hingga `Long.MAX_VALUE`. Unit: milidetik.
columnFilter	Filter yang ingin Anda gunakan untuk menyaring hasil kueri di sisi server. Hanya baris yang memenuhi kondisi filter yang dikembalikan. Untuk informasi lebih lanjut, lihat Konfigurasi filter. Catatan Jika Anda menentukan parameter columnsToGet dan columnFilter, Tablestore menanyakan kolom yang ditentukan oleh parameter columnsToGet, lalu mengembalikan baris yang memenuhi kondisi filter.

Contoh kode

Berikut adalah contoh kode untuk membaca satu baris data:

var TableStore = require('../index.js');
var Long = TableStore.Long;
var client = require('./client');

var params = {
  tableName: "sampleTable",
  primaryKey: [{ 'gid': Long.fromNumber(20004) }, { 'uid': Long.fromNumber(20004) }],
  maxVersions: 2 // Tentukan jumlah maksimum versi data yang dapat dibaca. Nilai 2 menentukan bahwa Anda dapat membaca maksimal dua versi data. 
};
var condition = new TableStore.CompositeCondition(TableStore.LogicalOperator.AND);
condition.addSubCondition(new TableStore.SingleColumnCondition('name', 'john', TableStore.ComparatorType.EQUAL));
condition.addSubCondition(new TableStore.SingleColumnCondition('addr', 'china', TableStore.ComparatorType.EQUAL));

params.columnFilter = condition;

client.getRow(params, function (err, data) {
  if (err) {
    console.log('error:', err);
    return;
  }
  console.log('success:', data);
});

Untuk melihat contoh kode lengkap, kunjungi GetRow@GitHub.

Membaca beberapa baris data sekaligus

Gunakan operasi BatchGetRow untuk membaca beberapa baris data dari satu atau lebih tabel sekaligus. Operasi BatchGetRow terdiri dari beberapa operasi GetRow.

Setiap operasi GetRow dilakukan secara terpisah, dan respons untuk setiap operasi dikembalikan secara individual oleh Tablestore.

Catatan Penggunaan

Saat memanggil operasi BatchGetRow untuk membaca beberapa baris sekaligus, ada kemungkinan beberapa baris gagal dibaca. Jika hal ini terjadi, Tablestore tidak mengembalikan pengecualian, melainkan mengembalikan BatchGetRowResponse yang mencakup informasi tentang baris yang gagal. Oleh karena itu, saat memanggil operasi BatchGetRow, Anda harus memeriksa nilai pengembalian untuk memastikan keberhasilan pembacaan data dari setiap baris.
Operasi BatchGetRow menggunakan parameter yang sama untuk semua baris. Misalnya, jika parameter ColumnsToGet diatur ke [colA], hanya nilai kolom colA yang dibaca dari semua baris.
Anda dapat membaca maksimal 100 baris sekaligus menggunakan operasi BatchGetRow.

Operasi API

/**
 * Membaca beberapa baris data dari satu atau lebih tabel sekaligus. 
 */
batchGetRow(params, callback)

Parameter

Dibandingkan dengan operasi GetRow, operasi BatchGetRow memiliki perubahan berikut:

Hierarki dibuat untuk tabel, memungkinkan pembacaan data dari beberapa tabel sekaligus.
Gunakan parameter tables untuk menentukan informasi tabel dan baris tempat operasi baca dilakukan.
Parameter primaryKey memungkinkan penentuan informasi kunci primer untuk beberapa baris, sehingga data dapat dibaca dari beberapa baris sekaligus.
Catatan
Pastikan informasi kunci primer yang ditentukan ada dalam tabel. Jika tidak, data baris yang sesuai akan kosong dalam respons.

Contoh kode

Berikut adalah contoh kode untuk membaca data dari beberapa tabel sekaligus dan mencoba lagi operasi baca jika terjadi kesalahan:

var client = require('./client');
var TableStore = require('../index.js');
var Long = TableStore.Long;

var params = {
    tables: [{
        tableName: 'sampleTable',
        primaryKey: [
            [{ 'gid': Long.fromNumber(20013) }, { 'uid': Long.fromNumber(20013) }],
            [{ 'gid': Long.fromNumber(20015) }, { 'uid': Long.fromNumber(20015) }]
        ],
        startColumn: "col2",
        endColumn: "col4"
    },
    {
        tableName: 'notExistTable',
        primaryKey: [
            [{ 'gid': Long.fromNumber(10001) }, { 'uid': Long.fromNumber(10001) }]
        ]
    }
    ],
};

var maxRetryTimes = 3;
var retryCount = 0;

function batchGetRow(params) {
    client.batchGetRow(params, function (err, data) {
        if (err) {
            console.log('error:', err);
            return;
        }

        var isAllSuccess = true;
        var retryRequest = { tables: [] };
        for (var i = 0; i < data.tables.length; i++) {
            var failedRequest = { tableName: data.tables[i][0].tableName, primaryKey: [] };

            for (var j = 0; j < data.tables[i].length; j++) {
                if (!data.tables[i][j].isOk && null != data.tables[i][j].primaryKey) {
                    isAllSuccess = false;
                    var pks = [];
                    for (var k in data.tables[i][j].primaryKey) {
                        var name = data.tables[i][j].primaryKey[k].name;
                        var value = data.tables[i][j].primaryKey[k].value;
                        var kp = {};
                        kp[name] = value;
                        pks.push(kp);
                    }
                    failedRequest.primaryKey.push(pks);

                } else {
                    // get success data
                }
            }

            if (failedRequest.primaryKey.length > 0) {
                retryRequest.tables.push(failedRequest);
            }
        }

        if (!isAllSuccess && retryCount++ < maxRetryTimes) {
            batchGetRow(retryRequest);
        }

        console.log('success:', data);
    });
}

batchGetRow(params, maxRetryTimes);

Untuk melihat contoh kode lengkap, kunjungi BatchGetRow@GitHub.

Membaca data yang nilai kunci primernya berada dalam rentang tertentu

Gunakan operasi GetRange untuk membaca data dengan nilai kunci primer dalam rentang tertentu.

Operasi GetRange memungkinkan pembacaan data ke arah maju atau mundur dengan batasan jumlah baris. Jika rentang besar dan melebihi batas atas, pemindaian berhenti, dan baris yang dibaca serta informasi kunci primer baris berikutnya dikembalikan. Permintaan baru dapat dimulai dari posisi terakhir.

Catatan

Dalam tabel Tablestore, semua baris diurutkan berdasarkan kunci primer. Kunci primer terdiri dari semua kolom kunci primer secara berurutan, sehingga baris tidak disortir berdasarkan kolom kunci primer tertentu.

Catatan Penggunaan

Operasi GetRange mengikuti prinsip pencocokan paling kiri. Tablestore membandingkan nilai secara berurutan dari kolom kunci primer pertama hingga terakhir untuk membaca data dalam rentang tertentu. Misalnya, jika kunci primer terdiri dari PK1, PK2, dan PK3, Tablestore pertama-tama memeriksa apakah nilai PK1 suatu baris berada dalam rentang yang ditentukan. Jika ya, baris tersebut dikembalikan tanpa memeriksa kolom kunci primer lainnya. Jika tidak, proses dilanjutkan untuk kolom kunci primer berikutnya.

Jumlah data yang dipindai mencapai 4 MB.
Jumlah baris yang dipindai mencapai 5.000.
Jumlah baris yang dikembalikan mencapai batas atas.
Throughput baca tidak cukup untuk membaca baris data berikutnya karena semua throughput baca cadangan telah habis.

Operasi API

/**
 * Membaca data yang nilai kunci primernya berada dalam rentang tertentu. 
 */
getRange(params, callback)

Parameter

Parameter	Deskripsi
tableName	Nama tabel.
direction	Urutan di mana Anda ingin mengurutkan baris dalam respons. Jika Anda mengatur parameter ini ke FORWARD, nilai kunci primer awal harus lebih kecil dari nilai kunci primer akhir, dan baris dalam respons diurutkan dalam urutan naik nilai kunci primer. Jika Anda mengatur parameter ini ke BACKWARD, nilai kunci primer awal harus lebih besar dari nilai kunci primer akhir, dan baris dalam respons diurutkan dalam urutan turun nilai kunci primer. Misalnya, sebuah tabel memiliki dua nilai kunci primer A dan B, dan Nilai A lebih kecil dari Nilai B. Jika Anda mengatur parameter direction ke FORWARD dan menentukan rentang `[A, B)` untuk tabel, Tablestore mengembalikan baris yang nilai kunci primernya lebih besar dari atau sama dengan Nilai A tetapi lebih kecil dari Nilai B dalam urutan naik dari Nilai A ke Nilai B. Jika Anda mengatur parameter direction ke BACKWARD dan menentukan rentang `[B, A)` untuk tabel, Tablestore mengembalikan baris yang nilai kunci primernya lebih kecil dari atau sama dengan Nilai B dan lebih besar dari Nilai A dalam urutan turun dari Nilai B ke Nilai A.
inclusiveStartPrimaryKey	Informasi kunci primer awal dan informasi kunci primer akhir dari rentang yang ingin Anda baca. Kolom kunci primer awal dan kolom kunci primer akhir harus berupa kolom kunci primer valid atau kolom virtual yang datanya bertipe INF_MIN dan INF_MAX. Jumlah kolom dalam rentang yang ditentukan oleh kolom virtual harus sama dengan jumlah kolom kunci primer dari tabel yang ditentukan. INF_MIN menunjukkan nilai yang sangat kecil. Semua nilai tipe lainnya lebih besar dari nilai bertipe INF_MIN. INF_MAX menunjukkan nilai yang sangat besar. Semua nilai tipe lainnya lebih kecil dari nilai bertipe INF_MAX. Parameter inclusiveStartPrimaryKey menentukan kolom kunci primer awal dan nilainya. Jika suatu baris berisi kolom kunci primer awal, data baris tersebut dikembalikan. Parameter exclusiveEndPrimaryKey menentukan kolom kunci primer akhir dan nilainya. Jika suatu baris berisi kolom kunci primer akhir, data baris tersebut tidak dikembalikan. Baris dalam tabel diurutkan dalam urutan naik berdasarkan nilai kunci primer. Rentang yang digunakan untuk membaca data adalah interval tertutup-kiri, terbuka-kanan. Jika data dibaca ke arah maju, baris yang nilai kunci primernya lebih besar dari atau sama dengan nilai kunci primer awal tetapi lebih kecil dari nilai kunci primer akhir dikembalikan.
exclusiveEndPrimaryKey
limit	Jumlah maksimum baris yang dapat dikembalikan. Nilai parameter ini harus lebih besar dari 0. Tablestore menghentikan operasi setelah jumlah maksimum baris yang dapat dikembalikan dalam arah maju atau mundur tercapai, meskipun beberapa baris dalam rentang yang ditentukan belum dikembalikan. Anda dapat menggunakan nilai parameter nextStartPrimaryKey yang dikembalikan dalam respons untuk membaca data pada permintaan berikutnya.
columnsToGet	Kolom yang ingin Anda baca. Anda dapat menentukan nama kolom kunci primer atau kolom atribut. Jika Anda tidak menentukan kolom, semua data dalam baris dikembalikan. Jika Anda menentukan kolom tetapi baris tidak berisi kolom yang ditentukan, nilai pengembalian adalah null. Jika baris berisi beberapa dari kolom yang ditentukan, data dalam beberapa kolom yang ditentukan dari baris tersebut dikembalikan. Catatan Secara default, Tablestore mengembalikan data dari semua kolom baris saat Anda menanyakan baris tersebut. Anda dapat menggunakan parameter columnsToGet untuk mengembalikan data dari kolom tertentu. Jika col0 dan col1 ditambahkan ke parameter columnsToGet, hanya nilai kolom col0 dan col1 yang dikembalikan. Jika suatu baris berada dalam rentang yang ditentukan yang ingin Anda baca berdasarkan nilai kunci primer tetapi tidak berisi kolom yang ditentukan yang ingin Anda kembalikan, respons tidak menyertakan baris tersebut. Jika Anda menentukan parameter columnsToGet dan columnFilter, Tablestore menanyakan kolom yang ditentukan oleh parameter columnsToGet, lalu mengembalikan baris yang memenuhi kondisi filter.
maxVersions	Jumlah maksimum versi data yang dapat Anda baca. Penting Anda harus menentukan setidaknya salah satu parameter maxVersions dan timeRange. Jika Anda hanya menentukan parameter maxVersions, data dari jumlah versi yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Jika Anda hanya menentukan parameter timeRange, semua data yang versinya berada dalam rentang waktu yang ditentukan atau data dari versi yang ditentukan dikembalikan. Jika Anda menentukan kedua parameter maxVersions dan timeRange, data dari jumlah versi yang ditentukan dalam rentang waktu yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama.
timeRange	Rentang waktu versi atau versi spesifik yang ingin Anda baca. Untuk informasi lebih lanjut, lihat TimeRange. Penting Anda harus menentukan setidaknya salah satu parameter maxVersions dan timeRange. Jika Anda hanya menentukan parameter maxVersions, data dari jumlah versi yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Jika Anda hanya menentukan parameter timeRange, semua data yang versinya berada dalam rentang waktu yang ditentukan atau data dari versi yang ditentukan dikembalikan. Jika Anda menentukan kedua parameter maxVersions dan timeRange, data dari jumlah versi yang ditentukan dalam rentang waktu yang ditentukan dikembalikan dari entri data terbaru hingga entri data paling lama. Untuk menanyakan data yang versinya berada dalam rentang waktu tertentu, Anda harus menentukan parameter start_time dan end_time. Parameter start_time menentukan timestamp awal. Parameter end_time menentukan timestamp akhir. Rentang yang ditentukan adalah interval tertutup-kiri, terbuka-kanan dalam format `[start_time, end_time)`. Untuk menanyakan data dari versi tertentu, Anda harus menentukan parameter specific_time. Parameter specific_time menentukan timestamp tertentu. Hanya salah satu dari specific_time dan `[start_time, end_time)` yang diperlukan. Nilai valid parameter timeRange: 0 hingga `Long.MAX_VALUE`. Unit: milidetik.
columnFilter	Filter yang ingin Anda gunakan untuk menyaring hasil kueri di sisi server. Hanya baris yang memenuhi kondisi filter yang dikembalikan. Untuk informasi lebih lanjut, lihat Konfigurasi filter. Catatan Jika Anda menentukan parameter columnsToGet dan columnFilter, Tablestore menanyakan kolom yang ditentukan oleh parameter columnsToGet, lalu mengembalikan baris yang memenuhi kondisi filter.
nextStartPrimaryKey	Informasi kunci primer awal untuk permintaan baca berikutnya. Nilai parameter nextStartPrimaryKey dapat digunakan untuk menentukan apakah semua data telah dibaca. Jika nilai parameter nextStartPrimaryKey tidak kosong dalam respons, nilai tersebut dapat digunakan sebagai informasi kunci primer awal untuk operasi GetRange berikutnya. Jika nilai parameter nextStartPrimaryKey kosong dalam respons, semua data dalam rentang telah dikembalikan.

Contoh kode

Berikut adalah contoh kode untuk membaca data dalam rentang tertentu:

var Long = TableStore.Long;
var client = require('./client');

var params = {
  tableName: "sampleTable",
  direction: TableStore.Direction.FORWARD,
  inclusiveStartPrimaryKey: [{ "gid": TableStore.INF_MIN }, { "uid": TableStore.INF_MIN }],
  exclusiveEndPrimaryKey: [{ "gid": TableStore.INF_MAX }, { "uid": TableStore.INF_MAX }],
  limit: 50
};

client.getRange(params, function (err, data) {
  if (err) {
    console.log('error:', err);
    return;
  }

  // Jika nilai parameter data.next_start_primary_key tidak kosong, sistem melanjutkan membaca data. 
  if (data.next_start_primary_key) {

  }

  console.log('success:', data);
});

Untuk melihat contoh kode lengkap, kunjungi GetRange@GitHub.