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 Tablestore console. For more information, see Create instances.
  • A Tablestore client is initialized. For more information, see Initialization.

API operations

  /**
   * Create a data table based on the specified table schema. 
   */
  createTable(params, callback)           

Parameters

ParameterDescription
tableMetaThe schema information of the data table. The schema information contains the following items:
  • tableName: the name of the data table.
  • primaryKey: the schema of the primary key for the data table. For information, see Primary keys and attributes.
    Note Attribute columns are optional. Different rows in Tablestore 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 you assign no more than 10 GB of data with the same partition key. Otherwise, a single partition may be too large to split. We recommend that you evenly distribute requests to read and write data to different partition keys for load balancing.
  • definedColumn: the predefined columns of the data table and the data types of the predefined columns. Primary key columns cannot be specified as predefined columns. You can use predefined columns as the index columns or attribute columns for 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 TTL 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 the data table, you must set maxVersions to 1.
  • 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 all throughput is billed 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. Additional throughput is billed based on the pay-as-you-go billing method. For 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 tables. Each indexMeta contains the following items:
  • name: the name of the index table.
  • primaryKey: the primary key of the index table. The primary key is a combination of all primary key columns and a random number of predefined columns of the data table.

    If you use the local secondary index feature, the first primary key column of an index table must be the same as the first primary key column of the corresponding data table.

  • definedColumn: the attribute columns of the index table. The attribute columns are a combination of predefined columns of the data table.
  • includeBaseData: specifies whether to include the existing data from the data table in the index table.

    If you set includeBaseData to true, the index table includes the existing data. If you set includeBaseData to false, the index table excludes the existing data.

  • indexType: the type of the index. Valid values: IT_GLOBAL_INDEX and IT_LOCAL_INDEX.
    • If indexType is not specified or is set to IT_GLOBAL_INDEX, the global secondary index feature is used.

      When you use a global secondary index, Tablestore automatically synchronizes the data from the index columns and primary key columns of a data table to the columns of an index table in asynchronous mode. The synchronization latency is within a few milliseconds.

    • If indexType is set to IT_LOCAL_INDEX, the local secondary index feature is used.

      When you use a local secondary index, Tablestore automatically synchronizes the data from the index columns and primary key columns of a data table to the columns of an index table in synchronous mode. After data is written to the data table, you can query the data from the index table.

  • indexUpdateMode: the update mode of the index. Valid values: IUM_ASYNC_INDEX and IUM_SYNC_INDEX.
    • If indexUpdateMode is not specified or is set to IUM_ASYNC_INDEX, the asynchronous mode is used to update the index.

      If you use the global secondary index feature, you must set the index update mode to IUM_ASYNC_INDEX.

    • If you set indexUpdateMode to IUM_SYNC_INDEX, the synchronous update mode is used.

      If you use the local secondary index feature, you must set the index update mode to IUM_SYNC_INDEX, which indicates the synchronous update mode.

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):

    var client = require('./client');
    
    var params = {
      tableMeta: {
        tableName: 'sampleTable',
        primaryKey: [
          {
            name: 'gid',
            type: 'INTEGER'
          },
          {
            name: 'uid',
            type: 'INTEGER'
          }
        ]
      },
      reservedThroughput: {
        capacityUnit: {
          read: 0,
          write: 0
        }
      },
      tableOptions: {
        timeToLive: -1, // Specify the validity period of data in seconds. A value of -1 indicates that the data never expires. If you set the validity period to a year, the value of timeToLive is 31,536,000 (365 × 24 × 3,600). 
        maxVersions: 1 // Specify the maximum number of versions that can be retained for each column. A value of 1 indicates that only the latest version is retained for each column. 
      }
    };
    
    client.createTable(params, function (err, data) {
      if (err) {
        console.log('error:', err);
        return;
      }
      console.log('success:', data);
    });
                

    For the detailed sample code, visit CreateTable@GitHub.

  • Create a data table and an index table whose index type is global secondary index
    var client = require('./client');
    var TableStore = require('../index.js');
    
    var params = {
      tableMeta: {
        tableName: 'sdkGlobalTest',
        primaryKey: [
          {
            name: 'pk1',
            type: TableStore.PrimaryKeyType.INTEGER
          },
          {
            name: 'pk2',
            type: TableStore.PrimaryKeyType.INTEGER
          }
        ],
        definedColumn: [
          {
            "name": "col1",
            "type": TableStore.DefinedColumnType.DCT_INTEGER
          },
          {
            "name": "col2",
            "type": TableStore.DefinedColumnType.DCT_INTEGER
          }
        ],
      },
      reservedThroughput: {
        capacityUnit: {
          read: 0,
          write: 0
        }
      },
      tableOptions: {
        timeToLive: -1, // Specify the validity period of data in seconds. A value of -1 indicates that the data never expires. You must set timeToLive to -1 for a data table for which index tables are created. 
        maxVersions: 1 // Specify the maximum number of versions that can be retained for each column. A value of 1 indicates that only the latest version is retained for each column. You must set maxVersions to 1 for a data table for which index tables are created. 
      },
      streamSpecification: {
        enableStream: false, // The Stream feature cannot be enabled for secondary indexes. 
      },
      indexMetas: [
        {
          name: "sdkGlobalIndex1",
          primaryKey: ["pk2"],
          definedColumn: ["col1", "col2"]
        },
        {
          name: "sdkGlobalIndex2",
          primaryKey: ["col1"],
          definedColumn: ["col2"]
        }
      ]
    };
    
    client.createTable(params, function (err, data) {
      if (err) {
        console.log('error:', err);
        return;
      }
      console.log('success:', data);
    });
  • Create a data table and an index table whose index type is local secondary index
    var client = require('./client');
    var TableStore = require('../index.js');
    
    var params = {
      tableMeta: {
        tableName: 'sdkLocalTest',
        primaryKey: [
          {
            name: 'pk1',
            type: TableStore.PrimaryKeyType.INTEGER
          },
          {
            name: 'pk2',
            type: TableStore.PrimaryKeyType.INTEGER
          }
        ],
        definedColumn: [
          {
            "name": "col1",
            "type": TableStore.DefinedColumnType.DCT_INTEGER
          },
          {
            "name": "col2",
            "type": TableStore.DefinedColumnType.DCT_INTEGER
          }
        ],
      },
      reservedThroughput: {
        capacityUnit: {
          read: 0,
          write: 0
        }
      },
      tableOptions: {
        timeToLive: -1, // Specify the validity period of data in seconds. A value of -1 indicates that the data never expires. You must set timeToLive to -1 for a data table for which index tables are created. 
        maxVersions: 1 // Specify the maximum number of versions that can be retained for each column. A value of 1 indicates that only the latest version is retained for each column. You must set maxVersions to 1 for a data table for which index tables are created. 
      },
      streamSpecification: {
        enableStream: false, // The Stream feature cannot be enabled for secondary indexes. 
      },
      indexMetas: [
        {
          name: "sdklocalIndex1",
          primaryKey: ["pk1","col1"], // Add primary key columns to the index table. The first primary key column of the index table must be the same as the first primary key column of the data table. 
          definedColumn: ["col2"],
          indexUpdateMode: TableStore.IndexUpdateMode.IUM_SYNC_INDEX, // Set the index update mode to IUM_SYNC_INDEX, which indicates the synchronous update mode. If the index type is set to IT_LOCAL_INDEX, the index update mode must be set to IUM_SYNC_INDEX. 
          indexType: TableStore.IndexType.IT_LOCAL_INDEX, // Set the index type to IT_LOCAL_INDEX, which indicates a local secondary index. 
        },
    
        {
          name: "sdklocalIndex2",
          primaryKey: ["pk1","col2"],
          definedColumn: ["col1"],
          indexUpdateMode: TableStore.IndexUpdateMode.IUM_SYNC_INDEX, // Set the index update mode to IUM_SYNC_INDEX, which indicates the synchronous update mode. If the index type is set to IT_LOCAL_INDEX, the index update mode must be set to IUM_SYNC_INDEX. 
          indexType: TableStore.IndexType.IT_LOCAL_INDEX, // Set the index type to IT_LOCAL_INDEX, which indicates a local secondary index. 
        }
      ]
    };
    
    client.createTable(params, function (err, data) {
      if (err) {
        console.log('error:', err);
        return;
      }
      console.log('success:', data);
    });