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

说明
  • 创建数据表后需要几秒钟进行加载,在此期间对该数据表的读/写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
  • 创建数据表时必须指定数据表的主键。主键包含1个~4个主键列,每一个主键列都有名称和类型。

前提条件

  • 已通过控制台创建实例。具体操作,请参见创建实例
  • 已初始化Client。具体操作,请参见初始化

接口

  //说明:根据指定的表结构信息创建数据表。
  //request是CreateTableRequest类的实例,它包含TableMeta和TableOption以及ReservedThroughput。
  //请参见TableMeta类的文档。
  //当创建一个数据表后,通常需要等待几秒钟时间使partition load完成,才能进行各种操作。
  //返回:CreateTableResponse
        CreateTable(request *CreateTableRequest) (*CreateTableResponse, error)       

参数

参数说明
TableMeta数据表的结构信息,包括如下内容:
  • TableName:数据表名称。
  • PrimaryKey:数据表的主键定义。更多信息,请参见主键和属性
    说明 属性列不需要定义。表格存储每行的数据列都可以不同,属性列的列名在写入时指定。
    • 表格存储可包含1个~4个主键列。主键列是有顺序的,与用户添加的顺序相同,例如PRIMARY KEY(A, B, C)与PRIMARY KEY(A, C, B)是不同的两个主键结构。表格存储会按照主键的大小为行排序,具体请参见表格存储数据模型和查询操作
    • 第一列主键作为分区键。分区键相同的数据会存放在同一个分区内,所以相同分区键下的数据尽量不要超过10 GB,否则会导致单分区过大,无法分裂。另外,数据的读/写访问最好在不同的分区键上均匀分布,有利于负载均衡。
  • DefinedColumns:预先定义一些非主键列以及其类型,可以作为索引表的属性列或索引列。
TableOption数据表的配置信息。更多信息,请参见数据版本和生命周期

配置信息包括如下内容:

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

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

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

    单位为秒。

    说明 如果需要使用索引,则数据生命周期必须满足如下条件中的任意一个。
    • 数据表的数据生命周期为-1(数据永不过期)。
    • 数据表的数据生命周期不为-1时,数据表为禁止更新状态。
  • MaxVersion:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

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

    说明 如果需要使用索引,则最大版本数必须设置为1。
  • DeviationCellVersionInSec:有效版本偏差,即写入数据的时间戳与系统当前时间的偏差允许最大值。只有当写入数据所有列的版本号与写入时时间的差值在数据有效版本偏差范围内,数据才能成功写入。

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

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

    单位为秒。

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

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

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

单位为CU。

  • 当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。更多信息,请参见计费概述
  • 当预留读吞吐量或预留写吞吐量设置为0时,表格存储不会为数据表预留相应资源。
IndexMeta索引表的结构信息,包括如下内容:
  • IndexName:索引表名称。
  • PrimaryKey:索引表的索引列,索引列为数据表主键和预定义列的组合。

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

  • DefinedColumns:索引表的属性列,索引表属性列为数据表的预定义列的组合。
  • IndexType:索引类型。可选值包括IT_GLOBAL_INDEX和IT_LOCAL_INDEX。
    • 当不设置IndexType或者设置IndexType为IT_GLOBAL_INDEX时,表示使用全局二级索引。

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

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

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

