表格存储提供了PutRow、GetRow、UpdateRow和DeleteRow等单行操作的接口。

如需了解表格存储各场景的应用案例,请参见适用场景

前提条件

  • 已初始化Client,详情请参见初始化
  • 已创建数据表并写入数据。

插入一行数据(PutRow)

PutRow接口用于新写入一行数据。如果该行已存在,则先删除原行数据(原行的所有列以及所有版本的数据),再写入新行数据。

  • 接口
            """
            说明:写入一行数据。返回本次操作消耗的CapacityUnit。
            ``table_name``是数据表名称。
            ``row``是行数据,包括主键和属性列。
            ``condition``表示执行操作前做条件检查,满足条件才执行,是tablestore.metadata.Condition类的实例。支持对行的存在性和列条件进行检查,其中行存在性检查条件包括'IGNORE'、'EXPECT_EXIST'和'EXPECT_NOT_EXIST'。
            ``return_type``表示返回类型,是tablestore.metadata.ReturnType类的实例。目前仅支持返回PrimaryKey,一般用于主键列自增中。
    
            返回:本次操作消耗的CapacityUnit和需要返回的行数据。
            ``consumed``表示消耗的CapacityUnit,是tablestore.metadata.CapacityUnit类的实例。
            ``return_row``表示返回的行数据,可能包括主键、属性列。
            """
            def put_row(self, table_name, row, condition = None, return_type = None)
                        
  • 参数
    参数 说明
    table_name 数据表名称。
    primary_key 行的主键。
    说明
    • 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    • 当主键为自增列时,只需将自增列的值设置为占位符,详情请参见主键列自增
    attribute_columns 行的属性列。
    • 每一项的顺序是属性名、属性值ColumnValue、属性类型ColumnType(可选)、时间戳(可选)。
    • ColumnType可以是INTEGER、STRING(UTF-8编码字符串)、BINARY、BOOLEAN、DOUBLE五种,分别用ColumnType.INTEGER、ColumnType.STRING、ColumnType.BINARY、ColumnType.BOOLEAN、ColumnType.DOUBLE表示,其中BINARY不可省略,其他类型都可以省略。
    • 时间戳即数据的版本号,详情请参见数据版本和生命周期

      数据的版本号可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。

      • 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
      • 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
    说明
    • RowExistenceExpectation.IGNORE表示无论此行是否存在均会插入新数据,如果之前行已存在,则写入数据时会覆盖原有数据。
    • RowExistenceExpectation.EXPECT_EXIST表示只有此行存在时才会插入新数据,写入数据时会覆盖原有数据。
    • RowExistenceExpectation.EXPECT_NOT_EXIST表示只有此行不存在时才会插入数据。
  • 示例

    插入一行数据。

    说明 如下示例中属性列age的版本为1498184687000,此值是2017年06月23日,如果 当前时间-max_time_deviation(max_time_deviation由创建数据表时指定)大于1498184687000时,则PutRow时会被禁止。
        ## 主键的第一个主键列是gid,值是整数1,第二个主键列是uid,值是整数101。
        primary_key = [('gid',1), ('uid',101)]
    
        ## 属性列包括四个:
        ##                        第一个属性列的名字是name,值是字符串John,版本号没有指定,使用系统当前时间作为版本号。
        ##                        第二个属性列的名字是mobile,值是整数15100000000,版本号没有指定,使用系统当前时间作为版本号。
        ##                        第三个属性列的名字是address,值是二进制的China,版本号没有指定,使用系统当前时间作为版本号。
        ##                        第四个属性列的名字是age,值是29.7,指定版本号为1498184687000。
        attribute_columns = [('name','John'), ('mobile',15100000000),('address', bytearray('China')),('female', False), ('age', 29.7, 1498184687000)] 
    
        ## 通过primary_key和attribute_columns构造Row。
        row = Row(primary_key, attribute_columns)
    
        # 设置条件更新,行条件检查为期望行不存在。如果行存在会出现Condition Update Failed错误。
        condition = Condition(RowExistenceExpectation.EXPECT_NOT_EXIST)
    
        try :
            # 调用put_row方法,如果没有指定ReturnType,则return_row为None。
            consumed, return_row = client.put_row(table_name, row, condition)
    
            # 打印此次请求消耗的写CU。
            print ('put row succeed, consume %s write cu.' % consumed.write)
        # 客户端异常,一般为参数错误或者网络异常。
        except OTSClientError as e:
            print "put row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
        # 服务端异常,一般为参数错误或者流控错误。
        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())
                        

    详细代码请参见PutRow@GitHub

读取一行数据(GetRow)

GetRow接口用于读取一行数据。

