Tablestore では、異なる操作を呼び出すことで、単一のデータ行の書き込み、単一のデータ行の更新、複数データ行の一括書き込みを行うことができます。データテーブルにデータを書き込むには、完全なプライマリキー情報と、追加、削除、または変更する属性列を指定する必要があります。高並列アプリケーションにデータを書き込むには、行存在条件または列条件を設定して、指定された条件に基づいてデータを更新できます。
前提条件
OTSClient インスタンスが初期化されていること。詳細については、「OTSClient インスタンスの初期化」をご参照ください。
データテーブルが作成され、データがデータテーブルに書き込まれていること。詳細については、「データテーブルの作成」をご参照ください。
単一のデータ行の書き込み
API 操作
/**
* 単一のデータ行を書き込みます。行が存在する場合、PutRow 操作は既存の行のすべての列からすべてのバージョンのデータを削除し、新しいデータを書き込みます。操作で消費される容量ユニット (CU) の数が返されます。
* @api
* @param [] $request リクエストパラメータ。
* @return [] レスポンス。
* @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合にスローされる例外。
* @throws OTSServerException Tablestore サーバーがエラーを返した場合にスローされる例外。
*/
public function putRow(array $request);
リクエスト情報
リクエストパラメータ
パラメータ | 説明 |
table_name | データテーブルの名前。 |
condition | PutRow 操作に指定する条件。行存在条件または列値に基づく条件を指定できます。詳細については、「条件付き更新の実行」をご参照ください。
|
primary_key | 行に関するプライマリキー情報。 説明
|
attribute_columns | 行の属性列。
|
return_content | 返すコンテンツ。 return_type: 値を |
リクエスト構文
$result = $client->putRow([
'table_name' => '<string>', // データテーブルの名前を指定します。
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // プライマリキーを指定します。
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => [ // 属性列を指定します。
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'return_content' => [
'return_type' => <ReturnType>
]
]);
レスポンス情報
レスポンスパラメータ
パラメータ | 説明 |
consumed | 操作で消費される CU の数。 capacity_unit: 消費される読み取り/書き込み CU の数。パラメータ:
|
primary_key | プライマリキーの値。リクエストで指定された値と一致します。 説明 return_type を ReturnTypeConst::CONST_PK に設定すると、プライマリキーの値が返されます。このパラメータは、自動インクリメントプライマリキー列機能で使用されます。 |
attribute_columns | 属性列の値。リクエストで指定された値と一致します。現在、このパラメータの値は空です。 |
レスポンス構文
[
'consumed' => [
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'primary_key' => [
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => []
]
例
データ行を書き込むときに、Tablestore によって自動的に生成されるデータバージョン番号を使用する
次のサンプルコードは、それぞれが 1 つのバージョンのデータのみを格納する 10 個の属性列を含む行を書き込む方法を示しています。この例では、データバージョン番号は Tablestore によって自動的に生成されます。
$attr = array();
for($i = 0; $i < 10; $i++) {
$attr[] = ['Col'. $i, $i];
}
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_IGNORE, // condition は IGNORE、EXPECT_EXIST、または EXPECT_NOT_EXIST に設定できます。
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);
データ行を書き込むときに、カスタムデータバージョン番号を指定する
次のサンプルコードは、それぞれが 3 つのバージョンのデータを格納する 10 個の属性列を含む行を書き込む方法を示しています。この例では、カスタムデータバージョン番号が指定されています。
$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, // condition は IGNORE、EXPECT_EXIST、または EXPECT_NOT_EXIST に設定できます。
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);
データ行を書き込むときに、行存在条件を指定する
次のサンプルコードは、指定された行が存在しない場合に、それぞれが 3 つのバージョンのデータを格納する 10 個の属性列を含む行を書き込む方法を示しています。この例では、カスタムデータバージョン番号が指定されています。
$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, // 指定された行が存在しない場合にデータを書き込むように condition パラメータを設定します。
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);
データ行を書き込むときに、列に基づく条件と行存在条件を指定する
次のサンプルコードは、指定された行が存在し、Col0 列の値が 100 より大きい場合に、それぞれが 3 つのバージョンのデータを格納する 10 個の属性列を含む行を書き込む方法を示しています。この例では、カスタムデータバージョン番号が指定されています。
$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, // 指定された行が存在する場合にデータを書き込むように condition パラメータを設定します。
'column_condition' => [ // 条件が満たされた場合、データが更新されます。
'column_name' => 'Col0',
'value' => 100,
'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
]
,
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'attribute_columns' => $attr
];
$response = $otsClient->putRow ($request);
単一のデータ行の更新
API 操作
/**
* 単一のデータ行を更新します。
* @api
* @param [] $request リクエストパラメータ。
* @return [] レスポンス。
* @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合にスローされる例外。
* @throws OTSServerException Tablestore サーバーがエラーを返した場合にスローされる例外。
*/
public function updateRow(array $request);
リクエスト情報
リクエストパラメータ
パラメータ | 説明 |
table_name | データテーブルの名前。 |
condition | UpdateRow 操作に指定する条件。行存在条件または列値に基づく条件を指定できます。詳細については、「条件付き更新の実行」をご参照ください。 |
primary_key | 行に関するプライマリキー情報。 説明 指定するプライマリキー列の数とタイプは、データテーブル内のプライマリキー列の実際の数とタイプと同じである必要があります。 |
update_of_attribute_columns | 更新する属性列。 |
return_content | 返すコンテンツ。 return_type: 値を ReturnTypeConst::CONST_PK にのみ設定して、行のプライマリキーを返すことができます。このパラメータは、自動インクリメントプライマリキー列機能で使用されます。 |
リクエスト構文
$result = $client->updateRow([
'table_name' => '<string>', // データテーブルの名前を指定します。
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // プライマリキーを指定します。
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'update_of_attribute_columns' => [ // 更新する属性列を指定します。
'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>
]
]);
レスポンス情報
レスポンスパラメータ
パラメータ | 説明 |
consumed | 操作で消費される CU の数。 capacity_unit: 消費される読み取り/書き込み CU の数。パラメータ:
|
primary_key | プライマリキーの値。リクエストで指定された値と一致します。 説明 return_type を ReturnTypeConst::CONST_PK に設定すると、プライマリキーの値が返されます。このパラメータは、自動インクリメントプライマリキー列機能で使用されます。 |
attribute_columns | 属性列の値。リクエストで指定された値と一致します。現在、このパラメータの値は空です。 |
レスポンス構文
[
'consumed' => [
'capacity_unit' => [
'read' => <integer>,
'write' => <integer>
]
],
'primary_key' => [
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => []
]
例
条件を指定せずにデータ行を更新する
次のサンプルコードは、行の複数の列を更新し、列から特定のバージョンのデータを削除し、列を削除する方法を示しています。
$request = [
'table_name' => 'MyTable',
'condition' => RowExistenceExpectationConst::CONST_IGNORE,
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'update_of_attribute_columns' => [
'PUT' => [ // 複数の列を更新します。
['Col0', 100],
['Col1', 'Hello'],
['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
['Col3', 100, null, 1526418378526]
],
'DELETE' => [ // 列から特定のバージョンのデータを削除します。
['Col10', 1526418378526]
],
'DELETE_ALL' => [
'Col11' // 列を削除します。
]
]
];
$response = $otsClient->updateRow($request);
データ行を更新するときに、列に基づく条件と行存在条件を指定する
次のサンプルコードは、指定された行が存在し、Col0 列の値が 100 より大きい場合に、データ行を更新する方法を示しています。
$request = [
'table_name' => 'MyTable',
'primary_key' => [ // プライマリキーを指定します。
['PK0', 123],
['PK1', 'abc']
],
'condition' => [
'row_existence' => RowExistenceExpectationConst::CONST_EXPECT_EXIST, // 指定された行が存在する場合に、行を更新するように condition パラメータを設定します。
'column_filter' => [ // Col0 列の値が 100 より大きい場合に、行を更新します。
'column_name' => 'Col0',
'value' => 100,
'comparator' => ComparatorTypeConst::CONST_GREATER_THAN
]
],
'update_of_attribute_columns' => [
'PUT' => [ // 複数の列を更新します。
['Col0', 100],
['Col1', 'Hello'],
['Col2', 'a binary', ColumnTypeConst::CONST_BINARY],
['Col3', 100, null, 1526418378526]
],
'DELETE' => [ // 列から特定のバージョンのデータを削除します。
['Col10', 1526418378526]
],
'DELETE_ALL' => [
'Col11' // 列を削除します。
]
]
];
複数データ行の一括書き込み
使用上の注意
BatchWriteRow 操作を呼び出して複数データ行を一度に書き込むと、一部の行の書き込みに失敗することがあります。この場合、Tablestore は例外を返しません。Tablestore は、失敗した行のインデックスとエラーメッセージを含む BatchWriteRowResponse を返します。したがって、BatchWriteRow 操作を呼び出すときは、戻り値をチェックして、すべての行が書き込まれたかどうかを確認する必要があります。戻り値をチェックしないと、書き込みに失敗した行が無視される可能性があります。
API 操作
/**
* 指定されたデータ行を書き込み、更新、または削除します。
* BatchWriteRow 操作を呼び出して複数データ行を一度に書き込むと、一部の行の書き込みに失敗することがあります。この場合、Tablestore は例外を返しません。Tablestore は、失敗した行に関する情報を $response で返します。詳細については、BatchWriteRow 操作へのサンプルレスポンスをご参照ください。
* @api
* @param [] $request リクエストパラメータ。
* @return [] レスポンス。
* @throws OTSClientException パラメータエラーが発生した場合、または Tablestore サーバーが検証エラーを返した場合にスローされる例外。
* @throws OTSServerException Tablestore サーバーがエラーを返した場合にスローされる例外。
*/
public function batchWriteRow(array $request);
リクエスト情報
リクエストパラメータ
BatchWriteRow 操作は、複数の PutRow、UpdateRow、および DeleteRow 操作で構成されます。
テーブルの階層が作成されます。一度に複数のテーブルを処理できます。
tables パラメータを設定して、書き込み、更新、または削除操作を実行するテーブルと行に関する情報を指定できます。
operation_type パラメータが追加され、異なる操作タイプが区別されます。
operation_type の有効な値は、OperationTypeConst::CONST_PUT、OperationTypeConst::CONST_UPDATE、OperationTypeConst::CONST_DELETE です。
操作タイプが PUT の場合、primary_key パラメータと attribute_columns パラメータが有効になります。
操作タイプが UPDATE の場合、primary_key パラメータと update_of_attribute_columns パラメータが有効になります。
操作タイプが DELETE の場合、primary_key パラメータが有効になります。
リクエスト構文
$result = $client->batchWriteRow([
'tables' => [ // テーブルの階層を指定します。
[
'table_name' => '<string>', // データテーブルの名前を指定します。
'operation_type' => <OperationType>,
'condition' => [
'row_existence' => <RowExistence>,
'column_condition' => <ColumnCondition>
],
'primary_key' => [ // プライマリキーを指定します。
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>],
['<string>', <PrimaryKeyValue>, <PrimaryKeyType>]
],
'attribute_columns' => [ // 操作タイプが PUT の場合、このパラメータは必須です。
['<string>', <ColumnValue>],
['<string>', <ColumnValue>, <ColumnType>],
['<string>', <ColumnValue>, <ColumnType>, <integer>]
],
'update_of_attribute_columns' => [ // 操作タイプが 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>
]
],
// その他のテーブル。
]
]);
レスポンス情報
レスポンスパラメータ
レスポンスの tables パラメータで示される各テーブルは、リクエストで指定された各テーブルに対応しています。次の表に、レスポンスのパラメータを示します。
パラメータ | 説明 |
table_name | データテーブルの名前。 |
is_ok | 行に対する操作が成功したかどうかを示します。
|
error | 行に対する操作が失敗した場合のレスポンスのエラー情報。パラメータ:
|
consumed | この操作で消費される CU の数。 capacity_unit: 消費される読み取り/書き込み CU の数。パラメータ:
|
primary_key | プライマリキーの値。リクエストで指定された値と一致します。 return_type に値が指定されている場合、このパラメータの値が存在します。このパラメータは、自動インクリメントプライマリキー列機能で使用されます。 |
attribute_columns | 属性列の値。リクエストで指定された値と一致します。現在、このパラメータの値は空です。 |
レスポンス構文
[
'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' => []
],
// その他の行。
]
],
// その他のテーブル。
]
]
例
次のサンプルコードは、一度に 3 つのテーブルに 30 行のデータを書き込む方法を示しています。各テーブルに 10 行が書き込まれます。
// 3 つのテーブルにデータを書き込みます。各テーブルに 10 行が書き込まれます。
$tables = array();
for($i = 0; $i < 3; $i++) {
$rows = array();
for($j = 0; $j < 10; $j++) {
$rows[] = [
'operation_type' => OperationTypeConst::CONST_PUT, // 操作タイプを 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);
// 返された各テーブルを処理します。
foreach ($response['tables'] as $tableData) {
print "Handling table {$tableData['table_name']} ...\n";
// テーブルに対する PutRow 操作によって返された結果を処理します。
$putRows = $tableData['rows'];
foreach ($putRows as $rowData) {
if ($rowData['is_ok']) {
// データが書き込まれます。
print "Capacity Unit Consumed: {$rowData['consumed']['capacity_unit']['write']}\n";
} else {
// エラーを処理します。
print "Error: {$rowData['error']['code']} {$rowData['error']['message']}\n";
}
}
}
次の表に、詳細なサンプルコードの例を示します。
例 | 説明 |
BatchWriteRow で複数の PUT 操作を実行する方法を示します。 | |
BatchWriteRow で複数の UPDATE 操作を実行する方法を示します。 | |
BatchWriteRow で複数の DELETE 操作を実行する方法を示します。 | |
BatchWriteRow で UPDATE、PUT、および DELETE 操作を実行する方法を示します。 | |
BatchWriteRow を条件付き更新とともに使用する方法を示します。 |
FAQ
関連情報
指定された条件に基づいて高並列アプリケーションのデータを更新するには、条件付き更新機能を使用できます。詳細については、「条件付き更新の実行」をご参照ください。
さまざまなトピックのページビュー (PV) 数など、オンラインアプリケーションに関するリアルタイム統計を収集するには、アトミックカウンタ機能を使用できます。詳細については、「アトミックカウンタ機能の使用」をご参照ください。
1 つ以上のデータ行を書き込むためのアトミック操作を実行するには、ローカルトランザクション機能を使用できます。詳細については、「ローカルトランザクションの設定」をご参照ください。
テーブルにデータを書き込んだ後、ビジネス要件に基づいてテーブル内のデータを読み取ったり削除したりできます。詳細については、「データの読み取り」および「データの削除」をご参照ください。