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

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

注意事项

创建数据表后需要几秒钟进行加载，在此期间对该数据表的读写数据操作均会失败。请等待数据表加载完毕后再进行数据操作。
表格存储提供数据加密存储功能，如果您有高安全性或合规性要求，可以在创建数据表时配置加密相关参数。具体操作，请参见创建加密表。
如果您有主键数据自增的需求，例如电商网站的商品 ID、论坛帖子的 ID 等场景，可以在创建数据时配置主键列自增。具体操作，请参见主键列自增。

前提条件

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

接口

//说明：根据指定表结构信息创建数据表。
//当创建一个数据表后，通常需要等待几秒钟时间使partition load完成，才能进行各种操作。
//返回：CreateTableResponse
CreateTable(request *CreateTableRequest) (*CreateTableResponse, error)

参数说明

request包含以下参数：

参数	说明
TableMeta（必选）	数据表的结构信息，包括如下内容： TableName（必选）：数据表名称。 SchemaEntry（必选）：数据表的主键定义。更多信息，请参见核心组件。主键数据类型可以为 STRING、INTEGER 或 BINARY。可以设置 1~4 个主键列。表格存储将按照设置的顺序生成主键，默认按升序进行排序。第一个主键列将作为分区键。 DefinedColumns（可选）：预定义列信息。数据类型可以为 STRING、INTEGER、BINARY、DOUBLE 或 BOOLEAN。说明预定义列是预先定义的一些非主键列，通常被用作二级索引的主键列或预定义列，以实现快速查询数据的需求。属性列在创建表时无需定义，您可以在写入数据时为每行数据指定不同的属性列和列名。
TableOption（必选）	数据表的配置信息，包括如下内容： TimeToAlive（必选）：数据生命周期，即数据的过期时间，单位为秒。数据生命周期的取值最低为 86400 秒（一天），也可设置为 -1（永不过期）。重要如果要使用多元索引或二级索引，必须将数据生命周期设置为 -1，或者将 AllowUpdate 参数设置为 false。 MaxVersion（必选）：最大版本数，即属性列能够保留数据的最大版本个数。重要如果要使用多元索引或二级索引，最大版本数必须设置为 1。 DeviationCellVersionInSec（可选）：有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值，单位为秒。默认值 86400 秒（一天）。属性列的有效取值范围是一个左闭右开的区间：`[max{数据写入时间-有效版本偏差,数据写入时间-数据生命周期}，数据写入时间+有效版本偏差)`。 AllowUpdate（可选）：是否允许更新。默认为true。重要如果要使用多元索引的生命周期功能，必须设置此参数为 false。如果您需要更新数据，可使用 PutRow 接口写入数据。
IndexMetas（可选）	索引列表。每个索引包含以下内容： IndexName（必选）：索引名称。 PrimaryKey（必选）：索引的主键列。可以由数据表的主键列和预定义列组成。重要使用本地二级索引时，索引第一个主键列必须是数据表的第一个主键列。 DefinedColumns（可选）：索引的预定义列。可以由数据表的预定义列组成。 IndexType（可选）：索引类型。取值范围如下： IT_GLOBAL_INDEX （默认值）：全局二级索引。 IT_LOCAL_INDEX：本地二级索引。
ReservedThroughput（必选）	预留读写吞吐量，单位为 CU。默认值为 0。重要仅 CU 模式下高性能型实例支持设置数据表的预留读写吞吐量为非零值。
StreamSpec（可选）	数据表的 Stream 配置信息，包括如下内容： EnableStream（可选）：是否开启 stream。默认值为 false，即不开启 stream。 ExpirationTime（可选）：stream 过期时间，表示增量日志过期时长。单位为小时，最大值为 168 小时（7 天）。说明开启 stream 时，必须设置 expirationTime 参数。
SSESpecification（可选）	数据表的加密配置。重要数据表创建后，不支持修改加密相关配置。
EnableLocalTxn（可选）	是否开启局部事务功能。默认值为 false，表示不开启局部事务功能。重要主键列自增和局部事务功能无法同时使用，如果您配置了主键列自增，即使开启局部事务也不会生效。如果创建数据表时未开启局部事务功能，创建数据表后需要使用该功能，请提交工单进行申请或者加入钉钉群 23307953（表格存储技术交流群-3）进行咨询。

示例

创建数据表

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

func CreateTableSample(client *tablestore.TableStoreClient, tableName string) {
	createTableRequest := new(tablestore.CreateTableRequest)

	tableMeta := new(tablestore.TableMeta)
	//设置数据表名称。
	tableMeta.TableName = tableName
	//为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型），其中pk1主键列为分区键，pk2主键列为自增列。
	tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
	tableMeta.AddPrimaryKeyColumnOption("pk2", tablestore.PrimaryKeyType_INTEGER, tablestore.AUTO_INCREMENT)

	tableOption := new(tablestore.TableOption)
	//数据的过期时间，-1表示永不过期。
	tableOption.TimeToAlive = -1
	//最大版本数，属性列值最多保留1个版本，即保存最新的版本。
	tableOption.MaxVersion = 1
	//有效版本偏差，即写入数据的时间戳与系统当前时间的偏差允许最大值为86400秒（1天）。
	tableOption.DeviationCellVersionInSec = 86400

	//设置预留读写吞吐量，容量型实例下的数据表只能设置为0，高性能型实例下的数据表可以设置为非零值。
	reservedThroughput := new(tablestore.ReservedThroughput)
	reservedThroughput.Readcap = 0
	reservedThroughput.Writecap = 0
	
	createTableRequest.TableMeta = tableMeta
	createTableRequest.TableOption = tableOption
	createTableRequest.ReservedThroughput = reservedThroughput
	_, err := client.CreateTable(createTableRequest)
	if err != nil {
		fmt.Println("Failed to create table with error:", err)
	} else {
		fmt.Println("Create table finished")
	}
}

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

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

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

