表格存储 Python SDK 创建数据表-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 Python SDK 创建数据表，并按需配置表结构、表配置、二级索引和数据加密。

前提条件

功能说明

调用 create_table 方法创建数据表。

def create_table(
    self,
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=None,
    sse_spec=None,
)

以下示例创建主键列为 id 的 example_table 数据表。表中数据永不过期，每个属性列最多保留一个版本。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=1,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

说明

创建数据表后，需等待数据表加载完成再进行数据操作。加载过程通常需要几秒钟。

参数说明

create_table 方法包含以下参数。

名称	类型	说明
table_meta（必选）	`TableMeta`	表结构。
table_options（必选）	`TableOptions`	表配置。
reserved_throughput（必选）	`ReservedThroughput`	预留读写吞吐量。
secondary_indexes（可选）	`List[SecondaryIndexMeta]`	随数据表创建的二级索引列表。
sse_spec（可选）	`SSESpecification`	服务端加密配置。数据加密只能在创建数据表时开启，创建后无法关闭。此功能需要 Python SDK 6.4.0 及以上版本。

表结构

table_meta 的类型为 TableMeta，包含以下参数。

名称	类型	说明
table_name（必选）	`str`	数据表名称。
schema_of_primary_key（必选）	`List[Tuple]`	主键配置。可设置 1～4 个主键列，第一个主键列为分区键。主键列按升序排列，支持 `STRING`、`INTEGER` 和 `BINARY` 类型；非分区键的 `INTEGER` 类型主键列可设置为自增主键列。
defined_columns（可选）	`List[Tuple]`	预定义列配置。预定义列支持 `STRING`、`INTEGER`、`BINARY`、`DOUBLE` 和 `BOOLEAN` 类型，可用于创建二级索引和多元索引。

主键列

table_meta.schema_of_primary_key[] 使用元组配置一个主键列，包含以下元素。

名称	类型	说明
name（必选）	`str`	主键列名称。
type（必选）	`str`	主键列类型。取值为 `STRING`、`INTEGER` 或 `BINARY`。
option（可选）	`PrimaryKeyOption`	主键列选项。将非分区键的 `INTEGER` 类型主键列设置为 `PK_AUTO_INCR` 时，该列为自增主键列。

预定义列

table_meta.defined_columns[] 使用元组配置一个预定义列，包含以下元素。

名称	类型	说明
name（必选）	`str`	预定义列名称。
type（必选）	`str`	预定义列类型。取值为 `STRING`、`INTEGER`、`BINARY`、`DOUBLE` 或 `BOOLEAN`。

表配置

table_options 的类型为 TableOptions，包含以下参数。

名称	类型	说明
time_to_live（可选）	`int`	数据生命周期，单位为秒，默认值为 `-1`。设置为 `-1` 表示数据永不过期；设置为其他值时，最小值为 `86400`（1 天），超出生命周期的数据将被自动清除。使用多元索引或二级索引时，必须设置为 `-1`，或将 `allow_update` 设置为 `False`。
max_version（可选）	`int`	每个属性列最多保留的版本数，默认值为 `1`。使用多元索引或二级索引时，必须设置为 `1`。
max_time_deviation（可选）	`int`	有效版本偏差，单位为秒，默认值为 `86400`（1 天）。写入数据的时间戳与系统当前时间的差值必须在有效版本偏差范围内。属性列数据的有效版本范围为 `[max(数据写入时间-有效版本偏差, 数据写入时间-数据生命周期), 数据写入时间+有效版本偏差)`。
allow_update（可选）	`bool`	是否允许通过 `update_row` 方法更新数据。不设置时，服务端默认允许更新；设置为 `False` 时，无法通过 `update_row` 方法更新数据。

预留读写吞吐量

reserved_throughput 的类型为 ReservedThroughput，包含以下参数。

名称	类型	说明
capacity_unit（必选）	`CapacityUnit`	预留读写吞吐量，单位为 CU。默认读 CU 和写 CU 均为 `0`；仅 CU 模式的高性能型实例支持设置非零值。

容量单元

reserved_throughput.capacity_unit 的类型为 CapacityUnit，包含以下参数。

名称	类型	说明
read（可选）	`int`	预留读吞吐量，单位为 CU，默认值为 `0`。
write（可选）	`int`	预留写吞吐量，单位为 CU，默认值为 `0`。

二级索引

secondary_indexes[] 的类型为 SecondaryIndexMeta，包含以下参数。

名称	类型	说明
index_name（必选）	`str`	索引名称。
primary_key_names（必选）	`List[str]`	索引主键列，可由数据表的主键列和预定义列组成。本地二级索引的第一个主键列必须与数据表的第一个主键列相同。
defined_column_names（可选）	`List[str]`	索引包含的预定义列，必须是数据表中已定义的预定义列。
index_type（可选）	`SecondaryIndexType`	索引类型。取值为 `GLOBAL_INDEX`（默认值，全局二级索引）或 `LOCAL_INDEX`（本地二级索引）。

服务端加密配置

sse_spec 的类型为 SSESpecification，包含以下参数。

名称	类型	说明
enable（可选）	`bool`	是否开启数据加密，默认值为 `False`。
key_type（可选）	`SSEKeyType`	加密类型。取值为 `SSE_KMS_SERVICE`（KMS 服务密钥加密）或 `SSE_BYOK`（BYOK 加密）。开启数据加密时必须设置。
key_id（可选）	`str`	用户主密钥 ID。使用 BYOK 加密时必须设置。
role_arn（可选）	`str`	RAM 角色 ARN。使用 BYOK 加密时必须设置。

场景示例

配置表结构和数据版本

以下示例为数据表添加 name 预定义列，并将每个属性列最多保留的版本数设置为 3。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING")],
    [("name", "STRING")],
)
table_options = TableOptions(
    time_to_live=-1,
    max_version=3,
    max_time_deviation=86400,
    allow_update=True,
)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

client.create_table(table_meta, table_options, reserved_throughput)

创建数据表时添加二级索引

以下示例创建数据表时一并创建本地二级索引。数据表和二级索引的第一个主键列均为 id。

table_meta = TableMeta(
    "example_table",
    [("id", "STRING"), ("device_id", "INTEGER")],
    [("status", "STRING")],
)
table_options = TableOptions(time_to_live=-1, max_version=1)
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))
secondary_indexes = [
    SecondaryIndexMeta(
        "example_local_index",
        ["id", "device_id"],
        ["status"],
        index_type=SecondaryIndexType.LOCAL_INDEX,
    )
]

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    secondary_indexes=secondary_indexes,
)

加密数据表

以下示例分别使用 KMS 服务密钥和 BYOK 加密数据表。

重要

数据加密只能在创建数据表时开启，创建完成后无法关闭。

KMS 服务密钥加密

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_KMS_SERVICE,
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)

BYOK 加密

如需使用 BYOK 加密，请先获取用户主密钥 ID 和 RAM 角色 ARN。具体操作，请参见数据加密。

sse_spec = SSESpecification(
    enable=True,
    key_type=SSEKeyType.SSE_BYOK,
    key_id="key-example",
    role_arn="acs:ram::1234567890123456:role/example-role",
)

client.create_table(
    table_meta,
    table_options,
    reserved_throughput,
    sse_spec=sse_spec,
)