Tablestore：Membaca Data

Metode Kueri

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

Persyaratan Awal

• Instansi OTSClient harus diinisialisasi. Untuk detailnya, lihat Inisialisasi instansi OTSClient.

• Tabel data harus dibuat dan berisi data. Untuk detailnya, lihat Buat tabel data.

Membaca satu baris data

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

Operasi API

/**
 * Membaca baris data. 
 * @api
 * @param [] $request Parameter permintaan. 
 * @return [] Respons.  
 * @throws OTSClientException Pengecualian yang dilempar jika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi. 
 * @throws OTSServerException Pengecualian yang dilempar jika server Tablestore mengembalikan kesalahan. 
 */
public function getRow(array $request);            

Parameter Permintaan

Sintaksis Permintaan

$result = $client->getRow([
    'table_name' => '<string>',                     // Tentukan nama tabel. 
    'primary_key' => [                              // Tentukan informasi kunci primer. 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...   
    ],
    'column_filter' =>  <ColumnCondition>
]);            

Parameter Respons

Format Respons

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ],  
    'attribute_columns' => [
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
    ],
    'next_token' => '<string>'
]            

Kode Contoh

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ // Tentukan informasi kunci primer. 
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     // Atur parameter ini ke 1 untuk membaca data versi terbaru. 
    'columns_to_get' => ['Col0']             // Tentukan kolom yang ingin Anda baca. 
];
$response = $otsClient->getRow ($request);            

$request = [
    'table_name' => 'MyTable',
    'primary_key' => [ // Tentukan informasi kunci primer. 
        ['PK0', 123],
        ['PK1', 'abc']
    ],
    'max_versions' => 1,                     // Atur parameter ini ke 1 untuk membaca data versi terbaru. 
    'column_filter' => [                     // Konfigurasikan filter untuk mengembalikan baris yang nilainya pada kolom Col0 adalah 0. 
        'column_name' => 'Col0',
        'value' => 0,
        'comparator' => ComparatorTypeConst::CONST_EQUAL,
        'pass_if_missing' => false          // Jika baris tidak mengandung kolom Col0, baris tersebut tidak dikembalikan. 
    ]
];
$response = $otsClient->getRow ($request);            

Membaca beberapa baris data sekaligus

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

Setiap operasi GetRow dilakukan secara independen. Tablestore mengembalikan respons untuk setiap operasi GetRow secara terpisah.

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 menggunakan 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 BatchGetRow.

Operasi API

/**
 * Baca baris data yang ditentukan. 
 * Ketika Anda memanggil operasi BatchGetRow untuk membaca beberapa baris sekaligus, beberapa baris mungkin gagal dibaca. Jika ini terjadi, sistem tidak mengembalikan pengecualian tetapi mengembalikan informasi tentang baris yang gagal dalam $response. Untuk informasi lebih lanjut, lihat respons sampel untuk operasi BatchGetRow. 
 * @api
 * @param [] $request Parameter permintaan. 
 * @return [] Respons. 
 * @throws OTSClientException Pengecualian yang dikembalikan jika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi. 
 * @throws OTSServerException Pengecualian yang dikembalikan jika server Tablestore mengembalikan kesalahan. 
 */
public function batchGetRow(array $request);  
            

Parameter Permintaan

Sintaksis Permintaan

$result = $client->batchGetRow([
    'tables' => [                                            // Tentukan hierarki tabel. 
        [
            'table_name' => '<string>',                      // Tentukan nama tabel. 
            'primary_keys' => [                              // Tentukan informasi kunci primer. 
                [
                    ['<string>', <PrimaryKeyValue>], 
                    ['<string>', <PrimaryKeyValue>],
                    ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                ], 
                // Tentukan parameter lainnya. 
            ]
            'max_versions' => <integer>,
            'time_range' => [
                'start_time' => <integer>,
                'end_time' => <integer>,
                'specific_time' => <integer>
            ],
            'start_column' => '<string>',
            'end_column' => '<string>',
            'token' => '<string>',
            'columns_to_get' => [
                '<string>',
                '<string>',
                //...   
            ],
            'column_filter' =>  <ColumnCondition>
        ],
        // Tentukan tabel lainnya. 
    ]
]);            

Parameter Respons

Format Respons

[
    'tables' => [
        [
            'table_name' => '<string>',
            'rows' => [
                [
                    'is_ok' => true || false,
                    'error' => [
                        'code' => '<string>',
                        'message' => '<string>',
                    ]
                    'consumed' => [
                        'capacity_unit' => [
                            'read' => <integer>,
                            'write' => <integer>
                        ]
                    ],
                    'primary_key' => [ 
                        ['<string>', <PrimaryKeyValue>], 
                        ['<string>', <PrimaryKeyValue>],
                        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
                    ],  
                    'attribute_columns' => [
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                            ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ],
                    'next_token' => '<string>'
                ],
                // Baris lainnya. 
            ]
        ],
        // Tabel lainnya. 
    ]
]            

Kode Contoh

Contoh berikut menunjukkan cara membaca 30 baris data dari tiga tabel sekaligus (10 baris per tabel):

// Baca data dari tiga tabel. Sepuluh baris dibaca dari setiap tabel. 
$tables = array();
for($i = 0; $i < 3; $i++) {
    $primary_keys = array();
    for($j = 0; $j < 10; $j++) {
        $primary_keys[] = [
            ['pk0', $i],
            ['pk1', $j]
        ];
    }
    $tables[] = [
        'table_name' => 'SampleTable' . $i,
        'max_versions' => 1,
        'primary_keys' => $primary_keys
    ];
}
$request = [
    'tables' => $tables
];
$response = $otsClient->batchGetRow ($request);

