全部產品
Search
文件中心

Tablestore:原子計數器

更新時間:Jun 30, 2024

如果要在某些線上應用中快速進行計數操作,您可以使用原子計數器實現。使用原子計數器時,您需要將表中的某一列當成一個原子計數器,然後對該列進行原子計數操作。

前提條件

  • 已初始化Client,詳情請參見初始化OTSClient

  • 已建立資料表並寫入資料。

注意事項

  • 只支援對整型列的列值進行原子計數操作。

  • 作為原子計數器的列,如果寫入資料前該列不存在,則預設值為0;如果寫入資料前該列已存在且列值非整型,則產生OTSParameterInvalid錯誤。

  • 增量值可以是正數或負數,但不能出現計算溢出。如果出現計算溢出,則產生OTSParameterInvalid錯誤。

  • 預設不返回進行原子計數操作的列值,您可以通過相應操作指定返回進行原子計數操作的列值。

  • 在單次更新要求中,不能對某一列同時進行更新和原子計數操作。假設列A已經執行原子計數操作,則列A不能再執行其他動作(例如列的覆蓋寫,列刪除等)。

  • 在一次BatchWriteRow請求中,支援對同一行資料進行多次更新操作。但是如果某一行已進行原子計數操作,則該行在此批量請求中只能出現一次。

  • 原子計數操作只能作用在列值的最新版本,不支援對列值的特定版本做原子計數操作。更新完成後,原子計數操作會插入一個新的資料版本。

介面

/**
 * 更新一行資料。
 * @api
 * @param [] $request 請求參數。
 * @return [] 請求返回。
 * @throws OTSClientException 當參數檢查出錯或服務端返回校正出錯時拋出異常。
 * @throws OTSServerException 當OTS服務端返回錯誤時拋出異常。
 */
public function updateRow(array $request);         

updateRow介面中新增了原子計數器的操作介面,操作說明請參見下表。

操作

說明

update_of_attribute_columns

更新類型為INCREMENT,對列執行增量變更,例如+X,-X等。配置格式如下:

'update_of_attribute_columns'=> array(
    'INCREMENT' => array (     
        array('<column_name>', <value>, ColumnTypeConst::CONST_INTEGER), 
    ),
)

return_content

返回進行增量變更後的列值。您需要設定進行增量變更的列名以及設定傳回型別為ReturnTypeConst::CONST_AFTER_MODIFY。配置格式如下:

'return_content' => array(
    'return_type' => ReturnTypeConst::CONST_AFTER_MODIFY,
    'return_column_names' => array('<column_name>')
 )

參數

參數

說明

table_name

資料表名稱。

column_name

進行原子計數操作的列名。只支援對整型列的列值進行原子計數器操作。

value

對列進行增量變更的值。

return_content

返回進行原子計數操作的列資訊。包含return_type和return_column_names配置。

  • return_type:設定此參數為ReturnTypeConst::CONST_AFTER_MODIFY,返回進行原子計數操作的列的新值。

  • return_column_names:對於進行原子計數操作的列,返回列值的列名。

樣本

以下樣本用於在寫入資料時對整型列做列值的增量變更,然後讀取更新後的新值。

$request = array (
    //設定資料表名稱。
    'table_name' => 'MyTable',
    //設定行存在性條件為RowExistenceExpectationConst::CONST_IGNORE,表示忽略行是否存在,不做任何行存在性檢查。
    'condition' => RowExistenceExpectationConst::CONST_IGNORE,
    //設定主索引值。設定的主鍵個數和類型必須與資料表的主鍵個數和類型一致。
    'primary_key' => array ( 
        //第一列主鍵名為PK0,類型為整型,列值為123。
        array('PK0', 123),
        //第二列主鍵名為PK1,類型為字串,列值為'inc'。
        array('PK1', 'inc')
    ),
    //更新的屬性列。支援設定PUT、DELETE和DELETE_ALL三種操作類型。
    'update_of_attribute_columns'=> array(
        'INCREMENT' => array (     
            //設定進行原子操作的列名為attr0以及設定對列進行增量變更的值為1.其中attr0列的資料類型為整型。
            array('attr0', 1, ColumnTypeConst::CONST_INTEGER), 
        ),
        'PUT' => array(
            array('attr1', 1, ColumnTypeConst::CONST_INTEGER),
        )
    ),
    //返回進行原子操作後的列資訊。
    'return_content' => array(
        'return_type' => ReturnTypeConst::CONST_AFTER_MODIFY,
        'return_column_names' => array('attr0')
    )
);
$response = $otsClient->updateRow ($request);
print json_encode ($response);