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

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

前提条件

  • 已通过控制台创建实例,详情请参见创建实例
  • 已初始化Client,详情请参见初始化

接口

/// <summary>
 /// 根据表信息(包含数据表名称、主键的定义和预留读写吞吐量)创建数据表。
 /// </summary>
 /// <param name="request">请求参数</param>
 /// <returns>CreateTable的返回,此返回实例是空的,不包含具体信息。
 /// </returns>
        public CreateTableResponse CreateTable(CreateTableRequest request);

        /// <summary>
        /// CreateTable的异步形式。
        /// </summary>
        public Task<CreateTableResponse> CreateTableAsync(CreateTableRequest request);
            

参数

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

配置信息包括如下内容:

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

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

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

    单位为秒。

    说明 如果需要使用索引,则数据生命周期必须设置为-1(数据永不过期)。
  • maxVersions:最大版本数,即属性列能够保留数据的最大版本个数。当属性列数据的版本个数超过设置的最大版本数时,系统会自动删除较早版本的数据。

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

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

    属性列的有效版本范围为[数据写入时间-有效版本偏差,数据写入时间+有效版本偏差)

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

    单位为秒。

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

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

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

单位为CU。

  • 当预留读吞吐量或预留写吞吐量大于0时,表格存储会根据配置为数据表预留相应资源,且数据表创建成功后,将会立即按照预留吞吐量开始计费,超出预留的部分进行按量计费。详情请参见计费概述
  • 当预留读吞吐量或预留写吞吐量设置为0时,表格存储不会为数据表预留相应资源。
indexMetas 索引表的结构信息,每个indexMeta都包括如下内容:
  • indexName:索引表名称。
  • primaryKey:索引表的索引列,索引列为数据表主键和预定义列的任意组合。
  • definedColumns:索引表的属性列,索引表属性列为数据表的预定义列的组合。
  • indexUpdateMode:索引表更新模式,当前只支持IUM_ASYNC_INDEX。
  • indexType:索引表类型,当前只支持IT_GLOBAL_INDEX。

示例

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

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

     //创建主键列的schema,包括PK的个数、名称和类型。
     //第一个PK列为整数,名称是pk0,这个同时也是分区键。
     //第二个PK列为字符串,名称是pk1。
     var primaryKeySchema = new PrimaryKeySchema();
     primaryKeySchema.Add("pk0", ColumnValueType.Integer);
     primaryKeySchema.Add("pk1", ColumnValueType.String);
    
     //通过表名和主键列的schema创建一个tableMeta。
     var tableMeta = new TableMeta("SampleTable", primaryKeySchema);
    
     //设置预留读吞吐量为0,预留写吞吐量为0。
     var reservedThroughput = new CapacityUnit(0, 0);
    
     try
     {
         //构造CreateTableRequest对象。
         var request = new CreateTableRequest(tableMeta, reservedThroughput);
    
         //调用client的CreateTable接口,如果没有抛出异常,则说明执行成功。
         otsClient.CreateTable(request);
    
         Console.WriteLine("Create table succeeded.");
     }
     //如果抛出异常,则说明失败,处理异常。
     catch (Exception ex)
     {
         Console.WriteLine("Create table failed, exception:{0}", ex.Message);
     }
                

    详细代码请参见CreateTable@GitHub

  • 创建数据表(带索引)
            public static void CreateTableWithGlobalIndex()
            {
                //创建数据表,两列主键为Pk1、Pk2,预定义列为Col1、Col2。
                //创建索引表,索引表中Col1放Pk0。
                OTSClient otsClient = Config.GetClient();
    
                Console.WriteLine("Start create table with globalIndex...");
                PrimaryKeySchema primaryKeySchema = new PrimaryKeySchema
                    {
                        { Pk1, ColumnValueType.String },
                        { Pk2, ColumnValueType.String }
                    };
                TableMeta tableMeta = new TableMeta(TableName, primaryKeySchema);
                tableMeta.DefinedColumnSchema = new DefinedColumnSchema {
                       { Col1, DefinedColumnType.STRING},
                       { Col2, DefinedColumnType.STRING}
                    };
    
                IndexMeta indexMeta = new IndexMeta(IndexName);
                indexMeta.PrimaryKey = new List<string>() { Col1 };
                indexMeta.DefinedColumns = new List<string>() { Col2 };
                //indexMeta.IndexType = IndexType.IT_GLOBAL_INDEX;
                //indexMeta.IndexUpdateModel = IndexUpdateMode.IUM_ASYNC_INDEX;
    
                List<IndexMeta> indexMetas = new List<IndexMeta>() { };
                indexMetas.Add(indexMeta);
    
                CapacityUnit reservedThroughput = new CapacityUnit(0, 0);
                CreateTableRequest request = new CreateTableRequest(tableMeta, reservedThroughput, indexMetas);
                otsClient.CreateTable(request);
    
                Console.WriteLine("Table is created: " + TableName);
            }