Single-row operations

Last Updated: Sep 22, 2017

The Table Store SDK provides the following single-row operation APIs:

PutRow

Inserts data into a specified row.

API

  1. """
  2. Description: This operation writes a single row of data. CapacityUnit consumed by the operation is returned.
  3. ``table_name`` is the name of the table.
  4. ``row`` indicates row data, including primary key columns and attribute columns.
  5. ``condition`` indicates the conditions to be checked before an operation is executed. If the conditions are met, the operation is executed. It is an instance of the tablestore.metadata.Condition class. Currently, this function only supports row existence checks. Check conditions include: 'IGNORE', 'EXPECT_EXIST', and 'EXPECT_NOT_EXIST'.
  6. ``return_type`` indicates the type of the returned value. It is an instance of the tablestore.metadata.ReturnType class. Currently, only return of PrimaryKey is supported, which is typically used in automatic increment of primary key columns.
  7. Return: CapacityUnits consumed by the operation, as well as the row data to be returned.
  8. ``consumed`` indicates the CapacityUnits consumed. It is an instance of the tablestore.metadata.CapacityUnit class.
  9. ``return_row`` indicates the row data returned, which may include the primary key and attribute columns.
  10. """
  11. def put_row(self, table_name, row, condition = None, return_type = None)

Examples

Insert a data row.

  1. ## The first primary key column of the primary key is gid with an integral value of 1. The second primary key column is uid with an integral value of 101.
  2. primary_key = [('gid',1), ('uid',101)]
  3. ## Four attribute columns exist:
  4. ## The first attribute column is "name" with the string value "John". The version is not specified, and the current system time is used as the version.
  5. ## The second attribute column is "mobile" with the integral value 15100000000. The version is not specified, and the current system time is used as the version.
  6. ## The third attribute column is "address" with the binary value "China". The version is not specified, and the current system time is used as the version.
  7. ## The fourth column is "age" with the value 29.7. The version is 1498184687.
  8. attribute_columns = [('name','John'), ('mobile',15100000000),('address', bytearray('China')),('female', False), ('age', 29.7, 1498184687000)]
  9. ## Construction of Row using primary_key and attribute_columns
  10. row = Row(primary_key, attribute_columns)
  11. # Row condition: The expected row does not exist. If the expected row exists, the error "Condition Update Failed" is returned.
  12. condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)
  13. try :
  14. # Call the put_row method. If ReturnType is not specified, return_row is None.
  15. consumed, return_row = client.put_row(table_name, row, condition)
  16. # The write CU consumed by this request is printed.
  17. print ('put row succeed, consume %s write cu.' % consumed.write)
  18. # The client is abnormal, which is typically due to incorrect parameters or a network error.
  19. except OTSClientError as e:
  20. print "get row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
  21. # The server is abnormal, which is typically due to incorrect parameters or a network error.
  22. except OTSServiceError as e:
  23. 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())

Note:

  • RowExistenceExpectation.IGNORE indicates that new data is inserted no matter whether the specified row exists or not. If the inserted data is the same as the existing data, 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 data is inserted only when the specified row does not exist.
  • In the preceding sample program, the version of the attribute column “age” is 1498184687000, and the value is June, 23, 2017. If the current time minus the value of max_time_deviation (specified during table creation) is greater than 1498184687000, the PutRow operation is disabled.
  • If the operation is successful, no exception is thrown; if the operation fails, an exception is thrown.
  • Code details: PutRow@GitHub.

GetRow

This API reads a single data row based on a given Primary Key.

API

  1. """
  2. Description: This operation reads a single row of data.
  3. ``table_name`` is the name of the table.
  4. ``primary_key`` indicates the primary key; type: dict.
  5. ``columns_to_get`` is an optional parameter that indicates the names of the columns to read in list format. If not entered, all columns will be read.
  6. ``column_filter`` is an optional parameter, which indicates reading the row that meets specified conditions.
  7. ``max_version`` is an optional parameter, which indicates the maximum number of read versions.
  8. ``time_range`` is an optional parameter, which indicates reading versions within the specified range or reading the specified version. time_range and max_version are mutually exclusive.
  9. Return: The CapacityUnits consumed by this operation, as well as the primary key columns and attribute columns.
  10. ``consumed`` indicates the CapacityUnits consumed. It is an instance of the tablestore.metadata.CapacityUnit class.
  11. ``return_row`` indicates row data, including primary key columns and attribute columns of the list type, for example, [('PK0',value0), ('PK1',value1)].
  12. ``next_token`` indicates the location of the next read operation in the case of wide row reading. The value is encoded in binary format.
  13. """
  14. def get_row(self, table_name, primary_key, columns_to_get=None,
  15. column_filter=None, max_version=None, time_range=None,
  16. start_column=None, end_column=None, token=None):

Examples

