文档

创建数据表

更新时间:

使用CreateTable接口创建数据表时,需要指定数据表的结构信息和配置信息,高性能实例中的数据表还可以根据需要设置预留读/写吞吐量。创建数据表时支持创建一个或者多个索引表。

注意事项

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

  • 创建数据表时必须指定数据表的主键。主键包含1个~4个主键列,每一个主键列都包括名称和类型。

  • 如果要系统设计中存在使用主键列自增功能的场景,例如电商网站的商品ID、大型网站的用户ID、论坛帖子的ID、聊天工具的消息ID等,您可以通过在创建数据表时配置主键列自增实现。具体操作,请参见主键列自增

前提条件

  • 已通过控制台创建表格存储实例。具体操作,请参见创建实例

  • 已初始化Client。具体操作,请参见初始化客户端

接口

"""
说明:根据指定表结构信息创建数据表。

``table_meta``是``tablestore.metadata.TableMeta``类的实例,它包含数据表名称和PrimaryKey的schema。
请参见``TableMeta``类的文档。当创建一个数据表后,通常需要等待几秒钟时间使partition load完成,才能进行各种操作。
``table_options``是``tablestore.metadata.TableOptions``类的实例,它包含time_to_live,max_version和max_time_deviation三个参数。
``reserved_throughput``是``tablestore.metadata.ReservedThroughput``类的实例,表示预留读写吞吐量。
``secondary_indexes``是一个数组,可以包含一个或多个``tablestore.metadata.SecondaryIndexMeta``类的实例,表示要创建的全局二级索引。

返回:无。
"""

def create_table(self, table_meta, table_options, reserved_throughput, secondary_indexes=[]):

参数

请结合下表参数说明和创建数据表APICreateTable中的消息结构介绍进行代码中的参数配置。

参数

说明

table_meta

数据表的结构信息,包括如下内容:

  • table_name:数据表名称。

  • schema_of_primary_key:数据表的主键定义。更多信息,请参见核心组件

    说明

    属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。

    • 表格存储可包含1个~4个主键列。主键列是有顺序的,与用户添加的顺序相同,例如PRIMARY KEY(A, B, C)与PRIMARY KEY(A, C, B)是不同的两个主键结构。表格存储会按照主键的大小对行进行排序。

    • 第一列主键作为分区键。分区键相同的数据会存放在同一个分区内,所以相同分区键下的数据尽量不要超过10 GB,否则会导致单分区过大,无法分裂。另外,数据的读/写访问最好在不同的分区键上均匀分布,有利于负载均衡。

  • defined_columns:预先定义一些非主键列以及其类型,可以作为索引表的属性列或索引列。

table_options

数据表的配置信息。更多信息,请参见数据版本和生命周期

配置信息包括如下内容:

  • time_to_live:数据生命周期,即数据的过期时间。当数据的保存时间超过设置的数据生命周期时,系统会自动清理超过数据生命周期的数据。

    数据生命周期至少为86400秒(一天)或-1(数据永不过期)。

    创建数据表时,如果希望数据永不过期,可以设置数据生命周期为-1;创建数据表后,可以通过UpdateTable接口动态修改数据生命周期。

    单位为秒。

    重要

    如果需要使用索引,则数据生命周期必须满足如下条件中的任意一个。

    • 数据表的数据生命周期为-1(数据永不过期)。

    • 数据表的数据生命周期不为-1时,数据表为禁止更新状态。

  • max_version:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

    创建数据表时,可以自定义属性列的最大版本数;创建数据表后,可以通过UpdateTable接口动态修改数据表的最大版本数。

    重要

    如果需要使用索引,则最大版本数必须设置为1。

  • max_time_deviation:有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。

    属性列的有效版本范围为[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期},数据写入时间+有效版本偏差)

    创建数据表时,如果未设置有效版本偏差,系统会使用默认值86400;创建数据表后,可以通过UpdateTable接口动态修改有效版本偏差。

    单位为秒。

  • allow_update:是否允许UpdateRow相关更新写入操作。默认值为true,表示允许UpdateRow相关更新写入操作;当设置allow_update为false时,表示禁止UpdateRow相关更新写入操作。

    重要

    如果需要使用多元索引生命周期功能,您必须设置此参数为false,即不允许通过UpdateRow更新写入数据。

如果希望修改表的数据生命周期、最大版本数等配置信息,请通过调用UpdateTable接口实现。具体操作,请参见更新表

reserved_throughput

为数据表配置预留读吞吐量或预留写吞吐量。

容量型实例中的数据表的预留读/写吞吐量只能设置为0,不允许预留。

默认值为0,即完全按量计费。

单位为CU。

  • 当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。更多信息,请参见计费概述

  • 当预留读吞吐量或预留写吞吐量设置为0时,表格存储不会为数据表预留相应资源。

secondary_indexes

索引表的结构信息,每个SecondaryIndexMeta包括如下内容:

  • index_name:索引表名称。

  • primary_key_names:索引表的索引列,索引列为数据表主键和预定义列的组合。

    使用本地二级索引时,索引表的第一个主键列必须与数据表的第一个主键列相同。

  • defined_column_names:索引表的属性列,索引表属性列为数据表的预定义列的组合。

  • index_type:索引类型。可选值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。

    • 当不设置index_type或者设置index_type为IT_GLOBAL_INDEX时,表示使用全局二级索引。

      使用全局二级索引时,表格存储以异步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,正常情况下同步延迟达到毫秒级别。

    • 当设置index_type为IT_LOCAL_INDEX时,表示使用本地二级索引。

      使用本地二级索引时,表格存储以同步方式将数据表中被索引的列和主键列的数据自动同步到索引表中,当数据写入数据表后,即可从索引表中查询到数据。

示例

创建数据表时不带索引

以下示例用于创建一个有2个主键列的数据表。该数据表中的数据保留1年(60*60*24*365=31536000秒),最大版本数3,写入时间戳偏移小于1天(86400秒),预留读写吞吐量为(0, 0)

# 创建数据表主键列的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.")
    

详细代码请参见CreateTable@GitHub

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

以下示例用于在创建数据表时配置一个全局二级索引。

# 创建数据表主键列的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)                    

相关文档

  • 如果要读写表中数据,您可以通过调用读写数据接口实现。具体操作,请参见基础数据操作

  • 如果不再需要使用数据表,您可以删除数据表。具体操作,请参见删除数据表