After you create a data table, you can use the data table, query information about the data table, list the names of data tables, update the data table, and delete the data table.

Note For more information about the Wide Column model, see Wide Column model.

Create a data table

Create a data table for which parameters such as primary key columns and time to live (TTL) are specified. You can also import a configuration file in the JSON format to create a data table.

  • Command syntax
    create -t tableName --pk '[{"c":"<primaryKeyName>", "t":"<primaryKeyType>"}, {"c":"<primaryKeyName>", "t":"<primaryKeyType>", "opt":"<options>"}]'--ttl <timeToLive> --version <maxVersion> 

    The following table describes the parameters that you can configure to create a data table.

    Parameter Required Example Description
    -m, --mode No widecolumn The type of the table that you want to create. Default value: widecolumn. Valid values:
    • widecolumn: data table
    • timeseries: time series table
    -t, --table Yes mytable The name of the data table.
    -p, --pk Yes [{"c":"uid","t":"string"}, {"c":"pid","t":"integer"}] The primary key column settings of the data table. The value of this parameter is a JSON array. The following fields are supported:
    • c: required. The name of the primary key column.
    • t: required. The type of the primary key column. Valid values: string, integer, and binary.
    • opt: optional. The optional configuration item. Valid values: none and auto. Default value: none. If you set opt to auto, the primary key column is an auto-increment primary key column.

      For more information about auto-increment primary key columns, see Auto-increment of primary key columns.

    You can add one to four primary key columns. The first primary key column is the partition key. After you create a data table, you cannot modify the configurations and the order of primary key columns.

    --ttl No 864000 The retention period of data in the data table. If the retention period exceeds the TTL value, Tablestore automatically deletes expired data. Unit: seconds.

    If you do not specify a value for this parameter, the default value -1 is used. The value of -1 specifies that data never expires.

    The value of this parameter must be -1 or a value that is greater than or equal to 86400 seconds (one day).

    --version No 1 The maximum number of versions that can be retained for data in attribute columns of the data table. If the number of versions of data in attribute columns exceeds the value of this parameter, the system deletes data of earlier versions.

    If you do not specify a value for this parameter, the default value 1 is used. The value of 1 specifies that only data of the latest version is retained.

    The value of this parameter for an attribute column is a positive integer.

    --read_cu No 0 The reserved read throughput and reserved write throughput of the data table. The default value 0 specifies that all throughput is billed based on the pay-as-you-go billing method. Unit: capacity unit (CU).

    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.

    • 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.
    • If you set the reserved read throughput or reserved write throughput to 0, Tablestore does not reserve resources for the data table.
    --write_cu No 0
    -i, --input No /tmp/create_table_meta.json The path of the configuration file that is used to create a data table. The configuration file must be in the JSON format.
    You can also run the following commands to create a configuration file:
    • Windows
      create -i D:\\localpath\\filename.json
    • Linux and macOS
      create -i /localpath/filename.json
    The following example shows the content of a configuration file:
    {
        "Name": "mytable",
        "Meta": {
            "Pk": [
                {
                    "C": "uid",
                    "T": "string",
                    "Opt": "none"
                },
                {
                    "C": "pid",
                    "T": "integer",
                    "Opt": "none"
                }
            ]
        },
        "Option": {
            "TTL": 864000,
            "Version": 3
        },
        "CU": {
            "Read": 0,
            "Write": 0
        }
    }
  • Examples

    Create a data table named mytable. The data table contains the uid and pid primary key columns. The uid column is of the STRING type. The pid column is of the INTEGER type. Data in the data table never expires.

    create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'

    Create a data table named mytable. The data table contains the uid and pid primary key columns. The uid column is of the STRING type. The pid column is of the INTEGER type. The pid column is specified as an auto-increment primary key column. Data in the data table never expires.

    create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer", "opt":"auto"}]'

    Create a data table named mytable. The data table contains the uid and pid primary key columns. The uid column is of the STRING type. The pid column is of the INTEGER type. The TTL is set to 864000 seconds (10 days). Only the data of the latest version is retained.

    create -t mytable --pk '[{"C":"uid","t":"string"}, {"c":"pid","t":"integer"}]' --ttl 864000 --version 1

Use a data table

Select the data table on which you want to perform table operations or data operations.

  • Command syntax
    use --wc -t <tableName>

    The following table describes the parameters that you can configure to use a data table.

    Parameter Required Example Description
    --wc No N/A Specifies that the table on which you want to perform operations is a data table.
    -t, --table Yes mytable The name of the data table.
  • Example

    The following sample code shows how to use the data table named mytable:

    use -t mytable

List the names of tables

List the names of all tables, all data tables, or all time series tables in an instance.

  • List the names of all tables of the same type as the current table
    list
  • List the names of all tables
    list -a
  • List the names of all data tables
    list -w
  • List the names of all time series tables
    list -t

The following table describes the parameters that you can configure to list the names of tables.

Parameter Required Example Description
-a, --all No N/A Lists the names of all tables.
-d, --detail No N/A Lists the details about the tables.
-w, --wc No N/A Lists the names of all data tables.
-t, --ts No N/A Lists the names of all time series tables.

Update a data table

Update information about a data table, such as TTL and max versions.

  • Command syntax
    alter -t <tableName> --ttl <timeToLive> --version <maxVersion> --read_cu <readCU> --write_cu <writeCU>
  • Example

    Change the TTL of the data table named mytable to 86400 seconds (one day). Set the max versions to 1, reserved read CU to 0, and reserved write CU to 0.

    alter -t mytable --ttl 86400 --version 1 --read_cu 0 --write_cu 0

Query information about a data table

You can query information about a data table and then save the information to a JSON file on your local PC.

  • Command syntax
    desc -t <tableName> -o /localpath/filename.json

    The following table describes the parameters that you can configure to query information about a data table.

    Parameter Required Example Description
    -t, --table No mytable The name of the data table.
    -f, --print_format No json The output format of the information about the data table. Default value: json. Valid values: json and table.
    -o, --output No /tmp/describe_table_meta.json The path of the local JSON file in which the information about the data table is stored.
  • Example

    The following sample code shows how to query information about the current data table:

    desc
    The following sample code shows how to query information about the current data table and save the information to the local file named describe_table_meta.json:
    desc -o  /tmp/describe_table_meta.json

Delete a data table

You can delete a data table that you no longer require.

  • Command syntax
    drop -t <tableName> -y

    The following table describes the parameters that you can configure to delete a data table.

    Parameter Required Example Description
    --t, --table Yes mytable The name of the data table.
    -y, --yes Yes N/A Specifies that confirmation information appears. You must include this configuration item in the command.
  • Example

    The following sample code shows how to delete the data table named mytable:

    drop -t mytable -y