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

插入一行数据(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)

示例

插入一行数据。

	## 主键的第一个主键列是gid,值是整数1,第二个主键列是uid,值是整数101。
    primary_key = [('gid',1), ('uid',101)]
	
	## 属性列包括四个:
	##                        第一个属性列的名字是name,值是字符串John,版本没有指定,使用系统当前时间作为版本号。
	##                        第二个属性列的名字是mobile,值是整数15100000000,版本没有指定,使用系统当前时间作为版本号。
	##                        第三个属性列的名字是address,值是二进制的China,版本没有指定,使用系统当前时间作为版本号。
	##                        第四个属性列的名字是age,值是29.7,版本号为1498184687。
	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())
说明
  • RowExistenceExpectation.IGNORE 表示不管此行是否已经存在,都会插入新数据,如果之前有会被覆盖。

  • RowExistenceExpectation.EXPECT_EXIST 表示只有此行存在时,才会插入新数据,此时,原有数据也会被覆盖。

  • RowExistenceExpectation.EXPECT_NOT_EXIST 表示只有此行不存在时,才会插入数据,否则不执行。

  • 上述示例程序中属性列age的版本为1498184687000,这个值2017年06月23日,如果当前时间 - max_time_deviation(创建表时指定)大于1498184687000值,则PutRow的时候会被禁止。
  • 若执行成功,则不会抛异常,否则会抛异常。

详细代码请参见PutRow@GitHub

读取一行数据(GetRow)

根据给定的主键读取单行数据。

接口

       """
        说明:获取一行数据。
        ``table_name``是对应的表名。
        ``primary_key``是主键,类型为dict。
        ``columns_to_get``是可选参数,表示要获取的列的名称列表,类型为list;如果不填,表示获取所有列。
        ``column_filter``是可选参数,表示读取指定条件的行。
        ``max_version``是可选参数,表示最多读取的版本数。
        ``time_range``是可选参数,表示读取额版本范围或特定版本,和max_version至少存在一个。

        返回:本次操作消耗的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):

示例

读取一行数据。

	#  主键的第一列是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则返回此行。
    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())
说明 查询一行数据时,默认返回这一行所有列的数据。如果想只返回特定行,可以通过 columns_to_get 参数限制。如果将 col0 和 col1 加入到 columns_to_get 中,则只返回 col0 和 col1 的值。

详细代码请参见GetRow@GitHub

更新一行数据(UpdateRow)

更新指定行的数据,如果该行不存在,则新增一行;若该行存在,则根据请求的内容在这一行中新增、修改或者删除指定列的值。

接口

        """
        说明:更新一行数据。
        ``table_name``是对应的表名。
        ``row``表示更新的行数据,包括主键列和属性列,主键列是list;属性列是dict。
        ``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)

示例

更新一行数据。

	#  主键的第一列是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 on\
ly 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)

接口

        """
        说明:删除一行数据。
        ``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): 

示例

删除一行数据。

    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