AI 助理
备案控制台
文档
输入文档关键字查找
首页 表格存储 开发参考 SDK参考 Python SDK 表操作 创建数据表

创建数据表

更新时间：
产品详情
我的收藏

本文将通过参数说明和示例代码为您介绍如何使用 Python SDK 创建数据表。在创建数据表时，您需要指定数据表的结构信息和配置信息。CU 模式（原按量模式）下高性能型实例中的数据表还可以根据需要设置预留读写吞吐量。

注意事项

  • 创建数据表后需要几秒钟进行加载，在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。

  • 如果您有主键数据自增的需求，例如电商网站的商品 ID、论坛帖子的 ID 等场景，可以在创建数据时配置主键列自增。具体操作，请参见主键列自增。

前提条件

接口

"""
说明：根据指定表结构信息创建数据表。
当创建一个数据表后，通常需要等待几秒钟时间使partition load完成，才能进行各种操作。
返回：无。
"""
def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[])

参数说明

参数

说明

table_meta（必选）

数据表的结构信息，包括如下内容：

  • table_name（必选）：数据表名称。

  • schema_of_primary_key（必选）：数据表的主键定义。更多信息，请参见核心组件。

    • 主键数据类型可以为 STRING、INTEGER 或 BINARY。

    • 可以设置 1~4 个主键列。表格存储将按照设置的顺序生成主键，默认按升序进行排序。

    • 第一个主键列将作为分区键。

  • defined_columns（可选）：预定义列信息。数据类型可以为 STRING、INTEGER、BINARY、DOUBLE 或 BOOLEAN。

    说明

    • 预定义列是预先定义的一些非主键列，通常被用作二级索引的主键列或预定义列，以实现快速查询数据的需求。

    • 属性列在创建表时无需定义，您可以在写入数据时为每行数据指定不同的属性列和列名。

table_options（必选）

数据表的配置信息，包括如下内容：

  • time_to_live（可选）：数据生命周期，即数据的过期时间，单位为秒。当数据的保存时间超过设置的数据生命周期时，系统会自动清理超过数据生命周期的数据。

    默认值为 -1（表示数据永不过期）。数据生命周期的取值最低为 86400 秒（一天），也可设置为 -1（永不过期）。

    重要

    如果要使用多元索引或二级索引，必须将数据生命周期设置为 -1，或者将 allow_update 参数设置为 false。

  • max_version（可选）：最大版本数，即属性列能够保留数据的最大版本个数。

    默认值为 1，表示每列上最多保存一个版本，即保存最新的版本。

    重要

    如果要使用多元索引或二级索引，最大版本数必须设置为 1。

  • max_time_deviation（可选）：有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值，单位为秒。

    默认值 86400 秒（一天）。属性列的有效取值范围是一个左闭右开的区间：[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期}，数据写入时间+有效版本偏差)。

  • allow_update（可选）：是否允许更新。默认为true。

    重要

    如果要使用多元索引的生命周期功能，必须设置此参数为 false。如果您需要更新数据，可使用 PutRow 接口写入数据。

secondary_indexes（可选）

索引列表。每个索引包含以下内容：

  • index_name（必选）：索引名称。

  • primary_key_names（必选）：索引的主键列。可以由数据表的主键列和预定义列组成。

    重要

    使用本地二级索引时，索引第一个主键列必须是数据表的第一个主键列。

  • defined_column_names（可选）：索引的预定义列。可以由数据表的预定义列组成。

  • index_type（可选）：索引类型。取值范围如下：

    • GLOBAL_INDEX （默认值）：全局二级索引。

    • LOCAL_INDEX：本地二级索引。

reserved_throughput（必选）

预留读写吞吐量，单位为 CU。默认值为 0。

重要

仅 CU 模式下高性能型实例支持设置数据表的预留读写吞吐量为非零值。

示例

创建数据表

以下示例用于创建数据表。

# 创建数据表主键列的schema，包括主键的个数、名称和类型。
# 第一个主键列为整型，名称是pk0，该列同时也是分区键。
# 第二个主键列为整型，名称是pk1。其他可选的类型包括STRING和BINARY，此处使用INTEGER。
schema_of_primary_key = [('pk0', 'INTEGER'), ('pk1', 'INTEGER')]

# 通过数据表名称和主键列的schema创建一个tableMeta。
table_meta = TableMeta('<table_name>', schema_of_primary_key)

# 创建TableOptions，数据保留时间为31536000秒，数据超过保留时间后表格存储会自动删除超期数据，最大保存3个版本，写入时指定的版本值和当前时间相差不能超过86400秒（即1天）。
table_options = TableOptions(31536000, 3, 86400)

# 设置预留读吞吐量为0，预留写吞吐量为0。
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# 调用client的create_table接口，如果没有抛出异常，则说明执行成功。
try:
    ots_client.create_table(table_meta, table_options, reserved_throughput)
    print("create table succeeded.")
# 如果抛出异常，则说明执行失败，处理异常。
except Exception:
    print("create table failed.")

创建数据表时配置二级索引

创建数据表时配置全局二级索引

以下示例用于同时创建数据表和全局二级索引。

# 创建数据表主键列的schema，包括主键的个数、名称和类型。
schema_of_primary_key = [('gid', 'INTEGER'), ('uid', 'STRING')]

# 配置数据表的预定义列。
defined_columns = [('i', 'INTEGER'), ('bool', 'BOOLEAN'), ('d', 'DOUBLE'), ('s', 'STRING'), ('b', 'BINARY')]

# 通过数据表名称和主键列的schema创建一个tableMeta。
table_meta = TableMeta('<table_name>', schema_of_primary_key, defined_columns)

# 创建TableOptions，数据永不过期，只保存1个版本数据。
table_option = TableOptions(-1, 1)

# 设置预留读吞吐量为0，预留写吞吐量为0。
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# 设置二级索引的索引名称、主键列和属性列。索引类型默认为全局二级索引。
secondary_indexes = [
    SecondaryIndexMeta('index1', ['i', 's'], ['bool', 'b', 'd']),
]

# 调用client的create_table接口，如果没有抛出异常，则说明执行成功。
ots_client.create_table(table_meta, table_option, reserved_throughput, secondary_indexes)

创建数据表时配置本地二级索引

以下示例用于同时创建数据表和本地二级索引。

# 创建数据表主键列的schema，包括主键的个数、名称和类型。
schema_of_primary_key = [('gid', 'INTEGER'), ('uid', 'STRING')]

# 配置数据表的预定义列。
defined_columns = [('i', 'INTEGER'), ('bool', 'BOOLEAN'), ('d', 'DOUBLE'), ('s', 'STRING'), ('b', 'BINARY')]

# 通过数据表名称和主键列的schema创建一个tableMeta。
table_meta = TableMeta('<table_name>', schema_of_primary_key, defined_columns)

# 创建TableOptions，数据永不过期，只保存1个版本数据。
table_option = TableOptions(-1, 1)

# 设置预留读吞吐量为0，预留写吞吐量为0。
reserved_throughput = ReservedThroughput(CapacityUnit(0, 0))

# 设置二级索引的索引名称、主键列、索引列和索引类型。其中设置索引类型为本地二级索引。
secondary_indexes = [
    SecondaryIndexMeta('index1', ['gid', 's'], ['bool', 'b', 'd'],index_type= SecondaryIndexType.LOCAL_INDEX),
]

# 调用client的create_table接口，如果没有抛出异常，则说明执行成功。
ots_client.create_table(table_meta, table_option, reserved_throughput, secondary_indexes)

相关文档

上一篇：表操作下一篇：更新表配置
文档推荐