Tablestore SDK for Python provides multi-row operations such as BatchGetRow, BatchWriteRow, and GetRange.

BatchGetRow

You can call this operation to read several rows of data from one or more tables.

The BatchGetRow operation is a set of multiple GetRow operations. The execution, returning of results, and capacity unit (CU) consumption of each operation are carried out independently.

Compared with the execution of a large number of GetRow operations, the use of the BatchGetRow operation can effectively reduce the request response time and increase the data read rate.

  • Operation
            """
            Description: This operation reads the specified rows of data.
            request = BatchGetRowRequest()
            request.add(TableInBatchGetRowItem(myTable0, primary_keys, column_to_get=None, column_filter=None))
            request.add(TableInBatchGetRowItem(myTable1, primary_keys, column_to_get=None, column_filter=None))
            request.add(TableInBatchGetRowItem(myTable2, primary_keys, column_to_get=None, column_filter=None))
            request.add(TableInBatchGetRowItem(myTable3, primary_keys, column_to_get=None, column_filter=None))
            response = client.batch_get_row(request)
            response: the response to the request. Type: tablestore.metadata.BatchGetRowResponse
            """
            def batch_get_row(self, request): 
    					
  • Examples

    The following code provides an example on how to read 3 rows of data at a time:

        # Specify the columns to return.
        columns_to_get = ['name', 'mobile', 'address', 'age']
    
        # Read three rows.
        rows_to_get = [] 
        for i in range(0, 3):
            primary_key = [('gid',i), ('uid',i+1)]
            rows_to_get.append(primary_key)
    
        # Configure filtering conditions. Set name to John and address to China.
        cond = CompositeColumnCondition(LogicalOperator.AND)
        cond.add_sub_condition(SingleColumnCondition("name", "John", ComparatorType.EQUAL))
        cond.add_sub_condition(SingleColumnCondition("address", 'China', ComparatorType.EQUAL))
    
        # Create a request to read multiple rows.
        request = BatchGetRowRequest()
    
        # Add rows to read from table_name. The 1 parameter specifies the latest version to read.
        request.add(TableInBatchGetRowItem(table_name, rows_to_get, columns_to_get, cond, 1))
    
        # Add rows to read from notExistTable.
        request.add(TableInBatchGetRowItem('notExistTable', rows_to_get, columns_to_get, cond, 1))
    
        try:
               result = client.batch_get_row(request) 
            print ('Result status: %s'%(result.is_all_succeed()))
    
            table_result_0 = result.get_result_by_table(table_name)
            table_result_1 = result.get_result_by_table('notExistTable')
            print ('Check first table\'s result:')
            for item in table_result_0: 
                if item.is_ok:
                    print ('Read succeed, PrimaryKey: %s, Attributes: %s' % (item.row.primary_key, item.row.attribute_columns))
                else:
                    print ('Read failed, error code: %s, error message: %s' % (item.error_code, item.error_message))
            print ('Check second table\'s result:')
            for item in table_result_1:
                if item.is_ok:
                    print ('Read succeed, PrimaryKey: %s, Attributes: %s' % (item.row.primary_key, item.row.attribute_columns))
                else: 
                    print ('Read failed, error code: %s, error message: %s' % (item.error_code, item.error_message))
        # 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())
        # Client 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())
    					

    You can obtain the full sample code at BatchGetRow@GitHub.

BatchWriteRow

You can call this operation to insert, modify, or delete several rows of data in one or more tables.

The BatchGetRow operation is a set of multiple PutRow, UpdateRow, and DeleteRow operations. The execution, returning of results, and CU consumption of each operation are carried out independently.

  • Operation
            """
            Description: This operation modifies data from multiple rows.
            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.BatchWriteRowRespons.
            """
            def batch_write_row(self, request):
    					
  • Examples

    The following code provides an example on how to write multiple rows of data.

        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)
    
        # Create a request to write multiple rows.
        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, exceptions may occur if errors such as request parameter errors occur. Some may fail to write. If the operation fails for some 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 inserting 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 result of updating 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 result of deleting 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 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())
        # Client 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())
    					

    You can obtain the full sample code at BatchWriteRow@GitHub.

