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
|
attribute_columns | The attribute columns of the row.
|
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
|
Examples
The following code provides an example on how to insert a row of data:
## 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
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.
|
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.