Tablestore:Baca data

Metode kueri

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

Prasyarat

Sebelum memulai, pastikan Anda telah:

• Menginisialisasi instans OTSClient. Untuk informasi lebih lanjut, lihat Inisialisasi instans OTSClient.

• Tabel data dibuat dengan menuliskan data ke dalamnya. Untuk informasi lebih lanjut, lihat Membuat tabel data dan Menulis data.

Baca satu baris data

Panggil operasi GetRow untuk membaca satu baris berdasarkan kunci primernya.

Operasi API

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

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

Parameter

Kode contoh

    // Tentukan kunci utama. Kolom dan tipe harus sesuai dengan skema tabel.
    PrimaryKey primaryKey = new PrimaryKey();
    primaryKey.Add("pk0", new ColumnValue(0));
    primaryKey.Add("pk1", new ColumnValue("abc"));

    try
    {
        // Bangun permintaan. Mengabaikan columnsToGet mengembalikan seluruh baris.
        var request = new GetRowRequest(TableName, primaryKey);

        // Panggil GetRow.
        var response = otsClient.GetRow(request);

        // Proses data baris yang dikembalikan.
        // (Diabaikan di sini—lihat contoh GitHub untuk implementasi lengkap.)

        Console.WriteLine("Get row berhasil.");
    }
    catch (Exception ex)
    {
        Console.WriteLine("Update table gagal, exception:{0}", ex.Message);
    }

    // Tentukan kunci utama. Kolom dan tipe harus sesuai dengan skema tabel.
    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: col0 == 5
    var filter1 = new RelationalCondition("col0",
                RelationalCondition.CompareOperator.EQUAL,
                new ColumnValue(5));

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

    // Gabungkan dengan OR: kembalikan baris jika salah satu kondisi terpenuhi.
    var filter = new CompositeCondition(CompositeCondition.LogicOperator.OR);
    filter.AddCondition(filter1);
    filter.AddCondition(filter2);

    rowQueryCriteria.Filter = filter;

    // Ambil hanya col0 dan col1, lalu terapkan filter.
    rowQueryCriteria.AddColumnsToGet("col0");
    rowQueryCriteria.AddColumnsToGet("col1");

    var request = new GetRowRequest(rowQueryCriteria);

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

        // Proses data baris yang dikembalikan.
        // (Diabaikan di sini—lihat contoh GitHub untuk implementasi lengkap.)

        Console.WriteLine("Get row dengan filter berhasil.");
    }
    catch (Exception ex)
    {
        Console.WriteLine("Get row dengan filter gagal, exception:{0}", ex.Message);
    }

Baca beberapa baris data sekaligus

Panggil operasi BatchGetRow untuk membaca beberapa baris dari satu atau beberapa tabel dalam satu permintaan. Setiap baris diproses sebagai panggilan GetRow independen—Tablestore mengembalikan hasil terpisah untuk setiap baris.

Catatan penggunaan

• Beberapa baris dalam permintaan batch mungkin gagal secara individual. Kesalahan untuk baris-baris tersebut muncul dalam BatchGetRowResponse, bukan sebagai exception yang dilempar. Selalu periksa respons untuk memastikan setiap baris berhasil dibaca.

• Parameter yang sama berlaku untuk semua baris dalam permintaan. Misalnya, mengatur ColumnsToGet=[colA] hanya membaca colA dari setiap baris.

• Satu permintaan BatchGetRow dapat membaca maksimal 100 baris.

Operasi API

/// <summary>
/// Baca beberapa baris dari satu atau beberapa tabel dalam satu panggilan.
/// Setiap baris dibaca dan ditagih secara independen, tetapi batching mengurangi
/// overhead round-trip dibandingkan dengan beberapa panggilan GetRow.
/// </summary>
/// <param name="request">Instans permintaan</param>
/// <returns>Instans respons</returns>
public BatchGetRowResponse BatchGetRow(BatchGetRowRequest request);

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

Kode contoh

Contoh berikut membaca 10 baris dalam satu panggilan BatchGetRow:

// Bangun kunci utama untuk 10 baris.
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);

    var response = otsClient.BatchGetRow(request);
    var tableRows = response.RowDataGroupByTable;
    var rows = tableRows[TableName];

    // Periksa hasil setiap baris secara individual—beberapa baris mungkin gagal.
    // (Diabaikan di sini—lihat contoh GitHub untuk implementasi lengkap.)
}
catch (Exception ex)
{
    Console.WriteLine("Batch get row gagal, exception:{0}", ex.Message);
}