读取的结果可能有如下两种:
  • 如果该行存在,则返回该行的各主键列以及属性列。
  • 如果该行不存在,则返回中不包含行,并且不会报错。
  • 接口
           """
            说明:获取一行数据。
            ``table_name``是数据表名称。
            ``primary_key``是主键,类型为list。
            ``columns_to_get``是可选参数,表示要获取的列的名称列表,类型为list;如果不填写,表示获取所有列。
            ``column_filter``是可选参数,表示读取指定条件的行。
            ``max_version``是可选参数,表示最多读取的版本数,max_version和time_range必须至少设置一个。
            ``time_range``是可选参数,表示读取版本号范围或特定版本号的数据,max_version和time_range必须至少设置一个。
    
            返回:本次操作消耗的CapacityUnit、主键列和属性列。
            ``consumed``表示消耗的CapacityUnit,是tablestore.metadata.CapacityUnit类的实例。
            ``return_row``表示行数据,包括主键列和属性列,类型都为list,例如[('PK0',value0), ('PK1',value1)]。
            ``next_token``表示宽行读取时下一次读取的位置,编码的二进制。
            """
            def get_row(self, table_name, primary_key, columns_to_get=None,
                    column_filter=None, max_version=None, time_range=None,
                    start_column=None, end_column=None, token=None):
                        
  • 参数
    参数 说明
    table_name 数据表名称。
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    columns_to_get 读取的列集合,列名可以是主键列或属性列。

    如果不设置返回的列名,则返回整行数据。

    说明
    • 查询一行数据时,默认返回此行所有列的数据。如果需要只返回特定行,可以通过设置columns_to_get参数限制。如果将col0和col1加入到columns_to_get中,则只返回col0和col1列的值。
    • 当columns_to_get和column_filter同时使用时,执行顺序是先获取columns_to_get指定的列,再在返回的列中进行条件过滤。
    max_version 最多读取的版本数。
    说明 max_version与time_range必须至少设置一个。
    • 如果仅设置max_version,则返回所有版本中从新到旧最多指定数量版本的数据。
    • 如果仅设置time_range,则返回该范围内所有数据或指定版本数据。
    • 如果同时设置max_version和time_range,则返回版本号范围内从新到旧最多指定数量版本的数据。
    time_range 读取版本号范围或特定版本号的数据。详情请参见TimeRange
    说明 max_version与time_range必须至少设置一个。
    • 如果仅设置max_version,则返回所有版本中从新到旧最多指定数量版本的数据。
    • 如果仅设置time_range,则返回该范围内所有数据或指定版本数据。
    • 如果同时设置max_version和time_range,则返回版本号范围内从新到旧最多指定数量版本的数据。
    • 如果查询一个范围的数据,则需要设置start_time和end_time。start_time和end_time分别表示起始时间戳和结束时间戳,范围为前闭后开区间,即[start_time, end_time)。
    • 如果查询特定版本号的数据,则需要设置specific_time。specific_time表示特定的时间戳。

    specific_time和[start_time, end_time)中只需要设置一个。

    时间戳的单位为毫秒,最小值为0,最大值为INT64.MAX。

    column_filter 使用过滤器,在服务端对读取结果再进行一次过滤,只返回符合过滤器中条件的数据行,详情请参见过滤器
    说明 当columns_to_get和column_filter同时使用时,执行顺序是先获取columns_to_get指定的列,再在返回的列中进行条件过滤。
  • 示例

    读取一行数据。

        # 主键的第一列是uid,值是整数1,第二列是gid,值是整数101。
        primary_key = [('uid',1), ('gid',101)]
    
        # 需要返回的属性列name、growth、type。如果columns_to_get为[],则返回所有属性列。
        columns_to_get = ['name', 'growth', 'type'] 
    
        # 设置过滤器,增加列filter,当growth列的值不等于0.9且name列的值等于'杭州'时,则返回该行。
        cond = CompositeColumnCondition(LogicalOperator.AND)
        cond.add_sub_condition(SingleColumnCondition("growth", 0.9, ComparatorType.NOT_EQUAL))
        cond.add_sub_condition(SingleColumnCondition("name", '杭州', ComparatorType.EQUAL))
    
        try:
            # 调用get_row接口查询,最后一个参数值1表示只需要返回一个版本的值。
            consumed, return_row, next_token = client.get_row(table_name, primary_key, columns_to_get, cond, 1)
            print ('Read succeed, consume %s read cu.' % consumed.read)
            print ('Value of primary key: %s' % return_row.primary_key)
            print ('Value of attribute: %s' % return_row.attribute_columns)
            for att in return_row.attribute_columns:
                # 打印每一列的key、value和version值。
                print ('name:%s\tvalue:%s\ttimestamp:%d' % (att[0], att[1], att[2]))
        # 客户端异常,一般为参数错误或者网络异常。
        except OTSClientError as e:
            print "get row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
        # 服务端异常,一般为参数错误或者流控错误。
        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())
                        

    详细代码请参见GetRow@GitHub

更新一行数据(UpdateRow)