Read a data row.

  1. # The first column of the primary key is uid with the integral value 1. The second column is gid with the integral value 101.
  2. primary_key = [('uid',1), ('gid',101)]
  3. # Attribute columns to be returned: name, growth, and type If columns_to_get is [], all attribute columns are returned.
  4. columns_to_get = ['name', 'growth', 'type']
  5. # Add column filter: This row is returned if the value of the growth column is not 0.9.
  6. cond = CompositeColumnCondition(LogicalOperator.AND)
  7. cond.add_sub_condition(SingleColumnCondition("growth", 0.9, ComparatorType.NOT_EQUAL))
  8. cond.add_sub_condition(SingleColumnCondition("name", 'Hangzhou', ComparatorType.EQUAL))
  9. try:
  10. # Call the get_row query interface. The last parameter 1 indicates that the value of only one version needs to be returned.
  11. consumed, return_row, next_token = client.get_row(table_name, primary_key, columns_to_get, cond, 1)
  12. print ('Read succeed, consume %s read cu.' % consumed.read)
  13. print ('Value of primary key: %s' % return_row.primary_key)
  14. print ('Value of attribute: %s' % return_row.attribute_columns)
  15. for att in return_row.attribute_columns:
  16. # Print the key, value, and version of each column.
  17. print ('name:%s\tvalue:%s\ttimestamp:%d' % (att[0], att[1], att[2]))
  18. # The client is abnormal, which is typically due to incorrect parameters or a network error.
  19. except OTSClientError as e:
  20. print "get row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
  21. # The server is abnormal, which is typically due to incorrect parameters or a network error.
  22. except OTSServiceError as e:
  23. 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())

Note:

  • If you query a data row, the system returns the data in all columns of the row. You can use the columns_to_get parameter to read the data in specified columns. For example, the system only returns the data in col0 and col1 if col0 and col1 are inserted into columns_to_get.
  • Code details: GetRow@GitHub.

UpdateRow

Updates the data of the specified row. If the row does not exist, a new row is added. If the row exists, the values of the specified columns are added, modified, or deleted based on the request content.

API

  1. """
  2. Description: This operation updates a single row of data.
  3. ``table_name`` is the name of the table.
  4. ``row`` indicates the updated row data, including primary key columns (of the list type) and attribute columns (of the dict type).
  5. ``condition`` indicates the conditions to be checked before an operation is executed. If the conditions are met, the operation is executed. It is an instance of the tablestore.metadata.Condition class.
  6. Currently, this function only supports row existence checks. Check conditions include: 'IGNORE', 'EXPECT_EXIST', and 'EXPECT_NOT_EXIST'.
  7. ``return_type`` indicates the type of the returned value. It is an instance of the tablestore.metadata.ReturnType class. Currently, only return of PrimaryKey is supported, which is typically used in automatic increment of primary key columns.
  8. Return: CapacityUnits consumed by the operation, as well as the row data to be returned (which is indicated by return_row).
  9. consumed indicates the CapacityUnits consumed. It is an instance of the tablestore.metadata.CapacityUnit class.
  10. return_row indicates the row data to be returned.
  11. """
  12. def update_row(self, table_name, row, condition, return_type = None)

Examples

Update a data row.

  1. # The first column of the primary key is uid with the integral value 1. The second column is gid with the integral value 101.
  2. primary_key = [('uid',1), ('gid',101)]
  3. # The update contains three parts: PUT, DELETE, and DELETE_ALL.
  4. # PUT: Add two columns. The first column is "name" and the value is David; the second column is "address" and the value is Hongkong.
  5. # DELETE: Delete the value of the address column with the version 1488436949003.
  6. # DELETE_ALL: Delete the values of all versions in the "mobile" and "age" columns.
  7. update_of_attribute_columns = {
  8. 'PUT' : [('name','David'), ('address','Hongkong')],
  9. 'DELETE' : [('address', None, 1488436949003)],
  10. 'DELETE_ALL' : [('mobile'), ('age')],
  11. }
  12. row = Row(primary_key, update_of_attribute_columns)
  13. # The row condition is Ignore, indicating that data is updated regardless of whether the specified row exists.
  14. condition = Condition(RowExistenceExpectation.IGNORE, SingleColumnCondition("age", 20, ComparatorType.EQUAL)) # update row on\
  15. ly when this row is exist
  16. try:
  17. consumed, return_row = client.update_row(table_name, row, condition)
  18. # The client is abnormal, which is typically due to incorrect parameters or a network error.
  19. except OTSClientError as e:
  20. print "update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
  21. # The server is abnormal, which is typically due to incorrect parameters or a network error.
  22. except OTSServiceError as e:
  23. 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())

Note: Code details: UpdateRow@GitHub.

DeleteRow

API

  1. """
  2. Description: This operation deletes a single row of data.
  3. ``table_name`` is the name of the table.
  4. ``row`` indicates row data, which contains only the primary key in the case of delete_row.
  5. ``condition`` indicates the conditions to be checked before an operation is executed. If the conditions are met, the operation is executed. It is an instance of the tablestore.metadata.Condition class.
  6. Currently, this function only supports row existence checks. Check conditions include: 'IGNORE', 'EXPECT_EXIST', and 'EXPECT_NOT_EXIST'.
  7. Return: CapacityUnits consumed by the operation, as well as the row data to be returned (which is indicated by return_row).
  8. consumed indicates the CapacityUnits consumed. It is an instance of the tablestore.metadata.CapacityUnit class.
  9. return_row indicates the row data to be returned.
  10. """
  11. def delete_row(self, table_name, row, condition, return_type = None):

Examples

Delete a data row.

  1. primary_key = [('gid',1), ('uid','101')]
  2. row = Row(primary_key)
  3. try:
  4. consumed, return_row = client.delete_row(table_name, row, None)
  5. # The client is abnormal, which is typically due to incorrect parameters or a network error.
  6. except OTSClientError as e:
  7. print "update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
  8. # The server is abnormal, which is typically due to incorrect parameters or a network error.
  9. except OTSServiceError as e:
  10. 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())
  11. print ('Delete succeed, consume %s write cu.' % consumed.write)

Note: Code details: DeleteRow@GitHub.

Thank you! We've received your feedback.