Tablestore:Write data

Method signature

"""
Description: Writes a single row of data. Returns the capacity units (CUs) consumed by the operation.
table_name: the name of the table.
row: the row data, including primary key columns and attribute columns.
condition: the condition that Tablestore checks before performing the operation. The operation proceeds only when the condition is met. The condition parameter is an instance of the tablestore.metadata.Condition class.
  Two condition types are supported: row existence conditions and column value conditions.
  For row existence conditions, set the value to IGNORE, EXPECT_EXIST, or EXPECT_NOT_EXIST.
return_type: the return type. An instance of the tablestore.metadata.ReturnType class. Currently only primary key values can be returned. Typically used with auto-increment primary key columns.
Response: the CUs consumed and the row data to return.
  consumed: the CUs consumed. An instance of the tablestore.metadata.CapacityUnit class.
  return_row: the returned row data, which may include primary key and attribute columns.
Example:
    primary_key = [('gid',1), ('uid',101)]
    attribute_columns = [('name','Mary'), ('mobile',111111111), ('address','City A in China'), ('age',20)]
    row = Row(primary_key, attribute_columns)
    condition = Condition('EXPECT_NOT_EXIST')
    consumed, return_row = client.put_row('myTable', row, condition)
"""
def put_row(self, table_name, row, condition = None, return_type = None, transaction_id = None):

Parameters

Examples

Insert a row of data.

# Specify the data table name.
table_name = '<TABLE_NAME>'

# Define the primary key: gid = 1, uid = 101.
primary_key = [('gid',1), ('uid',101)]
# Define five attribute columns:
# name: string "John" (version auto-generated)
# mobile: integer 1390000**** (version auto-generated)
# address: binary value "China" (version auto-generated)
# female: boolean False (version auto-generated)
# age: double 29.7 (version explicitly set to 1498184687000)
attribute_columns = [('name','John'), ('mobile',1390000****),('address', bytearray('China', encoding='utf8')),('female', False), ('age', 29.7, 1498184687000)]
# Construct a Row from the primary key and attribute columns.
row = Row(primary_key, attribute_columns)

# Set the row existence condition to EXPECT_NOT_EXIST. If the row already exists, a Condition Update Failed error is returned.
condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)
try:
    # Call put_row. When ReturnType is not specified, return_row is None.
    consumed, return_row = client.put_row(table_name, row, condition)

    # Print the write CUs consumed.
    print('put row succeed, consume %s write cu.' % consumed.write)