func CreateTableWithGlobalIndexSample(client *tablestore.TableStoreClient, tableName string) {
	createTableRequest := new(tablestore.CreateTableRequest)

	tableMeta := new(tablestore.TableMeta)
	//设置数据表名称。
	tableMeta.TableName = tableName
	//为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
	tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
	tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
	//为数据表添加预定义列。预定义列为defcol1（String类型）和defcol2（Integer类型）。
	tableMeta.AddDefinedColumn("defcol1", tablestore.DefinedColumn_STRING)
	tableMeta.AddDefinedColumn("defcol2", tablestore.DefinedColumn_INTEGER)

	tableOption := new(tablestore.TableOption)
	//数据永不过期，-1表示永不过期。
	tableOption.TimeToAlive = -1
	//最大版本数，属性列值最多保留1个版本，即保存最新的版本。。
	tableOption.MaxVersion = 1
	reservedThroughput := new(tablestore.ReservedThroughput)

	//全局二级索引
	indexMeta := new(tablestore.IndexMeta)
	//设置索引名称。
	indexMeta.IndexName = "<INDEX_NAME>"
	//为索引添加主键列。主键列为defcol1、pk1和pk2
	indexMeta.AddPrimaryKeyColumn("defcol1")
	indexMeta.AddPrimaryKeyColumn("pk1")
	indexMeta.AddPrimaryKeyColumn("pk2")
	//为索引添加预定义列。预定义列为defcol2。
	indexMeta.AddDefinedColumn("defcol2")
	
	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
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
    tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
    tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)
    //为数据表添加预定义列。预定义列为defcol1（String类型）和defcol2（Integer类型）。
    tableMeta.AddDefinedColumn("defcol1", tablestore.DefinedColumn_STRING)
    tableMeta.AddDefinedColumn("defcol2", tablestore.DefinedColumn_INTEGER)

    tableOption := new(tablestore.TableOption)
    //数据永不过期，-1表示永不过期。
    tableOption.TimeToAlive = -1
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    tableOption.MaxVersion = 1
    reservedThroughput := new(tablestore.ReservedThroughput)

    //本地二级索引
    indexMeta := new(tablestore.IndexMeta)
    //设置索引名称。
    indexMeta.IndexName = "<INDEX_NAME>"
    //设置索引类型为本地二级索引（IT_LOCAL_INDEX）。
    indexMeta.IndexType = tablestore.IT_LOCAL_INDEX 
    //为索引添加主键列。主键列为pk1、defcol1和pk2。
    indexMeta.AddPrimaryKeyColumn("pk1") 
    indexMeta.AddPrimaryKeyColumn("defcol1") 
    indexMeta.AddPrimaryKeyColumn("pk2") 
    //为索引添加预定义列。预定义列为defcol2。
    indexMeta.AddDefinedColumn("defcol2")

    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 CreateTableWithEnableLocalTxnSample(client *tablestore.TableStoreClient, tableName string) {
    createTableRequest := new(tablestore.CreateTableRequest)

    tableMeta := new(tablestore.TableMeta)
    //设置数据表名称。
    tableMeta.TableName = tableName
    //为数据表添加主键列。主键为pk1（String类型）和pk2（Integer类型）。
    tableMeta.AddPrimaryKeyColumn("pk1", tablestore.PrimaryKeyType_STRING)
    tableMeta.AddPrimaryKeyColumn("pk2", tablestore.PrimaryKeyType_INTEGER)

    tableOption := new(tablestore.TableOption)
    //数据的过期时间，-1表示永不过期。
    tableOption.TimeToAlive = -1
    //最大版本数，属性列值最多保留1个版本，即保存最新的版本。
    tableOption.MaxVersion = 1
    reservedThroughput := new(tablestore.ReservedThroughput)

    //开启局部事务。如果数据表配置了主键自增列，则开启局部事务配置不会生效。
    enableLocalTxn := proto.Bool(true)

    createTableRequest.TableMeta = tableMeta
    createTableRequest.TableOption = tableOption
    createTableRequest.ReservedThroughput = reservedThroughput
    createTableRequest.EnableLocalTxn = enableLocalTxn
    _, err := client.CreateTable(createTableRequest)
    if err != nil {
        fmt.Println("Failed to create table with error:", err)
    } else {
	fmt.Println("Create table finished")
    }
}

注意事项

前提条件

接口

参数说明

示例

创建数据表

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

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

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

创建数据表时开启局部事务

相关文档