GetRange

You can call this operation to read data within the specified primary key range.

  • Operation
            """
            Description: This operation reads data from multiple rows within the specified range.
            table_name specifies the name of the table.
            direction specifies the order for this query. Data type: STRING. Valid values: FORWARD and BACKWARD.
            inclusive_start_primary_key specifies the primary key column from which the read starts. If the specified row exists, the row is included in the response.
            exclusive_end_primary_key specifies the primary key column at which the read ends. The end primary key column is excluded from the response even if the row exists.
            columns_to_get: optional. This parameter specifies the list columns to read. If you do not specify this parameter, all columns are read. Type: LIST.
            limit: optional. This parameter specifies the maximum number of rows to read. If you do not specify this parameter, all rows are read.
            column_filter: optional. This parameter specifies the filtering conditions for columns. Only rows that meet the condition are returned.
            max_version: optional. This parameter specifies the maximum number of versions from which data is read. You must specify at least one of max_version and time_range.        time_range: optional. This parameter specifies the range of versions from which data is read. You must specify at least one of max_version and time_range.
            start_column: optional. This parameter specifies the start column to read, which is used to read wide rows.
            end_column: optional. This parameter specifies the end column to read, which is used to read wide rows.
            token: optional. This parameter specifies the start column of a wide row to read next time. This parameter is unavailable.
    
            Response: the results that meet the conditions.
            consumed: an instance of the tablestore.metadata.CapacityUnit class. consumed indicates the number of CUs consumed by this operation.
            next_start_primary_key indicates the primary key column from which you want to start the next GetRange operation. Type: DICT.
            row_list indicates the list of returned rows of data. Format: [Row, ...].
            """
       def get_range(self, table_name, direction,
                      inclusive_start_primary_key,
                      exclusive_end_primary_key,
                      columns_to_get=None,
                      limit=None,
                      column_filter=None,
                      max_version=None,
                      time_range=None,
                      start_column=None,
                      end_column=None,
                      token = None):
    					
  • Examples

    The following code provides an example on how to read data within the specified range:

        # Specify the start primary key column.
        inclusive_start_primary_key = [('uid',INF_MIN), ('gid',INF_MIN)]
    
        # Specify the end primary key column.
        exclusive_end_primary_key = [('uid',INF_MAX), ('gid',INF_MAX)]
    
        # Query all columns.
        columns_to_get = []
    
        # Set limit to 90 to return a maximum of 90 rows of data. If there is a total of 100 rows to return, you can set limit to 90 in the first query. The next_start_primary_key value is not None.
        limit = 90
    
        # Configure the filter.
        cond = CompositeColumnCondition(LogicalOperator.AND)
        cond.add_sub_condition(SingleColumnCondition("address", 'China', ComparatorType.EQUAL))
        cond.add_sub_condition(SingleColumnCondition("age", 50, ComparatorType.LESS_THAN))
    
        try:
            # Call the GetRange operation.
            consumed, next_start_primary_key, row_list, next_token  = client.get_range(
                    table_name, Direction.FORWARD,
                    inclusive_start_primary_key, exclusive_end_primary_key,
                    columns_to_get,
                    limit,
                    column_filter = cond,
                    max_version = 1
                    time_range = (1557125059000, 1557129059000) # The start_time value is equal to or greater than 1557125059000. The end_time value is smaller than 1557129059000.
        )
    
            all_rows = []
            all_rows.extend(row_list)
    
            # If the next_start_primary_key value is not None, there is remaining data to read.
            while next_start_primary_key is not None:
                inclusive_start_primary_key = next_start_primary_key
                consumed, next_start_primary_key, row_list, next_token = client.get_range(
                    table_name, Direction.FORWARD,
                    inclusive_start_primary_key, exclusive_end_primary_key,
                    columns_to_get, limit,
                    column_filter = cond,
                    max_version = 1
            )
                all_rows.extend(row_list)
    
            # Display the primary key and attribute columns.
            for row in all_rows:
                print (row.primary_key, row.attribute_columns)
            print ('Total rows: ', len(all_rows))
        # 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())
        # Client 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())
    					

    You can obtain the full sample code at GetRange@GitHub.