Tablestore：Membaca data

Metode kueri

Tablestore menyediakan operasi GetRow, BatchGetRow, dan GetRange untuk membaca data. Sebelum memulai pembacaan, pilih metode kueri sesuai dengan skenario yang diinginkan.

Prasyarat

• Instansi OTSClient harus diinisialisasi. Lihat Inisialisasi Instansi OTSClient.

• Tabel data harus dibuat dan berisi data. Lihat Buat Tabel Data dan Tulis Data.

Membaca satu baris data

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

Operasi API

/// <summary>
/// Membaca satu baris data berdasarkan informasi kunci primer yang ditentukan. 
/// </summary>
/// <param name="request">Permintaan kueri data</param>
/// <returns>Respons GetRow</returns>
public GetRowResponse GetRow(GetRowRequest request);

/// <summary>
/// Mode asinkron dari GetRow. 
/// </summary>
public Task<GetRowResponse> GetRowAsync(GetRowRequest request);          

Parameter

Kode sampel

    // Tentukan informasi kunci primer baris. Informasi kunci primer harus sama dengan informasi kunci primer yang ditentukan dalam TableMeta saat tabel dibuat. 
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    try
    {
        // Buat objek permintaan kueri. Seluruh baris dibaca jika tidak ada kolom yang ditentukan. 
        var request = new GetRowRequest(TableName, primaryKey);

        // Panggil operasi GetRow untuk menanyakan data. 
        var response = otsClient.GetRow(request);

        // Kembalikan data baris. Dalam contoh ini, kode sampel yang digunakan untuk mengembalikan data baris dihilangkan. Untuk melihat kode sampel lengkap, kunjungi tautan GitHub yang disediakan untuk kode sampel ini. 

        // Jika operasi berhasil, tidak ada pengecualian yang dikembalikan. 
        Console.WriteLine("Dapatkan baris berhasil.");
    }
    catch (Exception ex)
    {
        // Jika operasi gagal, pengecualian dikembalikan. Tangani pengecualian. 
        Console.WriteLine("Pembaruan tabel gagal, pengecualian:{0}", ex.Message);
    }
            

    // Tentukan informasi kunci primer baris. Informasi kunci primer harus sama dengan informasi kunci primer yang ditentukan dalam TableMeta saat tabel dibuat. 
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    var rowQueryCriteria = new SingleRowQueryCriteria("SampleTable");
    rowQueryCriteria.RowPrimaryKey = primaryKey;

    // Kondisi 1: Nilai kolom col0 adalah 5. 
    var filter1 = new RelationalCondition("col0",
                RelationalCondition.CompareOperator.EQUAL,
                new ColumnValue(5));

    // Kondisi 2: Nilai kolom col1 bukan ff. 
    var filter2 = new RelationalCondition("col1", RelationalCondition.CompareOperator.NOT_EQUAL, new ColumnValue("ff"));

    // Buat kombinasi Kondisi 1 dan Kondisi 2. Kondisi dievaluasi menggunakan operator OR. 
    var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
    filter.AddCondition(filter1);
    filter.AddCondition(filter2);

    rowQueryCriteria.Filter = filter;

    // Tentukan col0 dan col1 sebagai kolom yang ingin Anda baca. Tablestore menanyakan nilai kolom col0 dan col1, lalu mengembalikan baris yang memenuhi kondisi filter. 
    rowQueryCriteria.AddColumnsToGet("col0");
    rowQueryCriteria.AddColumnsToGet("col1");

    // Buat objek GetRowRequest. 
    var request = new GetRowRequest(rowQueryCriteria);

    try
    {
        // Lakukan kueri. 
        var response = otsClient.GetRow(request);

        // Kembalikan data atau lakukan operasi logis terkait. Dalam contoh ini, kode yang digunakan untuk mengembalikan data atau melakukan operasi logis terkait dihilangkan. 

        // Jika operasi berhasil, tidak ada pengecualian yang dikembalikan. 
        Console.WriteLine("Dapatkan baris dengan filter berhasil.");
    }
    catch (Exception ex)
    {
        // Jika operasi gagal, pengecualian dikembalikan. Tangani pengecualian. 
        Console.WriteLine("Dapatkan baris dengan filter gagal, pengecualian:{0}", ex.Message);
    }          

