Write a row - Tablestore SDK for Python - Tablestore - Alibaba Cloud Documentation Center

Use Tablestore SDK for Python to write a row and optionally specify a write condition, data version, or local transaction.

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Function description

Call put_row to write a row. If the primary key already exists, the method overwrites the row. Otherwise, the method creates a row.

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

The following example writes a row whose primary key is ("device", 1) to example_table.

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)

Parameters

The put_row method contains the following parameters.

Name	Type	Description
table_name (required)	`str`	The name of the table.
row (required)	`Row`	The primary key and attribute columns to write.
condition (optional)	`Condition`	The write condition. By default, row existence is not checked. For more information, see Use conditional updates.
return_type (optional)	`ReturnType`	The return type. `RT_NONE`, the default value, returns no data. `RT_PK` returns the primary key and is typically used to obtain the value of an auto-increment primary key column.
transaction_id (optional)	`str`	The local transaction ID. Specify this parameter only for writes in a local transaction. For more information, see Use local transactions.

Row data

The row parameter is of the Row type and contains the following parameters.

Name	Type	Description
primary_key (required)	`List[Tuple]`	The primary key. The names, order, number, and types of the primary key columns must match the primary key schema of the table.
attribute_columns (optional)	`List[Tuple]`	The attribute columns. Each element is `(column_name, column_value)` or `(column_name, column_value, timestamp)`. Attribute column values support the `str`, `int`, `bytes`, `float`, and `bool` types. If `timestamp` is omitted, the server generates a data version.

Response

put_row returns the following values.

Field	Type	Description
consumed	`CapacityUnit`	The read and write CUs consumed by the operation.
return_row	`Row`	The returned row. If `return_type` is `RT_PK`, the primary key is returned. Otherwise, this value is `None`.

Examples

Write multiple attribute columns

The following example writes attribute columns of the string, integer, and Boolean types.

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),
)

Specify data versions

The third element of an attribute column tuple specifies the data version in milliseconds. The version must be within the valid version range allowed by the table.

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),
)

Obtain an auto-increment primary key value

When you write to a table that has an auto-increment primary key column, set the column value to PK_AUTO_INCR and return_type to RT_PK. For more information about the requirements, see Use an auto-increment primary key column.

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)