Tablestore provides the PutRow and UpdateRow operations to allow you to write a single row of data, and the BatchWriteRow operation to allow you to write multiple rows of data in a batch.

Prerequisites

  • The OTSClient instance is initialized. For more information, see Initialization.
  • A data table is created. Data is written to the table.

Insert a single row of data

You can call the PutRow operation to insert a row of data. If the row exists, the PutRow operation deletes all versions of data in all columns from the existing row, and then inserts a new row.

API operations

"""
Description: This operation writes a single row of data. The number of capacity units (CUs) that are consumed by the operation is returned. 
table_name specifies the name of the table. 
row specifies the row you want to insert to the table, including primary key columns and attribute columns. 
condition is an instance of the tablestore.metadata.Condition class. After a condition is specified, Tablestore checks whether the specified condition is met before Tablestore performs the operation. The operation is performed only when the condition is met. You can specify a row existence condition or a condition based on column values. If you specify a row existence condition, you can set condition to IGNORE, EXPECT_EXIST, or EXPECT_NOT_EXIST. 
return_type specifies the type of data that you want to return. return_type is an instance of the tablestore.metadata.ReturnType class. Only primary key columns can be returned. This parameter applies to auto-increment primary key columns. 

Response: the number of CUs that are consumed by the operation and the row data that is returned. 
consumed is an instance of the tablestore.metadata.CapacityUnit class. This parameter indicates the number of CUs that are consumed by the operation. 
return_row indicates the row data that is returned, including the primary key and attribute columns. 
"""
def put_row(self, table_name, row, condition = None, return_type = None)                   

Parameters

Parameter Description
table_name The name of the data table.
primary_key The primary key of the row.
Note
  • The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
  • If a primary key column is an auto-increment primary key column, you need to only set the value of the auto-increment primary key column to a placeholder. For more information, see Configure an auto-increment primary key column.
attribute_columns The attribute columns of the row.
  • Each attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value (ColumnValue), attribute column value type (ColumnType), and timestamp. ColumnType and the timestamp are optional.
  • You can set ColumnType to ColumnType.INTEGER that specifies an INTEGER value, ColumnType.STRING that specifies a UTF-8 encoded STRING, ColumnType.BINARY that specifies a BINARY value, ColumnType.BOOLEAN that specifies a BOOLEAN value, or ColumnType.DOUBLE that specifies a DOUBLE value. If you want to set the column value type to BINARY, you must set ColumnType to ColumnType.BINARY. If you want to use other types of column values, the ColumnType is optional.
  • The timestamp is the data version number. For more information, see Data versions and TTL.

    You can specify a data version number or use the data version number that is generated by Tablestore. If you do not configure this parameter, the data version number that is generated by Tablestore is used.

    • The version number that is generated by Tablestore is the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
    • If you specify the version number, make sure that the version number is a 64-bit timestamp that is accurate to milliseconds and is in the valid version range.
condition The condition that you want to specify to perform the PutRow operation. You can specify a row existence condition or a condition based on column values. For more information, see Configure conditional update.
Note
  • RowExistenceExpectation.IGNORE indicates that new data is inserted into a row regardless of whether the specified row exists. If the specified row exists, the existing data is overwritten.
  • RowExistenceExpectation.EXPECT_EXIST indicates that new data is inserted only when the specified row exists. The existing data is overwritten.
  • RowExistenceExpectation.EXPECT_NOT_EXIST indicates that new data is inserted only when the specified row does not exist.

Examples

The following code provides an example on how to insert a row of data:

Note In the following example, the data version in the age attribute column is 1498184687000, which indicates June 23, 2017. If the difference between the current time and the value of max_time_deviation is greater than 1498184687000, the PutRow operation is prohibited. The value of max_time_deviation is specified when you create the table.
## The first primary key column is gid and the value is the integer 1. The second primary key column is uid and the value is the integer 101. 
primary_key = [('gid',1), ('uid',101)]