Untuk melihat kode contoh lengkap, kunjungi BatchGetRow@GitHub.

Baca data yang nilai kunci primernya berada dalam rentang tertentu

Panggil operasi GetRange untuk memindai baris-baris yang nilai kunci primernya berada dalam rentang tertentu. Pemindaian dapat dilakukan maju atau mundur, dan Anda dapat membatasi jumlah baris yang dikembalikan. Jika pemindaian mencapai batas (volume data, jumlah baris, atau throughput terpesan), pemindaian berhenti lebih awal dan mengembalikan nilai nextStartPrimaryKey. Gunakan nilai tersebut sebagai kunci awal dalam permintaan lanjutan untuk membaca baris-baris yang tersisa.

Catatan penggunaan

GetRange menggunakan prinsip pencocokan paling kiri: Tablestore membandingkan nilai kolom kunci utama dari kiri ke kanan. Ketika nilai baris untuk kolom kunci utama pertama (PK1) berada dalam rentang yang ditentukan, baris tersebut dikembalikan tanpa mengevaluasi kolom selanjutnya. Ketika PK1 berada di luar rentang, Tablestore melanjutkan evaluasi kolom yang tersisa dengan cara yang sama.

Operasi GetRange berhenti lebih awal ketika salah satu batas berikut tercapai:

• Data yang dipindai mencapai 4 MB.

• Jumlah baris yang dipindai mencapai 5.000.

• Jumlah baris yang dikembalikan mencapai limit yang ditentukan.

• Throughput baca terpesan habis sebelum baris berikutnya dapat dibaca.

Operasi API

/// <summary>
/// Baca baris-baris yang nilai kunci primernya berada dalam rentang yang ditentukan.
/// </summary>
/// <param name="request">Instans permintaan</param>
/// <returns>Instans respons</returns>
public GetRangeResponse GetRange(GetRangeRequest request);

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

Parameter

Kode contoh

Contoh berikut memindai semua baris dengan nilai kunci utama antara (0, INF_MIN) dan (100, INF_MAX), menangani paginasi secara otomatis:

// Tentukan rentang kunci: pk0 dari 0 (inklusif) hingga 100 (eksklusif).
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
{
    var request = new GetRangeRequest(TableName, GetRangeDirection.Forward,
                    inclusiveStartPrimaryKey, exclusiveEndPrimaryKey);

    var response = otsClient.GetRange(request);

    // Kumpulkan semua baris, lakukan paginasi hingga nextStartPrimaryKey null.
    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);
        }
    }

    // Proses semua baris yang dikumpulkan.
    // (Diabaikan di sini—lihat contoh GitHub untuk implementasi lengkap.)

    Console.WriteLine("Get range berhasil");
}
catch (Exception ex)
{
    Console.WriteLine("Get range gagal, exception:{0}", ex.Message);
}

Untuk melihat kode contoh lengkap, kunjungi GetRange@GitHub.

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

Panggil operasi GetRangeIterator untuk memindai rentang kunci utama menggunakan iterator. Berbeda dengan GetRange, iterator menangani paginasi secara otomatis—tidak perlu memeriksa nextStartPrimaryKey dan mengeluarkan permintaan lanjutan secara manual.

Operasi API

/// <summary>
/// Pindai baris-baris yang nilai kunci primernya berada dalam rentang yang ditentukan.
/// Mengembalikan iterator yang menghasilkan satu baris dalam satu waktu, menangani paginasi secara internal.
/// </summary>
/// <param name="request"><see cref="GetIteratorRequest"/></param>
/// <returns>Iterator dari <see cref="RowDataFromGetRange"/>.</returns>
public IEnumerable<RowDataFromGetRange> GetRangeIterator(GetIteratorRequest request);

Kode contoh

Contoh berikut membaca semua baris dengan nilai kunci utama antara (0, "a") dan (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"));

// Lacak unit kapasitas yang dikonsumsi selama iterasi.
var cu = new CapacityUnit(0, 0);

try
{
    // Filter didukung pada GetIteratorRequest.
    var request = new GetIteratorRequest(TableName, GetRangeDirection.Forward, inclusiveStartPrimaryKey,
                                                exclusiveEndPrimaryKey, cu);

    var iterator = otsClient.GetRangeIterator(request);
    foreach (var row in iterator)
    {
        // Proses setiap baris.
    }

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

Untuk melihat kode contoh lengkap, kunjungi GetRangeIterator@GitHub.