// Proses data yang dikembalikan dari setiap tabel. 
foreach ($response['tables'] as $tableData) {
  print "Memproses tabel {$tableData['table_name']} ...\n";

  // Proses setiap baris data dalam tabel. 
  foreach ($tableData['rows'] as $rowData) {

    if ($rowData['is_ok']) {

      // Proses data yang dibaca. 
        $row = json_encode($rowData['primary_key']);
        print "Memproses baris: {$row}\n";

    } else {

      // Tangani kesalahan. 
      print "Kesalahan: {$rowData['error']['code']} {$rowData['error']['message']}\n";
    }
  }
}            

Tabel berikut menjelaskan contoh kode rinci:

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, pemindaian berhenti ketika batas tercapai, dan baris yang dibaca serta informasi kunci primer baris berikutnya dikembalikan. Anda dapat melanjutkan dari posisi terakhir menggunakan informasi tersebut.

Catatan Penggunaan

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

• 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 yang dicadangkan telah habis.

Operasi API

/**
 * Baca data yang nilai kunci primernya berada dalam rentang yang ditentukan oleh informasi kunci primer awal dan informasi kunci primer akhir. 
 * Server mungkin memotong rentang ini. Jika ini terjadi, Anda harus menentukan apakah akan memanggil operasi GetRange lagi berdasarkan nilai parameter next_start_primary_key yang dikembalikan dalam respons. 
 * Anda dapat menentukan jumlah maksimum baris yang ingin dibaca. 
 * Saat Anda menentukan informasi kunci primer awal dan informasi kunci primer akhir, Anda dapat menggunakan INF_MIN untuk menentukan nilai minimum dan menggunakan INF_MAX untuk menentukan nilai maksimum. Untuk informasi lebih lanjut, lihat kode contoh berikut. 
 * @api
 * @param [] $request Parameter permintaan. 
 * @return [] Respons. 
 * @throws OTSClientException Pengecualian yang dikembalikan jika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi. 
 * @throws OTSServerException Pengecualian yang dikembalikan jika server Tablestore mengembalikan kesalahan. 
 */
public function getRange(array $request);            

Parameter

Sintaksis Permintaan

$result = $client->getRange([
    'table_name' => '<string>',                                     // Tentukan nama tabel. 
    'inclusive_start_primary_key' => [                              // Tentukan informasi kunci primer awal. 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'exclusive_end_primary_key' => [                                // Tentukan informasi kunci primer akhir. 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'direction' => <Direction>,                                     // Tentukan urutan Anda ingin menyortir baris dalam respons. 
    'limit' => <Direction>,
    'max_versions' => <integer>,
    'time_range' => [
        'start_time' => <integer>,
        'end_time' => <integer>,
        'specific_time' => <integer>
    ],
    'start_column' => '<string>',
    'end_column' => '<string>',
    'token' => '<string>',
    'columns_to_get' => [
        '<string>',
        '<string>',
        //...   
    ],
    'column_filter' =>  <ColumnCondition>
]);      

Parameter Respons

Format Respons

[
    'consumed' => [
        'capacity_unit' => [
            'read' => <integer>,
            'write' => <integer>
        ]
    ],
    'next_start_primary_key' => [ 
        ['<string>', <PrimaryKeyValue>], 
        ['<string>', <PrimaryKeyValue>],
        ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
    ], 
    'rows' => [
        [
            'primary_key' => [ 
                ['<string>', <PrimaryKeyValue>], 
                ['<string>', <PrimaryKeyValue>],
                ['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
            ],  
            'attribute_columns' => [
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
                    ['<string>', <ColumnValue>, <ColumnType>, <integer>]
            ]
        ],
        // Baris lainnya. 
    ]
]
            

Kode Contoh

Contoh berikut menunjukkan cara membaca data dalam rentang tertentu:

// Kueri baris yang nilainya pada kolom PK0 berada dalam rentang [1, 4). 
// Anda harus menyediakan kolom kunci primer lengkap untuk menentukan rentang. Jika rentang kueri tidak melibatkan nilai kolom, atur nilai kolom ke nilai sangat besar (INF_MAX) atau nilai sangat kecil (INF_MIN). 
$startPK = [
    ['PK0', 1], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MIN]  // INF_MIN menunjukkan nilai yang sangat kecil. 
];
// Anda harus menyediakan kolom kunci primer lengkap untuk menentukan rentang. Jika rentang kueri tidak melibatkan nilai kolom, atur nilai kolom ke nilai sangat besar (INF_MAX) atau nilai sangat kecil (INF_MIN). 
$endPK = [
    ['PK0', 4], 
    ['PK1', null, PrimaryKeyTypeConst::CONST_INF_MAX]  // INF_MAX menunjukkan nilai yang sangat besar. 
];
$request = [
    'table_name' => 'SampleTable',
    'max_versions' => 1,                          // Atur parameter ini ke 1 untuk membaca versi terbaru. 
    'direction' => DirectionConst::CONST_FORWARD, // Kueri data ke arah maju. 
    'inclusive_start_primary_key' => $startPK,    // Tentukan informasi kunci primer awal. 
    'exclusive_end_primary_key' => $endPK,        // Tentukan informasi kunci primer akhir. 
    'limit' => 10                                 // Atur parameter ini ke 10 untuk menentukan bahwa maksimal 10 baris data dapat dikembalikan. 
];
$response = $otsClient->getRange ($request);
print "CU Baca Terpakai: {$response['consumed']['capacity_unit']['read']}\n";

foreach ($response['rows'] as $rowData) {
  // Proses setiap baris data. 
}           

Tabel berikut menjelaskan contoh kode rinci: