Write data

API

"""
Writes a single row and returns the consumed capacity units.
``table_name``: The name of the data table.
``row``: The row data, which includes the primary key and attribute columns.
``condition``: The condition that must be met for the operation to proceed. This is an instance of `tablestore.metadata.Condition`.
Tablestore supports two types of conditions: a row existence condition ('IGNORE', 'EXPECT_EXIST', or 'EXPECT_NOT_EXIST') and a column value condition.
``return_type``: The type of data to return. This is an instance of `tablestore.metadata.ReturnType`. Currently, only `PrimaryKey` is supported, which is typically used with an auto-increment primary key column.
Returns: The capacity units consumed and the requested row data.
consumed: An instance of the tablestore.metadata.CapacityUnit class that represents the consumed capacity units.
return_row: The returned row data, which may include the primary key and attribute columns.
Example:
    primary_key = [('gid',1), ('uid',101)]
    attribute_columns = [('name','Mary'), ('mobile',111****1111), ('address','China, City A'), ('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

Example

Insert a row of data.

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

# The primary key consists of two columns: 'gid' with an integer value of 1, 
# and 'uid' with an integer value of 101.
primary_key = [('gid',1), ('uid',101)]
# Define five attribute columns:
# - 'name': A string 'J***'. The version is not specified, so the system uses the current timestamp as the version.
# - 'mobile': An integer 139********. The version is not specified.
# - 'address': A binary value 'China'. The version is not specified.
# - 'female': A boolean value False. The version is not specified.
# - 'age': A double value 29.7. The version is explicitly set to 1498184687000.
attribute_columns = [('name','J***'), ('mobile',139********),('address', bytearray('China', encoding='utf8')),('female', False), ('age', 29.7, 1498184687000)]
# Construct a Row object from the primary key and attribute columns.
row = Row(primary_key, attribute_columns)

# Set a conditional update. The row existence condition is set to expect that the row does not exist.
# If the row exists, a 'Condition Update Failed' error occurs.
condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)
try:
    # Call the put_row method. If ReturnType is not specified, return_row is None.
    consumed, return_row = client.put_row(table_name, row, condition)

    # Print the consumed write capacity units for this request.
    print('put row succeed, consume %s write cu.' % consumed.write)
# Client exception: typically caused by a parameter error or network issue.
except OTSClientError as e:
    print("put row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exception: typically caused by a parameter error 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 code, see PutRow@GitHub.

API

"""
Description: Updates a single row.
``table_name``: The name of the data table.
``row``: The row data to be updated, which includes the primary key columns (list) and attribute columns (dict).
``condition``: The condition that must be met for the operation to proceed. This is an instance of the tablestore.metadata.Condition class.
Tablestore supports two types of conditions: a row existence condition ('IGNORE', 'EXPECT_EXIST', or 'EXPECT_NOT_EXIST') and a column value condition.
``return_type``: The type of data to return. This is an instance of the tablestore.metadata.ReturnType class. Currently, only PrimaryKey is supported, which is typically used with an auto-increment primary key column.
Returns: The capacity units consumed and the requested row data (return_row).
consumed: An instance of the tablestore.metadata.CapacityUnit class that represents the consumed capacity units.
return_row: The requested row data.
Example:
    primary_key = [('gid',1), ('uid',101)]
    update_of_attribute_columns = {
        'put' : [('name','Jack'), ('address','China, City B')],
        'delete' : [('mobile', None, 1493725896147)],
        'delete_all' : [('age')],
        'increment' : [('counter', 1)]
    }
    row = Row(primary_key, update_of_attribute_columns)
    condition = Condition('EXPECT_EXIST')
    consumed, return_row = client.update_row('myTable', row, condition)
"""
def update_row(self, table_name, row, condition, return_type = None, transaction_id = None):

Parameters

Example

Update a row of data.

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

# The primary key consists of two columns: 'gid' with an integer value of 1,
# and 'uid' with an integer value of 101.
primary_key = [('gid',1), ('uid',101)]
# The update consists of 'PUT', 'DELETE', and 'DELETE_ALL' operations.
# 'PUT': Adds or updates column values. This example adds two columns: 'name' with the value 'David' and 'address' with the value 'Hongkong'.
# 'DELETE': Deletes a specific version of a column. This example deletes the version '1488436949003' of the 'address' column.
# 'DELETE_ALL': Deletes all versions of a column. This example deletes the 'mobile' and 'age' columns entirely.
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)

# The row existence condition is set to IGNORE, so the update occurs regardless of whether the row exists.
# A column condition is also set to update the row only if the 'age' column has a value of 20.
condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", 20, ComparatorType.EQUAL)) # update row only when age is 20
try:
    consumed, return_row = client.update_row(table_name, row, condition)
    
    # Print the consumed write capacity units for this request.
    print('update row succeed, consume %s write cu.' % consumed.write)
# Client exception: typically caused by a parameter error or network issue.
except OTSClientError as e:
    print("update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exception: typically caused by a parameter error 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 code, see UpdateRow@GitHub.

Usage notes

• When you call the BatchWriteRow operation, some sub-operations may fail. The operation does not throw an exception for such partial failures. Instead, the BatchWriteRowResponse object reports the status of each sub-operation. Therefore, you must always check the response to identify any failures.

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

• If you call add multiple times for the same data table in a request, only the final add call takes effect.

Example

Write data in batches.

put_row_items = []
# Add rows for the PutRow 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 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 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 a batch write request.
request = BatchWriteRowRequest()

# If you call the add operation multiple times for the same table, only the last add request takes effect.
request.add(TableInBatchWriteRowItem('<TABLE_NAME>', put_row_items))
request.add(TableInBatchWriteRowItem('<DELETE_TABLE_NAME>', delete_row_items))

# Example of performing multiple operations on the same table.
# table_batch_items = TableInBatchWriteRowItem('<TABLE_NAME>', put_row_items)
# table_batch_items.row_items += delete_row_items
# request.add(table_batch_items)
# Call the batch_write_row method to perform the batch write.
# An exception is thrown for request parameter errors.
# For failures of individual rows, no exception is thrown; instead, the status is returned in the corresponding result item.
try:
    result = client.batch_write_row(request)
    print('Result status: %s'%(result.is_all_succeed()))

    # Check the results for Put rows.
    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 the results for Update rows.
    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 the results for Delete rows.
    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 exception: typically caused by a parameter error or network issue.
except OTSClientError as e:
    print("batch write row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message()))
# Server exception: typically caused by a parameter error or throttling.
except OTSServiceError as e:
    print("batch write 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 code, see BatchWriteRow@GitHub.