Use the Tablestore CLI to perform operations on data tables - Tablestore

The Wide Column model uses data tables to store data. This topic describes how to use the Tablestore CLI to perform operations on data tables. You can use the Tablestore CLI to create, use, update, and delete a table. You can also use the Tablestore CLI to list the names of tables and query information about a table.

Create a table

Create a data table for which configurations 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>

Parameters

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.
-k, --pk	Yes	[{"c":"uid","t":"string"},{"c":"pid","t":"integer"}]	The primary key columns of the data table. The value of this parameter is a JSON array. This parameter consists of the following fields: 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 Configure an auto-increment primary key column. Note You do not need to specify the schema of attribute columns when you create a data table. The attribute columns in each row can be different. You must specify the name of an attribute column when you write data. You can specify 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 or order of the primary key columns.
--ttl	No	864000	The retention period of data in the data table. Unit: seconds. The default value is -1, which specifies that the data never expires. Note The TTL must be at least 86,400 seconds (one day) or -1. A value of -1 specifies that data in the data table never expires.
--version	No	1	The maximum number of versions that can be retained for the data in an attribute column. Default value: 1. A value of 1 specifies that only the latest version of the data is retained for each attribute column. The value of this parameter must be a positive integer. Important Tablestore does not enforce a limit on the maximum number of versions that can be retained for the data in an attribute column. However, for optimal performance and ease of use, we recommend that you set this parameter to a value that does not exceed 500.
--read_cu	No	0	The reserved read and write throughput. Unit: capacity unit (CU). The default value 0 specifies that you are charged for all throughput on a pay-as-you-go basis. Note You can specify the reserved read and write throughput only for data tables in high-performance instances. If you set the reserved read or write throughput to a value other than 0, you are charged regardless of whether you initiate read or write requests.
--write_cu	No	0
-d, --defined	No	[{"c":"name","t":"string"},{"c":"age","t":"integer"}]	The names and types of the predefined columns. The value of this parameter is a JSON array. This parameter consists of the following fields: c: required. The name of the predefined column. t: required. The type of the predefined column. Valid values: string, integer, binary, double, and bool. Note By default, you can specify up to 32 predefined columns for a data table.
-i, --input	No	/tmp/create_table_meta.json	The path of the configuration file that is used to create the data table. The configuration file must be in the JSON format.

Examples

The following sample code provides an example on how to create a data table named mytable. In this example, the data table contains the following primary key columns: the uid primary key column and the pid primary key column. Data in the data table never expires.
```
create -t mytable --pk '[{"c":"uid", "t":"string"}, {"c":"pid", "t":"integer"}]'
```
The following sample code provides an example on how to create a data table named mytable. In this example, the data table contains the following primary key columns: the uid primary key column and the pid primary key column. The pid primary key column is specified as an auto-increment primary key column.

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

The following sample code provides an example on how to create a data table named mytable. In this example, the data table contains the following primary key columns: the uid primary key column and the pid primary key column. The TTL is set to 864,000 seconds (10 days). Only the latest version of data is retained for each attribute column.
```
create -t mytable --pk '[{"C":"uid","t":"string"}, {"c":"pid","t":"integer"}]' --ttl 864000 --version 1
```

The following sample code provides an example on how to use a configuration file to create a data table named mytable. In this example, the data table contains the following primary key columns: the uid primary key column and the pid primary key column. The TTL is set to 864,000 seconds (10 days) and the reserved read and write throughput to 0. Up to three versions of data are retained for each attribute column.

Windows

create -i D:\\localpath\\filename.json

Linux and macOS

create -i /localpath/filename.json

The configuration file contains the following information:

{
    "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
    }
}

Use a table

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

Command syntax

use --wc -t <tableName>

Parameters

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

Examples

The following sample code provides an example on how to select the mytable table:

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.

Command syntax

list

Parameters

Parameter	Required	Example	Description
-a, --all	No	N/A	Lists the names of all tables.
-d, --detail	No	N/A	Lists the details of 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.

Examples

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
```

Update a table

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

Command syntax

alter -t <tableName> --ttl <timeToLive> --version <maxVersion> --read_cu <readCU> --write_cu <writeCU>

Parameters

Parameter	Required	Example	Description
-t, --table	Yes	mytable	The name of the data table.
--ttl	No	864000	The retention period of data in the data table. Unit: seconds. The TTL must be at least 86,400 seconds (one day) or -1. A value of -1 specifies that data in the data table never expires.
--version	No	1	The maximum number of versions that can be retained for the data in an attribute column. Default value: 1. A value of 1 specifies that only the latest version of the data is retained for each attribute column. The value of this parameter must be a positive integer. Important Tablestore does not enforce a limit on the maximum number of versions that can be retained for the data in an attribute column. However, for optimal performance and ease of use, we recommend that you set this parameter to a value that does not exceed 500.
--read_cu	No	0	The reserved read and write throughput. Unit: CU. The default value 0 specifies that you are charged for all throughput on a pay-as-you-go basis. Note You can specify the reserved read and write throughput only for data tables in high-performance instances. If you set the reserved read or write throughput to a value other than 0, you are charged regardless of whether you initiate read or write requests.
--write_cu	No	0

Examples

The following sample code provides an example on how to change the TTL to 86,400 seconds and set the max versions to 1 and reserved read and write throughput to 0 for a data table named mytable:

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

Query information about a table

Query information about a table and then save the information to a JSON file on your local computer.

Command syntax

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

Parameters

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

Examples

The following sample code provides an example on how to query information about the current table:
```
desc
```
The following sample code provides an example on how to query information about the current table and save the information to a local file named describe_table_meta.json:
```
desc -o  /tmp/describe_table_meta.json
```

Delete a table

Delete a data table.

Command syntax

drop -t <tableName> -y

Parameters

Parameter	Required	Example	Description
-t, --table	Yes	mytable	The name of the data table.
-y,--yes	Yes	N/A	Specifies that the confirmation information is displayed. This parameter is required in the command.

Examples

The following sample code provides an example on how to delete a data table named mytable:

drop -t mytable -y

References

The Wide Column model is similar to the data model of Bigtable or HBase, and is suitable for various scenarios such as the storage of metadata and big data. For more information, see Overview.
You can perform operations on data tables in the Tablestore console, or by using the Tablestore CLI or Tablestore SDKs. For more information, see Use the Tablestore console and Use Tablestore SDKs.