Membaca beberapa baris data sekaligus

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

Setiap operasi GetRow dalam BatchGetRow dilakukan secara terpisah. Tablestore mengembalikan respons untuk setiap operasi GetRow secara individual.

Catatan penggunaan

• Jika beberapa baris gagal dibaca saat menggunakan BatchGetRow, Tablestore tidak mengembalikan pengecualian tetapi memberikan informasi tentang baris yang gagal dalam respons BatchGetRowResponse. Periksa nilai pengembalian untuk memastikan keberhasilan pembacaan setiap baris.

• Operasi BatchGetRow menggunakan pengaturan parameter yang sama untuk semua baris. Sebagai contoh, jika parameter ColumnsToGet diatur ke [colA], hanya nilai kolom colA yang akan dibaca dari semua baris.

• Anda dapat membaca maksimal 100 baris sekaligus menggunakan BatchGetRow.

Operasi API

/// <summary>
/// <para>Baca beberapa baris data dari satu atau lebih tabel sekaligus. </para>
/// <para>Operasi BatchGetRow adalah serangkaian operasi GetRow. Setiap operasi dilakukan, mengembalikan hasil, dan menghitung unit kapasitas yang dikonsumsi (CUs) secara mandiri. </para>
/// Dibandingkan dengan banyak operasi GetRow, operasi BatchGetRow dapat mengurangi waktu respons dan meningkatkan laju pembacaan data. 
/// </summary>
/// <param name="request">Contoh permintaan</param>
/// <returns>Contoh respons</returns>
public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);

/// <summary>
/// Mode asinkron dari BatchGetRow. 
/// </summary>
public Task<BatchGetRowResponse> BatchGetRowAsync(BatchGetRowRequest request);            

Kode sampel

Contoh kode berikut menunjukkan cara membaca 10 baris data sekaligus:

// Buat objek permintaan untuk membaca beberapa baris data sekaligus. Tentukan informasi kunci primer untuk 10 baris data. 
List<PrimaryKey> primaryKeys = new List<PrimaryKey>();
for (int i = 0; i < 10; i++)
{
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(i));
    primaryKey.Add("pk1", new ColumnValue("abc"));
    primaryKeys.Add(primaryKey);
}

try
{
    BatchGetRowRequest request = new BatchGetRowRequest();
    request.Add(TableName, primaryKeys);

    // Panggil operasi BatchGetRow untuk membaca 10 baris data. 
    var response = otsClient.BatchGetRow(request);
    var tableRows = response.RowDataGroupByTable;
    var rows = tableRows[TableName];

    // Kembalikan data baris. Dalam contoh ini, kode sampel yang digunakan untuk mengembalikan data baris dihilangkan. Untuk melihat kode sampel lengkap, kunjungi tautan GitHub yang disediakan untuk kode sampel ini. 

    // Saat Anda memanggil operasi BatchGetRow untuk membaca beberapa baris sekaligus, beberapa baris mungkin gagal dibaca. Anda harus memeriksa nilai pengembalian untuk menentukan apakah data berhasil dibaca dari setiap baris. Untuk melihat kode sampel lengkap, kunjungi tautan GitHub yang disediakan untuk kode sampel ini. 
}
catch (Exception ex)
{
    // Jika operasi gagal, pengecualian dikembalikan. Tangani pengecualian. 
    Console.WriteLine("Batch get row gagal, pengecualian:{0}", ex.Message);
}            

Lihat kode lengkap di 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 mendukung pembacaan maju atau mundur dengan batasan jumlah baris. Jika rentang besar, pemindaian akan berhenti ketika batas atas tercapai, dan informasi tentang baris berikutnya dikembalikan untuk dilanjutkan.

Catatan penggunaan

Operasi GetRange mengikuti prinsip pencocokan paling kiri. Tablestore membandingkan nilai kolom kunci primer secara berurutan untuk membaca data dalam rentang tertentu.

• 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 digunakan.

Operasi API

/// <summary>
/// Kueri data yang nilai kunci primernya berada dalam rentang tertentu. 
/// </summary>
/// <param name="request">Contoh permintaan</param>
/// <returns>Contoh respons</returns>
public GetRangeResponse GetRange(GetRangeRequest request);

