表格存储 Python SDK 写入单行数据 - 表格存储

使用 Python SDK 写入单行数据，并按需设置写入条件、数据版本号和局部事务。

前提条件

功能说明

调用 put_row 方法写入单行数据。如果主键已存在，该方法覆盖该行；如果主键不存在，该方法新增一行。

def put_row(
    self,
    table_name,
    row,
    condition=None,
    return_type=None,
    transaction_id=None,
)

以下示例向 example_table 写入主键为 ("device", 1) 的一行数据。

primary_key = [("partition", "device"), ("id", 1)]
attribute_columns = [("name", "thermometer"), ("status", "online")]
row = Row(primary_key, attribute_columns)
condition = Condition(RowExistenceExpectation.IGNORE)

consumed, return_row = client.put_row(
    "example_table",
    row,
    condition,
)
print("Write CU: %s" % consumed.write)

参数说明

put_row 方法包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
row（必选）	`Row`	待写入的主键和属性列。
condition（可选）	`Condition`	写入条件。默认不判断行是否存在。有关条件的配置方法，请参见条件更新。
return_type（可选）	`ReturnType`	返回类型。`RT_NONE`（默认值）表示不返回数据；`RT_PK` 表示返回主键列，常用于获取自增主键值。
transaction_id（可选）	`str`	局部事务 ID。仅在局部事务内写入数据时设置。有关局部事务的使用方法，请参见局部事务。

行数据

row 的类型为 Row，包含以下参数。

名称	类型	说明
primary_key（必选）	`List[Tuple]`	主键信息。主键列的名称、顺序、数量和类型必须与数据表的主键结构一致。
attribute_columns（可选）	`List[Tuple]`	属性列列表。每个元素为 `(column_name, column_value)` 或 `(column_name, column_value, timestamp)`。属性列值支持 `str`、`int`、`bytes`、`float` 和 `bool` 类型。未指定 `timestamp` 时，服务端自动生成数据版本号。

返回值

put_row 返回以下值。

字段	类型	说明
consumed	`CapacityUnit`	本次操作消耗的读写 CU。
return_row	`Row`	返回的行数据。`return_type` 为 `RT_PK` 时返回主键列，否则为 `None`。

场景示例

写入多个属性列

以下示例写入字符串、整数和布尔类型的属性列。

primary_key = [("partition", "device"), ("id", 2)]
attribute_columns = [
    ("name", "humidity-sensor"),
    ("temperature", 26),
    ("enabled", True),
]
row = Row(primary_key, attribute_columns)

client.put_row(
    "example_table",
    row,
    Condition(RowExistenceExpectation.IGNORE),
)

指定数据版本号

属性列元组的第三个元素用于指定数据版本号，单位为毫秒。版本号必须处于数据表允许的有效版本范围内。

timestamp = int(time.time() * 1000)
primary_key = [("partition", "device"), ("id", 3)]
attribute_columns = [
    ("status", "online", timestamp),
    ("temperature", 25, timestamp),
]
row = Row(primary_key, attribute_columns)

client.put_row(
    "example_table",
    row,
    Condition(RowExistenceExpectation.IGNORE),
)

获取自增主键值

向包含自增主键列的数据表写入数据时，将该列的值设置为 PK_AUTO_INCR，并将 return_type 设置为 RT_PK。有关自增主键列的配置要求，请参见主键列自增。

primary_key = [("partition", "device"), ("id", PK_AUTO_INCR)]
row = Row(primary_key, [("name", "pressure-sensor")])

consumed, return_row = client.put_row(
    "example_table",
    row,
    Condition(RowExistenceExpectation.IGNORE),
    ReturnType.RT_PK,
)
print(return_row.primary_key)