Tablestore memungkinkan Anda menulis satu baris data, memperbarui satu baris data, dan menulis beberapa baris data sekaligus dengan memanggil operasi yang berbeda. Untuk menulis data ke tabel, Anda harus menentukan informasi kunci utama lengkap serta kolom atribut yang ingin ditambahkan, dihapus, atau diperbarui. Untuk aplikasi dengan konkurensi tinggi, Anda dapat mengonfigurasi kondisi keberadaan baris atau kondisi kolom untuk memperbarui data berdasarkan kondisi tertentu.
Prasyarat
Instansi OTSClient telah diinisialisasi. Untuk informasi lebih lanjut, lihat Inisialisasi Instansi OTSClient.
Tabel data telah dibuat dan siap digunakan untuk penulisan data. Untuk informasi lebih lanjut, lihat Buat Tabel Data.
Tulis satu baris data
Operasi API
/**
* Tulis satu baris data. Jika baris ada, operasi PutRow akan menghapus semua versi data di semua kolom dari baris yang ada, lalu menulis data baru. Jumlah unit kapasitas (CUs) yang dikonsumsi oleh operasi ini dikembalikan.
* @api
* @param [] $request Parameter permintaan.
* @return [] Respons.
* @throws OTSClientException Pengecualian yang dilempar ketika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi.
* @throws OTSServerException Pengecualian yang dilempar ketika server Tablestore mengembalikan kesalahan.
*/
public function putRow(array $request); Informasi permintaan
Parameter permintaan
Parameter | Deskripsi |
table_name | Nama tabel data. |
condition | Kondisi yang ingin Anda tentukan untuk operasi PutRow. Anda dapat menentukan kondisi keberadaan baris atau kondisi berdasarkan nilai kolom. Untuk informasi lebih lanjut, lihat Lakukan pembaruan bersyarat.
|
primary_key | Informasi kunci utama tentang baris. Catatan
|
attribute_columns | Kolom atribut dari baris.
|
return_content | Konten yang ingin Anda kembalikan. return_type: Anda dapat menetapkan nilainya ke |
Sintaks permintaan
$result = $client->putRow([
'table_name' => '<string>', // Tentukan nama tabel data.
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // Tentukan kunci utama.
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => [ // Tentukan kolom atribut.
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'return_content' => [
'return_type' => <ReturnType>
]
]); Informasi respons
Parameter respons
Parameter | Deskripsi |
consumed | Jumlah CUs yang dikonsumsi oleh operasi. capacity_unit: jumlah CUs baca/tulis yang dikonsumsi. Parameter:
|
primary_key | Nilai kunci utama, yang konsisten dengan yang ditentukan dalam permintaan. Catatan Jika Anda menetapkan return_type ke ReturnTypeConst::CONST_PK, nilai kunci utama dikembalikan. Parameter ini digunakan oleh fitur kolom kunci utama auto-increment. |
attribute_columns | Nilai kolom atribut, yang konsisten dengan yang ditentukan dalam permintaan. Saat ini, nilai parameter ini kosong. |
Sintaks respons
[
'consumed' => [
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'primary_key' => [
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => []
] Contoh
Gunakan nomor versi data yang dihasilkan secara otomatis oleh Tablestore saat Anda menulis satu baris data
Kode sampel berikut menunjukkan cara menulis satu baris yang berisi 10 kolom atribut, masing-masing menyimpan data hanya satu versi. Dalam contoh ini, nomor versi data dihasilkan secara otomatis oleh Tablestore.
$attr = array();
for($i = 0; $i < 10; $i++) {
$attr[] = ['Col'. $i, $i];
}
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_IGNORE, // Anda dapat menetapkan condition ke IGNORE, EXPECT_EXIST, atau EXPECT_NOT_EXIST.
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request); Tentukan nomor versi data kustom saat Anda menulis satu baris data
Kode sampel berikut menunjukkan cara menulis satu baris yang berisi 10 kolom atribut, masing-masing menyimpan data tiga versi. Dalam contoh ini, nomor versi data kustom ditentukan.
$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
for($j = 0; $j < 3; $j++) {
$attr[] = ['Col'. $i, $j, null, $timestamp+$j];
}
}
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_IGNORE, // Anda dapat menetapkan condition ke IGNORE, EXPECT_EXIST, atau EXPECT_NOT_EXIST.
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request); Tentukan kondisi keberadaan baris saat Anda menulis satu baris data
Kode sampel berikut menunjukkan cara menulis satu baris yang berisi 10 kolom atribut, masing-masing menyimpan data tiga versi, ketika baris yang ditentukan tidak ada. Dalam contoh ini, nomor versi data kustom ditentukan.
$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
for($j = 0; $j < 3; $j++) {
$attr[] = ['Col'. $i, $j, null, $timestamp+$j];
}
}
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_EXPECT_NOT_EXIST, // Konfigurasikan parameter kondisi untuk menulis data ketika baris yang ditentukan tidak ada.
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request); Tentukan kondisi berbasis kolom dan kondisi keberadaan baris saat Anda menulis satu baris data
Kode sampel berikut menunjukkan cara menulis satu baris yang berisi 10 kolom atribut, masing-masing menyimpan data tiga versi, ketika baris yang ditentukan ada dan nilai kolom Col0 lebih besar dari 100. Dalam contoh ini, nomor versi data kustom ditentukan.
$attr = array();
$timestamp = getMicroTime();
for($i = 0; $i < 10; $i++) {
for($j = 0; $j < 3; $j++) {
$attr[] = ['Col'. $i, $j, null, $timestamp+$j];
}
}
$request = [
'table_name' => 'MyTable',
'condition' => [
'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, // Konfigurasikan parameter kondisi untuk menulis data ketika baris yang ditentukan ada.
'column_condition' => [ // Jika kondisi terpenuhi, data diperbarui.
'column_name' => 'Col0',
'value' => 100,
'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
]
,
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request); Perbarui satu baris data
Operasi API
/**
* Perbarui satu baris data.
* @api
* @param [] $request Parameter permintaan.
* @return [] Respons.
* @throws OTSClientException Pengecualian yang dilempar ketika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi.
* @throws OTSServerException Pengecualian yang dilempar ketika server Tablestore mengembalikan kesalahan.
*/
public function updateRow(array $request); Informasi permintaan
Parameter permintaan
Parameter | Deskripsi |
table_name | Nama tabel data. |
condition | Kondisi yang ingin Anda tentukan untuk operasi UpdateRow. Anda dapat menentukan kondisi keberadaan baris atau kondisi berdasarkan nilai kolom. Untuk informasi lebih lanjut, lihat Lakukan pembaruan bersyarat. |
primary_key | Informasi kunci utama tentang baris. Catatan Jumlah dan tipe kolom kunci utama yang Anda tentukan harus sama dengan jumlah dan tipe sebenarnya dari kolom kunci utama dalam tabel data. |
update_of_attribute_columns | Kolom atribut yang ingin Anda perbarui. |
return_content | Konten yang ingin Anda kembalikan. return_type: Anda dapat menetapkan nilainya hanya ke ReturnTypeConst::CONST_PK untuk mengembalikan kunci utama baris. Parameter ini digunakan oleh fitur kolom kunci utama auto-increment. |
Sintaks permintaan
$result = $client->updateRow([
'table_name' => '<string>', // Tentukan nama tabel data.
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // Tentukan kunci utama.
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'update_of_attribute_columns' => [ // Tentukan kolom atribut yang ingin Anda perbarui.
'PUT' => [
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'DELETE' => [
['<string>', <integer>],
['<string>', <integer>],
['<string>', <integer>],
['<string>', <integer>]
],
'DELETE_ALL' => [
'<string>',
'<string>',
'<string>',
'<string>'
],
],
'return_content' => [
'return_type' => <ReturnType>
]
]); Informasi respons
Parameter respons
Parameter | Deskripsi |
consumed | Jumlah CUs yang dikonsumsi oleh operasi. capacity_unit: jumlah CUs baca/tulis yang dikonsumsi. Parameter:
|
primary_key | Nilai kunci utama, yang konsisten dengan yang ditentukan dalam permintaan. Catatan Jika Anda menetapkan return_type ke ReturnTypeConst::CONST_PK, nilai kunci utama dikembalikan. Parameter ini digunakan oleh fitur kolom kunci utama auto-increment. |
attribute_columns | Nilai kolom atribut, yang konsisten dengan yang ditentukan dalam permintaan. Saat ini, nilai parameter ini kosong. |
Sintaks respons
[
'consumed' => [
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'primary_key' => [
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => []
] Contoh
Perbarui satu baris data tanpa menentukan kondisi
Kode sampel berikut menunjukkan cara memperbarui beberapa kolom dari satu baris, menghapus versi tertentu dari data dari satu kolom, dan menghapus satu kolom.
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_IGNORE,
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'update_of_attribute_columns' => [
'PUT' => [ // Perbarui beberapa kolom.
['Col0', 100],
['Col1', 'Halo'],
['Col2', 'biner', ColumnTypeConst::CONST_BINARY],
['Col3', 100, null, 1526418378526]
],
'DELETE' => [ // Hapus versi tertentu dari data dari satu kolom.
['Col10', 1526418378526]
],
'DELETE_ALL' => [
'Col11' // Hapus satu kolom.
]
]
];
$response = $otsClient->updateRow($request); Tentukan kondisi berbasis kolom dan kondisi keberadaan baris saat Anda memperbarui satu baris data
Kode sampel berikut menunjukkan cara memperbarui satu baris data ketika baris yang ditentukan ada dan nilai kolom Col0 lebih besar dari 100.
$request = [
'table_name' => 'MyTable',
'primary_key' => [ // Tentukan kunci utama.
['PK0', 123],
['PK1', 'abc']
],
'condition' => [
'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, // Konfigurasikan parameter kondisi untuk memperbarui baris ketika baris yang ditentukan ada.
'column_filter' => [ // Perbarui baris ketika nilai kolom Col0 lebih besar dari 100.
'column_name' => 'Col0',
'value' => 100,
'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
]
],
'update_of_attribute_columns' => [
'PUT' => [ // Perbarui beberapa kolom.
['Col0', 100],
['Col1', 'Halo'],
['Col2', 'biner', ColumnTypeConst::CONST_BINARY],
['Col3', 100, null, 1526418378526]
],
'DELETE' => [ // Hapus versi tertentu dari data dari satu kolom.
['Col10', 1526418378526]
],
'DELETE_ALL' => [
'Col11' // Hapus satu kolom.
]
]
]; Tulis beberapa baris data sekaligus
Catatan penggunaan
Ketika Anda memanggil operasi BatchWriteRow untuk menulis beberapa baris data sekaligus, beberapa baris mungkin gagal ditulis. Dalam kasus ini, Tablestore tidak mengembalikan pengecualian. Sebagai gantinya, Tablestore mengembalikan BatchWriteRowResponse yang mencakup indeks dan pesan kesalahan dari baris yang gagal. Oleh karena itu, saat menggunakan operasi BatchWriteRow, Anda harus memeriksa nilai kembali untuk memastikan bahwa semua baris berhasil ditulis. Jika tidak, baris yang gagal mungkin terlewatkan.
Operasi API
/**
* Tulis, perbarui, atau hapus baris data yang ditentukan.
* Ketika Anda memanggil operasi BatchWriteRow untuk menulis beberapa baris data sekaligus, beberapa baris mungkin gagal ditulis. Dalam kasus ini, Tablestore tidak mengembalikan pengecualian. Tablestore mengembalikan informasi tentang baris yang gagal dalam $response. Untuk informasi lebih lanjut, lihat contoh respons terhadap operasi BatchWriteRow.
* @api
* @param [] $request Parameter permintaan.
* @return [] Respons.
* @throws OTSClientException Pengecualian yang dilempar ketika terjadi kesalahan parameter atau server Tablestore mengembalikan kesalahan verifikasi.
* @throws OTSServerException Pengecualian yang dilempar ketika server Tablestore mengembalikan kesalahan.
*/
public function batchWriteRow(array $request); Informasi permintaan
Parameter permintaan
Operasi BatchWriteRow terdiri dari beberapa operasi PutRow, UpdateRow, dan DeleteRow.
Hierarki dibuat untuk tabel. Beberapa tabel dapat diproses sekaligus.
Anda dapat mengonfigurasi parameter tables untuk menentukan informasi tentang tabel dan baris yang akan dilakukan operasi tulis, pembaruan, atau penghapusan.
Parameter operation_type ditambahkan untuk membedakan antara tipe operasi yang berbeda.
Nilai valid operation_type adalah OperationTypeConst::CONST_PUT, OperationTypeConst::CONST_UPDATE, dan OperationTypeConst::CONST_DELETE.
Jika tipe operasi adalah PUT, parameter primary_key dan attribute_columns berlaku.
Jika tipe operasi adalah UPDATE, parameter primary_key dan update_of_attribute_columns berlaku.
Jika tipe operasi adalah DELETE, parameter primary_key berlaku.
Sintaks permintaan
$result = $client->batchWriteRow([
'tables' => [ // Tentukan hierarki tabel.
[
'table_name' => '<string>', // Tentukan nama tabel data.
'operation_type' => <OperationType>,
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // Tentukan kunci utama.
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => [ // Parameter ini diperlukan ketika tipe operasi adalah PUT.
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'update_of_attribute_columns' => [ // Parameter ini diperlukan ketika tipe operasi adalah UPDATE.
'PUT' => [
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'DELETE' => [
['<string>', <integer>],
['<string>', <integer>],
['<string>', <integer>],
['<string>', <integer>]
],
'DELETE_ALL' => [
'<string>',
'<string>',
'<string>',
'<string>'
],
],
'return_content' => [
'return_type' => <ReturnType>
]
],
// Tabel lainnya.
]
]); Informasi respons
Parameter respons
Setiap tabel yang ditunjukkan oleh parameter tables dalam respons sesuai dengan setiap tabel yang ditentukan dalam permintaan. Tabel berikut menjelaskan parameter dalam respons.
Parameter | Deskripsi |
table_name | Nama tabel data. |
is_ok | Menunjukkan apakah operasi pada baris berhasil.
|
error | Informasi kesalahan dalam respons jika operasi pada baris gagal. Parameter:
|
consumed | Jumlah CUs yang dikonsumsi oleh operasi ini. capacity_unit: jumlah CUs baca/tulis yang dikonsumsi. Parameter:
|
primary_key | Nilai kunci utama, yang konsisten dengan yang ditentukan dalam permintaan. Jika nilai ditentukan untuk return_type, nilai parameter ini ada. Parameter ini digunakan untuk fitur kolom kunci utama auto-increment. |
attribute_columns | Nilai kolom atribut, yang konsisten dengan yang ditentukan dalam permintaan. Saat ini, nilai parameter ini kosong. |
Sintaks 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' => []
],
// Baris lainnya.
]
],
// Tabel lainnya.
]
] Contoh
Kode sampel berikut menunjukkan cara menulis 30 baris data ke tiga tabel sekaligus. Sepuluh baris ditulis ke setiap tabel.
// Tulis data ke tiga tabel. Sepuluh baris ditulis ke setiap tabel.
$tables = array();
for($i = 0; $i < 3; $i++) {
$rows = array();
for($j = 0; $j < 10; $j++) {
$rows[] = [
'operation_type' => OperationTypeConst::CONST_PUT, // Tetapkan tipe operasi ke PUT.
'condition' => RowExistenceExpectationConst::CONST_IGNORE,
'primary_key' => [
['pk0', $i],
['pk1', $j]
],
'attribute_columns' => [
['Col0', 4],
['Col2', 'Beijing']
]
];
}
$tables[] = [
'table_name' => 'SampleTable' . $i,
'rows' => $rows
];
}
$request = [
'tables' => $tables
];
$response = $otsClient->batchWriteRow ($request);
// Proses setiap tabel yang dikembalikan.
foreach ($response['tables'] as $tableData) {
print "Memproses tabel {$tableData['table_name']} ...\n";
// Proses hasil yang dikembalikan oleh operasi PutRow pada tabel.
$putRows = $tableData['rows'];
foreach ($putRows as $rowData) {
if ($rowData['is_ok']) {
// Data berhasil ditulis.
print "Unit Kapasitas Dikonsumsi: {$rowData['consumed']['capacity_unit']['write']}\n";
} else {
// Tangani kesalahan.
print "Kesalahan: {$rowData['error']['code']} {$rowData['error']['message']}\n";
}
}
} Tabel berikut menjelaskan contoh kode sampel terperinci.
Contoh | Deskripsi |
Menunjukkan cara melakukan beberapa operasi PUT dalam BatchWriteRow. | |
Menunjukkan cara melakukan beberapa operasi UPDATE dalam BatchWriteRow. | |
Menunjukkan cara melakukan beberapa operasi DELETE dalam BatchWriteRow. | |
Menunjukkan cara melakukan operasi UPDATE, PUT, dan DELETE dalam BatchWriteRow. | |
Menunjukkan cara menggunakan BatchWriteRow bersama dengan pembaruan bersyarat. |
Pertanyaan Umum
Referensi
Untuk memperbarui data dalam aplikasi dengan konkurensi tinggi berdasarkan kondisi tertentu, Anda dapat menggunakan fitur pembaruan bersyarat. Untuk informasi lebih lanjut, lihat Lakukan Pembaruan Bersyarat.
Untuk mengumpulkan statistik waktu nyata tentang aplikasi online, seperti jumlah page views (PV) pada berbagai topik, Anda dapat menggunakan fitur penghitung atomik. Untuk informasi lebih lanjut, lihat Gunakan Fitur Penghitung Atomik.
Untuk melakukan operasi atomik untuk menulis satu atau lebih baris data, Anda dapat menggunakan fitur transaksi lokal. Untuk informasi lebih lanjut, lihat Konfigurasikan Transaksi Lokal.
Setelah Anda menulis data ke tabel, Anda dapat membaca atau menghapus data dalam tabel berdasarkan kebutuhan bisnis Anda. Untuk informasi lebih lanjut, lihat Baca Data dan Hapus Data.