/// <summary>
/// Mode asinkron dari GetRange. 
/// </summary>
/// <param name="request"></param>
/// <returns></returns>
public Task<GetRangeResponse> GetRangeAsync(GetRangeRequest request);              

Parameter

Kode sampel

Contoh kode berikut menunjukkan cara membaca data dengan nilai kunci primer dalam rentang tertentu:

// Baca semua baris yang nilai kunci primernya berada dalam rentang (0, INF_MIN) hingga (100, INF_MAX). 
var inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", ColumnValue.INF_MIN);

var exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(100));
exclusiveEndPrimaryKey.Add("pk1", ColumnValue.INF_MAX);

try
{
    // Buat objek permintaan untuk membaca data yang nilai kunci primernya berada dalam rentang tertentu. 
    var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                    inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);

    var response = otsClient.GetRange(request);

    // Lanjutkan operasi baca jika hanya sebagian data yang dikembalikan. 
    var rows = response.RowDataList;
    var nextStartPrimaryKey = response.NextPrimaryKey;
    while (nextStartPrimaryKey != null)
    {
        request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                        nextStartPrimaryKey, exclusiveEndPrimaryKey);
        response = otsClient.GetRange(request);
        nextStartPrimaryKey = response.NextPrimaryKey;
        foreach (RowDataFromGetRange row in response.RowDataList)
        {
            rows.Add(row);
        }
    }

    // Kembalikan data baris. Dalam contoh ini, kode sampel yang digunakan untuk mengembalikan data baris dihilangkan. Untuk melihat kode sampel lengkap, kunjungi tautan GitHub yang disediakan untuk kode sampel ini. 

    // Jika operasi berhasil, tidak ada pengecualian yang dikembalikan. 
    Console.WriteLine("Dapatkan rentang berhasil");
}
catch (Exception ex)
{
    // Jika operasi gagal, pengecualian dikembalikan. Tangani pengecualian. 
    Console.WriteLine("Dapatkan rentang gagal, pengecualian:{0}", ex.Message);
}            

Lihat kode lengkap di GetRange@GitHub.

Membaca data yang nilai kunci primernya berada dalam rentang tertentu menggunakan iterator

Gunakan operasi GetRangeIterator untuk membaca data dengan nilai kunci primer dalam rentang tertentu menggunakan iterator.

Operasi API

/// <summary>
/// Dapatkan data dari beberapa baris yang nilai kunci primernya berada dalam rentang yang ditentukan. Kembalikan iterator yang digunakan untuk memproses setiap baris data. 
/// </summary>
/// <param name="request"><see cref="GetIteratorRequest"/></param>
/// <returns>Kembalikan iterator <see cref="RowDataFromGetRange"/>. </returns>
public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);           

Kode sampel

Contoh kode berikut menunjukkan cara membaca semua baris dengan nilai kunci primer dalam rentang (0, "a") hingga (1000, "xyz"):

// Baca semua baris yang nilai kunci primernya berada dalam rentang (0, "a") hingga (1000, "xyz"). 
PrimaryKey inclusiveStartPrimaryKey = new PrimaryKey();
inclusiveStartPrimaryKey.Add("pk0", new ColumnValue(0));
inclusiveStartPrimaryKey.Add("pk1", new ColumnValue("a"));

PrimaryKey exclusiveEndPrimaryKey = new PrimaryKey();
exclusiveEndPrimaryKey.Add("pk0", new ColumnValue(1000));
exclusiveEndPrimaryKey.Add("pk1", new ColumnValue("xyz"));

// Buat objek CapacityUnit untuk mencatat jumlah CU yang dikonsumsi oleh iterasi. 
var cu = new CapacityUnit(0, 0);

try
{
    // Buat objek GetIteratorRequest. Kondisi filter didukung. 
    var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
                                                exclusiveEndPrimaryKey, cu);

    var iterator = otsClient.GetRangeIterator(request);
    // Gunakan iterator yang membaca data dengan cara traversal. 
    foreach (var row in iterator)
    {
        // Jalankan logika pemrosesan. 
    }

    Console.WriteLine("Iterasi baris berhasil");
} 
catch (Exception ex)
{
    Console.WriteLine("Iterasi baris gagal, pengecualian:{0}", ex.Message);
}            

Lihat kode lengkap di GetRangeIterator@GitHub.