## Insert the following attribute columns:
##              The name of the first attribute column is name and the value is John (type: String). The version number is not specified, and the current system time is used as the version number. 
##              The name of the second attribute column is mobile and the value is 13900006666 (type: Integer). The version number is not specified, and current system time is used as the version number. 
##              The name of the third attribute column is address and the value is China (type: Binary). The version number is not specified, and current system time is used as the version number. 
##              The name of the fourth attribute column is female and the value is False (type: Boolean). The version number is not specified, and current system time is used as the version number. 
##              The name of the fifth attribute column is age and the value is 29.7. The specified version number is 1498184687000. 
attribute_columns = [('name','John'), ('mobile',13900006666),('address', bytearray('China')),('female', False), ('age', 29.7, 1498184687000)]

## Construct a row by using primary_key and attribute_columns. 
row = Row(primary_key, attribute_columns)

# Specify a row existence condition that expects the specified row to not exist. If the specified row exists, the Condition Update Failed error occurs. 
condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)

try :
    # If ReturnType is not specified when you call the put_row method, the value of return_row is None. 
    consumed, return_row = client.put_row(table_name, row, condition)

    # Display the number of write CUs that are consumed by the request. 
    print ('put row succeed, consume %s write cu.' % consumed.write)
# Client exceptions are generally caused by parameter errors or network exceptions. 
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 generally caused by parameter or throttling errors. 
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())                    

To view the detailed sample code, visit PutRow@GitHub.

Update a single row of data

You can call the UpdateRow operation to update the data in a row. You can add attribute columns to a row or delete attribute columns from a row, delete a specified version of data from an attribute column, or update the existing data in an attribute column. If the row does not exist, a new row is added.
Note If you call the UpdateRow operation only to delete columns from a row and the row does not exist, no row is inserted into the table.

API operations

"""
Description: This operation updates a single row of data. 
table_name specifies the name of the table. 
row specifies the row you want to update, including primary key columns and attribute columns of the list type. 
condition is an instance of the tablestore.metadata.Condition class. After conditions are specified, Tablestore checks whether the specified conditions are met before Tablestore performs the operation. The operation is performed only when the conditions are met. This feature supports row existence and column-based conditions checks. Check conditions for row existence include IGNORE, EXPECT_EXIST, and EXPECT_NOT_EXIST. 
return_type specifies the type of data to return. return_type is an instance of the tablestore.metadata.ReturnType class. Only primary key columns can be returned. This parameter applies to auto-increment primary key columns. 
Response: the number of CUs consumed by this operation and the row data that is specified by return_row to return. 
consumed is an instance of the tablestore.metadata.CapacityUnit class. This parameter indicates the number of CUs consumed by this operation. 
return_row indicates the row to return. 
"""
def update_row(self, table_name, row, condition, return_type = None)                    

Parameters

Parameter Description
table_name The name of the data table.
primary_key The primary key of the row.
Note The number and types of the primary key columns that you specify must be the same as the actual number and types of primary key columns in the data table.
update_of_attribute_columns The attribute column you want to update.
  • Each attribute column is specified by parameters in the following sequence: the attribute column name, attribute column value, attribute column value type, and timestamp. The attribute column value type and the timestamp are optional.

    A timestamp is a data version number. You can specify a data version number or use the data version number that is generated by Tablestore. By default, if you do not configure this parameter, the data version number that is generated by Tablestore is used. For more information, see Data versions and TTL.

    • The version number that is generated by Tablestore is the number of milliseconds that have elapsed since 00:00:00 UTC on January 1, 1970.
    • If you specify the version number, make sure that the version number is a 64-bit timestamp that is accurate to milliseconds and is in the valid version range.
  • To delete a specified version of data from an attribute column, you need to only specify the attribute column name and timestamp.

    The timestamp is a 64-bit integer that indicates a specified version of data. Unit: milliseconds.

  • To delete an attribute column, you need to only specify the attribute column name.
    Note A row exists even if all attribute columns in the row are deleted. To delete a row, use the DeleteRow operation.
