Tablestore:Write data

API operation

"""
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: the name of the table. 
row: the row that you want to write to the data table, including primary key columns and attribute columns. 
condition: the condition that must be met to perform the operation. After you specify a condition, Tablestore checks whether the specified condition is met before Tablestore performs the operation. The operation is performed only if the condition is met. The condition parameter is an instance of the tablestore.metadata.Condition class. 
Row existence conditions and conditions based on column values are supported. If you want to specify a row existence condition, you can set the condition parameter to IGNORE, EXPECT_EXIST, or EXPECT_NOT_EXIST based on your business requirements. 
return_type: the type of data that you want to return. The return_type parameter is an instance of the tablestore.metadata.ReturnType class. Only the primary key can be returned. In most cases, this parameter is used by the auto-increment primary key column feature. 
Response: the number of CUs that are consumed by the operation and the row data that is returned. 
consumed: the number of CUs consumed by the operation. The consumed parameter is an instance of the tablestore.metadata.CapacityUnit class. 
return_row: the row data that is returned, which may include primary key columns 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

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

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

# 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)]
# The row contains five attribute columns:
# The first attribute column is name and the value is the string John. The data version number of the first attribute column is not specified. The system uses the current time as the data version number. 
# The second attribute column is mobile and the value is the integer 1390000****. The data version number of the second attribute column is not specified. The system uses the current time as the data version number. 
# The third attribute column is address and the value is the binary value China. The data version number of the third attribute column is not specified. The system uses the current time as the data version number. 
# The fourth attribute column is female and the value is the Boolean value False. The data version number of the fourth attribute column is not specified. The system uses the current time as the data version number. 
# The fifth attribute column is age and the value is 29.7. 1498184687000 is specified as the data version number of the fifth attribute column. 
attribute_columns = [('name','John'), ('mobile',1390000****),('address', bytearray('China', encoding='utf8')),('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 you do not specify the ReturnType parameter when you call the put_row method, the value of the return_row parameter 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)
# In most cases, client exceptions are 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()))
# In most cases, server exceptions are 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.

API operation

"""
Description: This operation updates a single row of data. 
table_name: the name of the table. 
row: the row that you want to update, including primary key columns and attribute columns. The primary key columns are in the list structure and the attribute columns are in the dict structure. 
condition: the condition that must be met to perform the operation. After you specify a condition, Tablestore checks whether the specified condition is met before Tablestore performs the operation. The operation is performed only if the condition is met. The condition parameter is an instance of the tablestore.metadata.Condition class. 
Row existence conditions and conditions based on column values are supported. If you want to specify a row existence condition, you can set the condition parameter to IGNORE, EXPECT_EXIST, or EXPECT_NOT_EXIST based on your business requirements. 
return_type: the type of data that you want to return. The return_type parameter is an instance of the tablestore.metadata.ReturnType class. Only the primary key can be returned. In most cases, this parameter is used by the auto-increment primary key column feature. 
Response: the number of CUs that are consumed by the operation and the row data that is specified by return_row.
consumed: the number of CUs consumed by the operation. The consumed parameter is an instance of the tablestore.metadata.CapacityUnit class. 
return_row: the row data that is returned. 
Example:
    primary_key = [('gid',1), ('uid',101)]
    update_of_attribute_columns = {
        'put' : [('name','Jack'), ('address','City A in China')],
        'delete' : [('mobile', 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

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

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

# 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)]
# The update types include PUT, DELETE, and DELETE_ALL. 
# PUT: adds an attribute column or updates the existing value in an attribute column. In this example, two attribute columns are added. The first column is name and the value is David. The second column is address and the value is Hongkong. 
# DELETE: deletes a specific version (timestamp) of data. In this example, data whose data version number is 1488436949003 in the address column is deleted. 
# DELETE_ALL: deletes the column. In this example, all version of data 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)

# In this example, the Condition parameter is set to RowExistenceExpectation.IGNORE, which specifies that the row is updated regardless of whether the row exists. 
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)
    
    # Display the number of write CUs that are consumed by the request. 
    print('put row succeed, consume %s write cu.' % consumed.write)
# In most cases, 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()))
# In most cases, 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()))

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

Usage notes

When you call the BatchWriteRow operation to write multiple rows of data at the same time, some rows may fail to be written. In this case, Tablestore does not return exceptions. Tablestore returns BatchWriteRowResponse in which the indexes and error messages of the failed rows are included. When you call the BatchWriteRow operation, make sure that you check the return values to determine whether all rows are written. If you do not check the return values, the rows that fail to be written may be ignored.

If the server detects that invalid parameters exist in some operations, an error message may return before the operations of the request are performed.

Examples

The following sample code provides an example on how to write multiple rows of data at the same time:

put_row_items = []
# Call the PutRow operation to insert a row. 
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)

# Call the UpdateRow operation to update a row. 
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)

# Call the DeleteRow operation to delete a row. 
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 at the same time. 
request = BatchWriteRowRequest()
request.add(TableInBatchWriteRowItem('<TABLE_NAME>', put_row_items))
request.add(TableInBatchWriteRowItem('<DELETE_TABLE_NAME>', delete_row_items))

# When you call the batch_write_row method to write multiple rows of data at the same time, 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)) 
# In most cases, client exceptions are 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()))
# In most cases, server exceptions are 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.