示例

  • 创建数据表(不带索引)

    创建一个含有2个主键列,预留读/写吞吐量为(0, 0)的数据表。

    func CreateTableSample(client *tablestore.TableStoreClient, tableName string) {
        createTableRequest := new(tablestore.CreateTableRequest)
        //创建主键列的schema,包括PK的个数、名称和类型。
        //第一个PK列为整数,名称是pk0,此列同时也是分区键。
        //第二个PK列为整数,名称是pk1。
        tableMeta := new(tablestore.TableMeta)
        tableMeta.TableName = tableName
        tableMeta.AddPrimaryKeyColumn("pk0", tablestore.PrimaryKeyType_INTEGER)
        tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
        tableOption := new(tablestore.TableOption)
        tableOption.TimeToAlive = -1
        tableOption.MaxVersion = 3
        reservedThroughput := new(tablestore.ReservedThroughput)
        reservedThroughput.Readcap = 0
        reservedThroughput.Writecap = 0
        createTableRequest.TableMeta = tableMeta
        createTableRequest.TableOption = tableOption
        createTableRequest.ReservedThroughput = reservedThroughput
        response, err := client.CreateTable(createTableRequest)
        if (err != nil) {
            fmt.Println("Failed to create table with error:", err)
        } else {
            fmt.Println("Create table finished")
        }
    }

    详细代码请参见CreateTable@GitHub

  • 创建数据表(带索引且索引类型为全局二级索引)
    func CreateTableWithGlobalIndexSample(client *tablestore.TableStoreClient, tableName string) {
        createTableRequest := new(tablestore.CreateTableRequest)
    
        tableMeta := new(tablestore.TableMeta)
        tableMeta.TableName = tableName
        tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
        tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
        tableMeta.AddDefinedColumn("definedcol1", tablestore.DefinedColumn_STRING)
        tableMeta.AddDefinedColumn("definedcol2", tablestore.DefinedColumn_INTEGER)
    
        indexMeta := new(tablestore.IndexMeta) //新建索引表Meta。
        indexMeta.AddPrimaryKeyColumn("definedcol1") //为索引表添加主键列。设置数据表的definedcol1列作为索引表的主键。
        indexMeta.AddDefinedColumn("definedcol2") //为索引表添加属性列。设置数据表的definedcol2列作为索引表的属性列。
        indexMeta.IndexName = "indexSample"
    
        tableOption := new(tablestore.TableOption)
        tableOption.TimeToAlive = -1 //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
        tableOption.MaxVersion = 1 //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
        reservedThroughput := new(tablestore.ReservedThroughput)
    
        createTableRequest.TableMeta = tableMeta
        createTableRequest.TableOption = tableOption
        createTableRequest.ReservedThroughput = reservedThroughput
        createTableRequest.AddIndexMeta(indexMeta)
    
        _, err := client.CreateTable(createTableRequest)
        if err != nil {
            fmt.Println("Failed to create table with error:", err)
        } else {
            fmt.Println("Create table finished")
        }
    }
  • 创建数据表(带索引且索引类型为本地二级索引)
    func CreateTableWithLocalIndexSample(client *tablestore.TableStoreClient, tableName string) {
        createTableRequest := new(tablestore.CreateTableRequest)
    
        tableMeta := new(tablestore.TableMeta)
        tableMeta.TableName = tableName
        tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
        tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
        tableMeta.AddDefinedColumn("definedcol1", tablestore.DefinedColumn_STRING)
        tableMeta.AddDefinedColumn("definedcol2", tablestore.DefinedColumn_INTEGER)
    
        indexMeta := new(tablestore.IndexMeta) //新建索引表Meta。
        indexMeta.IndexType = IT_LOCAL_INDEX //设置索引类型为本地二级索引(IT_LOCAL_INDEX)。
    
        indexMeta.AddPrimaryKeyColumn("pk1") //为索引表添加主键列。索引表的第一列主键必须与数据表的第一列主键相同。
        indexMeta.AddPrimaryKeyColumn("definedcol1") //为索引表添加主键列。设置数据表的definedcol1列作为索引表的主键。
        indexMeta.AddDefinedColumn("definedcol2") //为索引表添加属性列。设置数据表的definedcol2列作为索引表的属性列。
        indexMeta.IndexName = "indexSample"
    
        tableOption := new(tablestore.TableOption)
        tableOption.TimeToAlive = -1 //数据的过期时间,单位为秒,-1表示永不过期。带索引表的数据表数据生命周期必须设置为-1。
        tableOption.MaxVersion = 1 //保存的最大版本数,1表示每列上最多保存一个版本即保存最新的版本。带索引表的数据表最大版本数必须设置为1。
        reservedThroughput := new(tablestore.ReservedThroughput)
    
        createTableRequest.TableMeta = tableMeta
        createTableRequest.TableOption = tableOption
        createTableRequest.ReservedThroughput = reservedThroughput
        createTableRequest.AddIndexMeta(indexMeta)
    
        _, err := client.CreateTable(createTableRequest)
        if err != nil {
            fmt.Println("Failed to create table with error:", err)
        } else {
            fmt.Println("Create table finished")
        }
    }