アトミックカウンターの使用 - Tablestore SDK for Python - Tablestore

Tablestore SDK for Python を使用して、行レベルで整数の属性列をアトミックにインクリメントまたはデクリメントします。

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化します。アトミックカウンターには、バージョン 5.1.0 以降が必要です。最新バージョンの使用を推奨します。

機能の説明

update_row を呼び出し、属性列の操作を INCREMENT に設定することで、整数の属性列をアトミックに変更します。正の値を指定すると列がインクリメントされ、負の値を指定するとデクリメントされます。

def update_row(
    self,
    table_name,
    row,
    condition,
    return_type=None,
    transaction_id=None,
)

次の例では、counter 属性列を 5 だけアトミックにインクリメントします。

primary_key = [("partition", "device"), ("id", 1)]
attribute_columns = {"INCREMENT": [("counter", 5)]}
row = Row(primary_key, attribute_columns)
condition = Condition(RowExistenceExpectation.EXPECT_EXIST)

consumed, return_row = client.update_row(
    "example_table",
    row,
    condition,
)
print("Write CU: %s" % consumed.write)

Tablestore SDK for Python の update_row メソッドは、アトミックカウンター操作後の値を直接返しません。新しい値を取得するには、更新後に get_row を呼び出します。

パラメーター

アトミックカウンター操作の主要なパラメーターは次のとおりです。

名前	タイプ	説明
table_name (必須)	`str`	テーブルの名前。
row (必須)	`Row`	更新する行のデータをカプセル化する `Row` オブジェクト。このオブジェクトは、ターゲット行のプライマリキーと、実行する更新操作を定義する属性列で構成されます。アトミックカウンター操作の場合、属性列は `{"INCREMENT": [("列名", 変更量)]}` の形式で指定します。
column_name (required)	`str`	The name of the attribute column on which to perform the atomic counter operation. Only integer attribute columns are supported.
value (required)	`int`	The amount by which to change the attribute column value. A positive value increments the column, and a negative value decrements it.
condition (必須)	`Condition`	更新の条件。詳細については、「条件付き更新の使用」をご参照ください。
transaction_id (任意)	`str`	ローカルトランザクションの ID。このパラメーターは、ローカルトランザクション内のアトミックカウンター操作にのみ指定します。

制限

整数属性列のみがサポートされています。対象の列が存在しない場合、その初期値は 0 として扱われます。列が存在するが整数ではない場合、サーバーは OTSParameterInvalid を返します。
変更量は正または負の値を取ることができますが、結果が符号付き 64 ビット整数の範囲を超えることはできません。そうでない場合、サーバーは OTSParameterInvalid を返します。
アトミックカウンター操作は最新バージョンにのみ適用され、指定されたデータバージョンはサポートされません。この更新により、新しいデータバージョンが書き込まれます。
1 回の更新で、同じ属性列に対してアトミックカウンター操作と、上書きや削除などの別の操作を同時に実行することはできません。

重要
アトミックカウンター操作は、ネットワークタイムアウトやシステムエラーが原因で失敗することがあります。直接リトライすると、変更が複数回適用されてしまい、カウントが不正確になる可能性があります。厳密な精度を確保するには、現在の値を読み取り、条件付き更新を使用して新しい値を書き込みます。