创建数据表

本文将通过参数说明和示例代码为您介绍如何使用 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)                    

相关文档