Project: TDengine (App Definition and Development / Database)
File: 03-table.md

title: Table description: This document describes how to create and perform operations on standard tables and subtables. You create standard tables and subtables with the `CREATE TABLE` statement. ```sql CREATE TABLE [IF NOT EXISTS] [dbname.]tbname (createdefinition [, createdefinition] ...) [table_options] CREATE TABLE createsubtableclause CREATE TABLE [IF NOT EXISTS] [dbname.]tbname (createdefinition [, createdefinition] ...) [TAGS (createdefinition [, createdefinition] ...)] [table_options] createsubtableclause: { createsubtableclause [createsubtableclause] ... | [IF NOT EXISTS] [dbname.]tbname USING [dbname.]stbname [(tagname [, tagname] ...)] TAGS (tagvalue [, tagvalue] ...) } create_definition: colname columndefinition column_definition: typename [comment 'stringvalue'] [PRIMARY KEY] [ENCODE 'encodetype'] [COMPRESS 'compresstype'] [LEVEL 'level_type'] table_options: table_option ... table_option: { COMMENT 'string_value' | SMA(colname [, colname] ...) | TTL value } ``` More explanations The first column of a table MUST be of type TIMESTAMP. It is automatically set as the primary key. In addition to the timestamp primary key column, an additional primary key column can be specified using the `PRIMARY KEY` keyword. The second column specified as the primary key must be of type integer or string (varchar). The maximum length of the table name is 192 bytes. The maximum length of each row is 48k(64k since version 3.0.5.0) bytes, please note that the extra 2 bytes used by each BINARY/NCHAR/GEOMETRY column are also counted. The name of the subtable can only consist of characters from the English alphabet, digits and underscore. Table names can't start with a digit. Table names are case insensitive. The maximum length in bytes must be specified when using BINARY/NCHAR/GEOMETRY types. Escape character "\`" can be used to avoid the conflict between table names and reserved keywords, above rules will be bypassed when using escape character on table names, but the upper limit for the name length is still valid. The table names specified using escape character are case sensitive. For example \`aBc\` and \`abc\` are different table names but `abc` and `aBc` are same table names because they are both converted to `abc` internally. Only ASCII visible characters can be used with escape character. Parameter description COMMENT: specifies comments for the table. This parameter can be used with supertables, standard tables, and subtables. SMA: specifies functions on which to enable small materialized aggregates (SMA). SMA is user-defined precomputation of aggregates based on data blocks. Enter one of the following values: max, min, or sum This parameter can be used with supertables and standard tables. TTL: specifies the time to live (TTL) for the table. If TTL is specified when creatinga table, after the time period for which the table has been existing is over TTL, TDengine will automatically delete the

Please be noted that the system may not delete the table at the exact moment that the TTL expires but guarantee there is such a system and finally the table will be deleted. The unit of TTL is in days. The default value is 0, i.e. never expire. ```sql CREATE TABLE [IF NOT EXISTS] tbname USING stbname TAGS (tag_value1, ...); ``` ```sql CREATE TABLE [IF NOT EXISTS] tbname USING stbname (tagname1, ...) TAGS (tagvalue1, ...); ``` The preceding SQL statement creates a subtable based on a supertable but specifies a subset of tags to use. Tags that are not included in this subset are assigned a null value. ```sql CREATE TABLE [IF NOT EXISTS] tbname1 USING stbname TAGS (tagvalue1, ...) [IF NOT EXISTS] tbname2 USING stbname TAGS (tagvalue2, ...) ...; ``` You can create multiple subtables in a single SQL statement provided that all subtables use the same supertable. For performance reasons, do not create more than 3000 tables per statement. ```sql ALTER TABLE [dbname.]tbname altertableclause altertableclause: { altertableoptions | ADD COLUMN colname columntype | DROP COLUMN col_name | MODIFY COLUMN colname columntype | RENAME COLUMN oldcolname newcolname } altertableoptions: altertableoption ... altertableoption: { TTL value | COMMENT 'string_value' } ``` More explanations You can perform the following modifications on existing tables: ADD COLUMN: adds a column to the supertable. DROP COLUMN: deletes a column from the supertable. MODIFY COLUMN: changes the length of the data type specified for the column. Note that you can only specify a length greater than the current length. RENAME COLUMN: renames a specified column in the table. The primary key column of a table cannot be modified or added or deleted using ADD/DROP COLUMN. ```sql ALTER TABLE tbname ADD COLUMN fieldname data_type; ``` ```sql ALTER TABLE tbname DROP COLUMN fieldname; ``` ```sql ALTER TABLE tbname MODIFY COLUMN fieldname data_type(length); ``` ```sql ALTER TABLE tbname RENAME COLUMN oldcolname newcol_name ``` ```sql ALTER TABLE [dbname.]tbname altertableclause altertableclause: { altertableoptions | SET TAG tagname = newtag_value } altertableoptions: altertableoption ... altertableoption: { TTL value | COMMENT 'string_value' } ``` More explanations Only the value of a tag can be modified directly. For all other modifications, you must modify the supertable from which the subtable was created. ``` ALTER TABLE tbname SET TAG tagname=newtagvalue; ``` The following SQL statement deletes one or more tables. ```sql DROP TABLE [IF EXISTS] [dbname.]tbname [, [IF EXISTS] [dbname.]tbname] ... ``` The following SQL statement shows all tables in the current database. ```sql SHOW TABLES [LIKE tbnamewildchar]; ``` ``` SHOW CREATE TABLE tb_name; ``` This command is useful in migrating data from one TDengine cluster to another because it can be used to create the exact same tables in the target database. ``` DESCRIBE [dbname.]tbname; ```