condition The condition that you can configure to perform the UpdateRow operation. You can configure a row existence condition or a column-based condition. For more information, see Configure conditional update.

Example

The following code provides an example on how to update the data of a specified row:

# The first primary key column is uid and its value is the integer 1. The second primary key column is gid and its value is the integer 101. 
primary_key = [('uid',1), ('gid',101)]

# The update types include PUT, DELETE, and DELETE_ALL. 
# PUT: adds a value to the column or updates the existing value in the column. In the example, two columns are added. The first column is name and its value is David. The second column is address and its value is Hongkong. 
# DELETE: deletes a specified version (timestamp) of data. In this example, data whose version number is 1488436949003 in the address column is deleted. 
# DELETE_ALL: deletes the column. In the example, the date of all versions in the mobile and age columns are deleted. 
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 condition for row check is that the row existence is ignored. No matter whether the row exists, the row is updated. 
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)
# Client exceptions are caused by parameter errors or network exceptions. 
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 caused by parameter or throttling errors. 
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 detailed sample code, visit UpdateRow@GitHub.

Write multiple rows of data in a batch

You can call the BatchWriteRow operation to write multiple rows to one or more tables in a batch. The BatchWriteRow operation is a set of PutRow, UpdateRow, or DeleteRow operations. When you call the BatchWriteRow operation, the process of constructing the PutRow, UpdateRow, or DeleteRow operations is the same as the process of constructing the PutRow, UpdateRow, or DeleteRow operation when you call the PutRow, UpdateRow, or DeleteRow operation. BatchWriteRow supports conditional update.

If you call the BatchWriteRow operation, each PutRow, UpdateRow, or DeleteRow operation is separately performed and the response to each PutRow, UpdateRow, or DeleteRow operation is separately returned.

Usage notes

When you call the BatchWriteRow operation to write multiple rows in a batch, some rows may fail to be written. If this happens, Tablestore does not return exceptions, but returns BatchWriteRowResponse in which the indexes and error messages of the failed rows are included. Therefore, when you call the BatchWriteRow operation, you must check the return values to determine whether the operation on each row is successful. If you do not check the return values, failures of operations on some rows are ignored.

If the server detects that invalid parameters exist in some operations, the BatchWriteRow operation may return an exception about parameter errors before the first operation in the request is performed.

API operations

"""
Description: This operation writes multiple rows of data in a batch. 
request = MiltiTableInBatchWriteRowItem()
request.add(TableInBatchWriteRowItem(table0, row_items))
request.add(TableInBatchWriteRowItem(table1, row_items))
response = client.batch_write_row(request)
response indicates the returned result. Type: tablestore.metadata.BatchWriteRowResponse. 
"""
def batch_write_row(self, request):                   

Examples

The following code provides an example on how to write multiple rows of data in a batch:

put_row_items = []
# Add rows for PutRow. 
for i in range(0, 10):
    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 UpdateRow. 
for i in range(10, 20):
    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 DeleteRow. 
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 request to write multiple rows of data in a batch. 
request = BatchWriteRowRequest()
request.add(TableInBatchWriteRowItem(table_name, put_row_items))
request.add(TableInBatchWriteRowItem('notExistTable', delete_row_items))

# When you call the batch_write_row method to write multiple rows of data in a batch, exceptions may occur if errors such as request parameter errors occur. If the operation fails for part of the rows, an exception may not occur but the internal items may fail. 
try:
    result = client.batch_write_row(request)
    print ('Result status: %s'%(result.is_all_succeed()))

    # Check the result of the PutRow operation. 
    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 result of the UpdateRow operation. 
    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 result of the DeleteRow operation. 
    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 generally caused by parameter errors or network exceptions. 
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 generally caused by parameter or throttling errors. 
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())                    

To view the detailed sample code, visit BatchWriteRow@GitHub.