UpdateRow接口用于更新一行数据,可以增加和删除一行中的属性列,删除属性列指定版本的数据,或者更新已存在的属性列的值。如果更新的行不存在,则新增一行数据。
说明 当UpdateRow请求中只包含删除指定的列且该行不存在时,则该请求不会新增一行数据。
  • 接口
            """
            说明:更新一行数据。
            ``table_name``是数据表名称。
            ``row``表示更新的行数据,包括主键列和属性列,主键列和属性列的类型均是list。
            ``condition``表示执行操作前做条件检查,满足条件才执行,是tablestore.metadata.Condition类的实例。支持对行的存在性和列条件进行检查,其中行存在性检查条件包括'IGNORE'、'EXPECT_EXIST'和'EXPECT_NOT_EXIST'。
            ``return_type``表示返回类型,是tablestore.metadata.ReturnType类的实例。目前仅支持返回PrimaryKey,一般用于主键列自增中。
            返回:本次操作消耗的CapacityUnit和需要返回的行数据return_row。
            consumed表示消耗的CapacityUnit,是tablestore.metadata.CapacityUnit类的实例。
            return_row表示需要返回的行数据。
            """
            def update_row(self, table_name, row, condition, return_type = None)
                        
  • 参数
    参数 说明
    table_name 数据表名称。
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    update_of_attribute_columns 更新的属性列。
    • 增加或更新数据时,需要设置属性名、属性值、属性类型(可选)、时间戳(可选)。

      时间戳即数据的版本号,可以由系统自动生成或者自定义,如果不设置此参数,则默认由系统自动生成。详情请参见数据版本和生命周期

      • 当由系统自动生成数据的版本号时,系统默认将当前时间的毫秒单位时间戳(从1970-01-01 00:00:00 UTC计算起的毫秒数)作为数据的版本号。
      • 当自定义数据的版本号时,版本号需要为64位的毫秒单位时间戳且在有效版本范围内。
    • 删除属性列特定版本的数据时,只需要设置属性名和时间戳。

      时间戳是64位整数,单位为毫秒,表示某个特定版本的数据。

    • 删除属性列时,只需要设置属性名。
      说明 删除一行的全部属性列不等同于删除该行,如果需要删除该行,请使用DeleteRow操作。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
  • 示例

    更新一行数据。

        # 主键的第一列是uid,值是整数1,第二列是gid,值是整数101。
        primary_key = [('uid',1), ('gid',101)]
    
        # 更新包括PUT,DELETE和DELETE_ALL三部分。
        # PUT:新增或者更新列值。示例中是新增两列,第一列名字是name,值是David,第二列名字是address,值是Hongkong。
        # DELETE: 删除指定版本号(时间戳)的值。示例中是删除版本为1488436949003的address列的值。
        # DELETE_ALL:删除列。示例中是删除mobile和age两列的所有版本的值。
        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)
    
        # 行条件检查为忽略,无论行是否存在,均会更新。
        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)
        # 客户端异常,一般为参数错误或者网络异常。
        except OTSClientError as e:
            print "update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
        # 服务端异常,一般为参数错误或者流控错误。
        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())
                        

    详细代码请参见UpdateRow@GitHub

删除一行数据(DeleteRow)

DeleteRow接口用于删除一行数据。如果删除的行不存在,则不会发生任何变化。

  • 接口
            """
            说明:删除一行数据。
            ``table_name``是数据表名称。
            ``row``表示行数据,在delete_row中仅包含主键。
            ``condition``表示执行操作前做条件检查,满足条件才执行,是tablestore.metadata.Condition类的实例。支持对行的存在性和列条件进行检查,其中行存在性检查条件包括'IGNORE'、'EXPECT_EXIST'和'EXPECT_NOT_EXIST'。
            返回:本次操作消耗的CapacityUnit和需要返回的行数据return_row。
            consumed表示消耗的CapacityUnit,是tablestore.metadata.CapacityUnit类的实例。
            return_row表示需要返回的行数据。
            """
            def delete_row(self, table_name, row, condition, return_type = None): 
                        
  • 参数
    参数 说明
    table_name 数据表名称。
    primary_key 行的主键。
    说明 设置的主键个数和类型必须和数据表的主键个数和类型一致。
    condition 使用条件更新,可以设置原行的存在性条件或者原行中某列的列值条件,详情请参见条件更新
  • 示例

    删除一行数据。

        primary_key = [('gid',1), ('uid','101')]
        row = Row(primary_key)
        try:
            consumed, return_row = client.delete_row(table_name, row, None)
        # 客户端异常,一般为参数错误或者网络异常。
        except OTSClientError as e:
            print "update row failed, http_status:%d, error_message:%s" % (e.get_http_status(), e.get_error_message())
        # 服务端异常,一般为参数错误或者流控错误。
        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())    
        print ('Delete succeed, consume %s write cu.' % consumed.write) 
                        

    详细代码请参见DeleteRow@GitHub