# Client exceptions are typically caused by parameter errors or network issues.
except OTSClientError as e:
    print("put row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exceptions are typically caused by parameter errors or throttling.
except OTSServiceError as e:
    print("put row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))                    

For the complete sample code, see PutRow@GitHub.

Method signature

"""
Description: Updates a single row of data.
table_name: the name of the table.
row: the row data to update, including primary key columns and attribute columns. The primary key is a list; attribute columns are a dict.
condition: the condition that Tablestore checks before performing the operation. The operation proceeds only when the condition is met. The condition parameter is an instance of the tablestore.metadata.Condition class.
  Two condition types are supported: row existence conditions and column value conditions.
  For row existence conditions, set the value to IGNORE, EXPECT_EXIST, or EXPECT_NOT_EXIST.
return_type: the return type. An instance of the tablestore.metadata.ReturnType class. Currently only primary key values can be returned. Typically used with auto-increment primary key columns.
Response: the CUs consumed and the row data to return.
  consumed: the CUs consumed. An instance of the tablestore.metadata.CapacityUnit class.
  return_row: the returned row data.
Example:
    primary_key = [('gid',1), ('uid',101)]
    update_of_attribute_columns = {
        'put' : [('name','Jack'), ('address','City A in China')],
        'delete' : [('mobile', None, 1493725896147)],
        'delete_all' : [('age')],
        'increment' : [('counter', 1)]
    }
    row = Row(primary_key, update_of_attribute_columns)
    condition = Condition('EXPECT_EXIST')
    consumed = client.update_row('myTable', row, condition)
"""
def update_row(self, table_name, row, condition, return_type = None, transaction_id = None):

Parameters

Examples

Update a row of data.

# Specify the data table name.
table_name = '<TABLE_NAME>'

# Define the primary key: gid = 1, uid = 101.
primary_key = [('gid',1), ('uid',101)]
# The update includes three action types: PUT, DELETE, and DELETE_ALL.
# PUT: add or update column values. Adds name = "David" and address = "Hongkong".
# DELETE: delete a specific version. Deletes the address column version 1488436949003.
# DELETE_ALL: delete all versions of a column. Removes all versions of mobile and age.
update_of_attribute_columns = {
    'PUT' : [('name','David'), ('address','Hongkong')],
    'DELETE' : [('address', None, 1488436949003)],
    'DELETE_ALL' : [('mobile'), ('age')],
}
row = Row(primary_key, update_of_attribute_columns)

# Set the row existence condition to IGNORE with a column condition: update only when age equals 20.
condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", 20, ComparatorType.EQUAL)) # update row only when this row is exist
try:
    consumed, return_row = client.update_row(table_name, row, condition)
    
    # Print the write CUs consumed.
    print('put row succeed, consume %s write cu.' % consumed.write)
# Client exceptions are typically caused by parameter errors or network issues.
except OTSClientError as e:
    print("update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exceptions are typically caused by parameter errors or throttling.
except OTSServiceError as e:
    print("update row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))

For the complete sample code, see UpdateRow@GitHub.

Usage notes

When you call BatchWriteRow, some rows may fail to write. The operation does not throw an exception for partial failures. Instead, the returned BatchWriteRowResponse contains the indexes and error messages of the failed rows. Always check the return value to verify whether each row was written successfully. Unchecked failures may go unnoticed.

If the server detects parameter errors in some sub-operations, BatchWriteRow may throw an exception. In this case, none of the sub-operations in the request are executed.

Examples

Batch write multiple rows of data.

put_row_items = []
# Add rows for the PutRow sub-operation.
for i in range(0, 20):
    primary_key = [('gid',i), ('uid',i+1)]
    attribute_columns = [('name','somebody'+str(i)), ('address','somewhere'+str(i)), ('age',i)]
    row = Row(primary_key, attribute_columns)
    condition = Condition(RowExistenceExpectation.IGNORE)
    item = PutRowItem(row, condition)
    put_row_items.append(item)

# Add rows for the UpdateRow sub-operation.
for i in range(0, 10):
    primary_key = [('gid',i), ('uid',i+1)]
    attribute_columns = {'put': [('name','somebody'+str(i)), ('address','somewhere'+str(i)), ('age',i)]}
    row = Row(primary_key, attribute_columns)
    condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", i, ComparatorType.EQUAL))
    item = UpdateRowItem(row, condition)
    put_row_items.append(item)

# Add rows for the DeleteRow sub-operation.
delete_row_items = []
for i in range(10, 20):
    primary_key = [('gid',i), ('uid',i+1)]
    row = Row(primary_key)
    condition = Condition(RowExistenceExpectation.IGNORE)
    item = DeleteRowItem(row, condition)
    delete_row_items.append(item)

# Construct the batch write request.
request = BatchWriteRowRequest()
# When calling add multiple times for the same table, only the last add call takes effect.
request.add(TableInBatchWriteRowItem('<TABLE_NAME>', put_row_items))
request.add(TableInBatchWriteRowItem('<DELETE_TABLE_NAME>', delete_row_items))

# Call batch_write_row. Parameter errors throw an exception. Partial row failures do not throw an exception but are reflected in the response items.
try:
    result = client.batch_write_row(request)
    print('Result status: %s'%(result.is_all_succeed()))

    # Check PutRow results.
    print('check first table\'s put results:')
    succ, fail = result.get_put()
    for item in succ:
        print('Put succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print('Put failed, error code: %s, error message: %s' % (item.error_code, item.error_message))

    # Check UpdateRow results.
    print('check first table\'s update results:')
    succ, fail = result.get_update()
    for item in succ:
        print('Update succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print('Update failed, error code: %s, error message: %s' % (item.error_code, item.error_message))

    # Check DeleteRow results.
    print('check second table\'s delete results:')
    succ, fail = result.get_delete()
    for item in succ:
        print('Delete succeed, consume %s write cu.' % item.consumed.write)
    for item in fail:
        print('Delete failed, error code: %s, error message: %s' % (item.error_code, item.error_message)) 
# Client exceptions are typically caused by parameter errors or network issues.
except OTSClientError as e:
    print("get row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exceptions are typically caused by parameter errors or throttling.
except OTSServiceError as e:
    print("get row failed, http_status:%d, error_code:%s, error_message:%s, request_id:%s" % (e.get_http_status(), e.get_error_code(), e.get_error_message(), e.get_request_id()))

For the complete sample code, see BatchWriteRow@GitHub.