This topic describes how to create a data table by calling the CreateTable operation. When you call the CreateTable operation, you must specify the schema information and configuration information of the data table. You can set reserved read throughput and reserved write throughput for data tables in high-performance instances based on your business requirements. You can create one or more index tables when you create a data table.

Note
  • After a data table is created, it takes several seconds to load the data table. During this period, read and write operations performed on the table may fail. Perform operations on the data table after the data table is loaded.
  • You must specify the primary key when you create a data table. A primary key can contain one to four primary key columns. Each primary key column has a name and a data type.

Prerequisites

  • An instance is created in the console. For more information, see Create instances.
  • An OTSClient instance is initialized. For more information, see Initialization.

API operations

/// <summary>
/// Create a table based on table information including the table name, primary key schema, and reserved read and write throughput. 
/// </summary>
/// <param name="request">Request parameter</param>
/// <returns>Information returned by CreateTable. The result is null. 
/// </returns>
public CreateTableResponse CreateTable(CreateTableRequest request);

/// <summary>
/// Asynchronous mode of CreateTable. 
/// </summary>
public Task<CreateTableResponse> CreateTableAsync(CreateTableRequest request);

Parameters

ParameterDescription
tableMetaThe schema information about the data table. The schema information contains the following items:
  • tableName: the name of the data table.
  • primaryKeySchema: the schema of the primary key for the table. For more information, see Primary keys and attributes.
    Note You do not need to specify the schema for attribute columns. Different rows in a Tablestore table can have different attribute columns. You can specify the names of attribute columns when you write data to the attribute columns.
    • The primary key of a data table can contain one to four primary key columns. Primary key columns are sorted in the order in which they are added. For example, PRIMARY KEY (A, B, C) and PRIMARY KEY (A, C, B) have different primary key schemas. Tablestore sorts rows based on the values of all primary key columns.
    • The first primary key column is the partition key. Data that has the same partition key is stored in the same partition. Therefore, we recommend that the size of data with the same partition key be smaller than or equal to 10 GB. Otherwise, a single partition may be too large to split. We recommend that you evenly distribute requests to read data from and write data to different partition keys for load balancing.
  • definedColumnSchema: the predefined columns of the table and the data types of the predefined column values. Primary key columns cannot be specified as predefined columns. You can use predefined columns as the index columns or attribute columns of index tables.
tableOptionsThe configuration information about the data table. For more information, see Data versions and TTL.

The configuration information contains the following items:

  • timeToLive: the period for which data in the data table can be retained. This period is the validity period of data. If the retention period exceeds the timeToLive value, Tablestore automatically deletes expired data.

    The minimum timeToLive value is 86400, which is equal to one day. A value of -1 indicates that data never expires.

    When you create a data table, you can set timeToLive to -1. This way, the data in the table never expires. After the table is created, you can call the UpdateTable operation to change the timeToLive value.

    Unit: seconds.

    Note If you want to create an index table for the data table, the timeToLive parameter must meet one of the following requirements:
    • The timeToLive parameter of the data table is set to -1, which means that data in the data table never expires.
    • The timeToLive parameter of the data table is set to a value other than -1 and update operations on the data table are prohibited.
  • maxVersions: the maximum number of versions of data that can be retained for a single attribute column. If the number of versions of data in attribute columns exceeds the value of this parameter, the system deletes data of earlier versions.

    When you create a data table, you can specify the maximum number of versions that can be retained for the data in an attribute column. After the data table is created, you can call the UpdateTable operation to modify the maxVersions value for the data table.

    Note If you want to create an index table for a data table, you must set maxVersions to 1 for the data table.
  • deviationCellVersionInSec: the max version offset, which is the maximum difference between the current system time and the timestamp of the written data. The difference between the version number and the time at which the data is written must be less than or equal to the value of deviationCellVersionInSec. Otherwise, an error occurs when the data is written.

    The valid version range of data in an attribute column is calculated by using the following formula: Valid version range = [max{Data written time - Max version offset, Data written time - TTL value}, Data written time + Max version offset).

    When you create a data table, Tablestore uses the default value of 86400 if you do not specify a max version offset. After the data table is created, you can call the UpdateTable operation to modify the deviationCellVersionInSec value.

    Unit: seconds.

  • allowUpdate: specifies whether to allow the UpdateRow operation. The default value is true, which indicates that the UpdateRow operation is allowed. If you set allowUpdate to false, the UpdateRow operation is prohibited.
reservedThroughputThe reserved read throughput and reserved write throughput of the data table.

You can set the reserved read throughput or reserved write throughput only to 0 for data tables in capacity instances. Reserved throughput does not apply to these instances.

The default value 0 indicates that you are billed for all throughput on a pay-as-you-go basis.

Unit: capacity unit (CU).

  • If you set the reserved read throughput or reserved write throughput to a value that is greater than 0 for a data table, Tablestore reserves resources for the data table. After you create the data table, Tablestore charges you for the reserved throughput. You are charged for additional throughput based on the pay-as-you-go billing method. For more information, see Billing overview.
  • If you set the reserved read throughput or reserved write throughput to 0, Tablestore does not reserve resources for the data table.
indexMetasThe schema information about the index table. Each indexMeta contains the following items:
  • indexName: the name of the index table.
  • primaryKey: the primary key of the index table, which is a combination of all primary key columns and a random number of predefined columns of the data table.
  • definedColumns: the attribute columns of the index table. The attribute columns are a combination of predefined columns of the data table.
  • indexUpdateMode: the update mode of the index table. Only IUM_ASYNC_INDEX is supported.
  • indexType: the type of the index table. Only IT_GLOBAL_INDEX is supported.

Examples

  • Create a data table without creating an index table

    The following code provides an example on how to create a data table that has two primary key columns and reserved read and write throughput of (0, 0):

     // Create a schema for primary key columns, which includes the number, names, and types of the primary key columns. 
     // The first primary key column is named pk0, and is also the partition key. The type of the first primary key column is INTEGER. 
     // The second primary key column is named pk1 and the type of the second primary key column is STRING. 
     var primaryKeySchema = new PrimaryKeySchema();
     primaryKeySchema.Add("pk0", ColumnValueType.Integer);
     primaryKeySchema.Add("pk1", ColumnValueType.String);
    
     // Create a tableMeta class based on the table name and the schema for primary key columns. 
     var tableMeta = new TableMeta("SampleTable", primaryKeySchema);
    
     // Set the reserved read throughput and reserved write throughput to 0. 
     var reservedThroughput = new CapacityUnit(0, 0);
    
     try
     {
         // Construct a CreateTableRequest object. 
         var request = new CreateTableRequest(tableMeta, reservedThroughput);
    
         // Call the CreateTable operation of the client. If no exception is returned, a table is created. 
         otsClient.CreateTable(request);
    
         Console.WriteLine("Create table succeeded.");
     }
     // If an exception is returned, no table is created and you need to handle the exception. 
     catch (Exception ex)
     {
         Console.WriteLine("Create table failed, exception:{0}", ex.Message);
     }
                

    For the detailed sample code, visit CreateTable@GitHub.

  • Create a data table and an index table for the data table
    public static void CreateTableWithGlobalIndex()
    {
        // Create a table that contains two primary key columns Pk1 and Pk2 and set the predefined columns to Col1 and Col2. 
        // Create an index table and set one primary key column of the index table to Col1. The name of the primary key column is 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);
    }