跳至主要內容

表管理

2025年1月3日大约 4 分钟

表管理

1. 表管理

1.1 创建表

1.1.1 通过 Create 语句手动创建表

用于在当前数据库中创建表，也可以对任何指定数据库创建表，格式为“数据库名.表名”。

语法：

CREATE TABLE (IF NOT EXISTS)? <TABLE_NAME>
    '(' (columnDefinition (',' columnDefinition)*)? ')'
    (WITH properties)?
    
columnDefinition
    : identifier columnCategory=(TAG | ATTRIBUTE)
    | identifier type (columnCategory=(TAG | ATTRIBUTE | TIME | FIELD))?
    ;
    
properties
    : '(' propertyAssignments ')'
    ;

propertyAssignments
    : property (',' property)*
    ;

property
    : identifier EQ propertyValue
    ;

说明：

  1. 在创建表时，可以不指定时间列（TIME），IoTDB会自动添加该列。其他所有列可以通过在数据库配置时启用enable_auto_create_schema选项，或通过 session 接口自动创建或修改表的语句来添加。
  2. 列的类别可以省略，默认为FIELD。当列的类别为TAG或ATTRIBUTE时，数据类型需为STRING（可省略）。
  3. 表的TTL默认为其所在数据库的TTL。如果使用默认值，可以省略此属性，或将其设置为default。
  4. <TABLE_NAME>表名称，具有以下特性：
    • 大小写不敏感
    • 名称可包含特殊字符，如 ~!"%` 等
    • 包含特殊字符如 or 中文字符的数据库名创建时必须用双引号 "" 括起来。
    • 当为表命名时，最外层的双引号（""）不会在实际创建的表名中出现。
    •  "a""b" --> a"b
 """""" --> ""
  5. columnDefinition 列名称与表名称具有相同特性，并且可包含特殊字符.。

示例:

CREATE TABLE table1 (
  time TIMESTAMP TIME,
  region STRING TAG,
  plant_id STRING TAG,
  device_id STRING TAG,
  model_id STRING ATTRIBUTE,
  maintenance STRING ATTRIBUTE,
  temperature FLOAT FIELD,
  humidity FLOAT FIELD,
  status Boolean FIELD,
  arrival_time TIMESTAMP FIELD
) WITH (TTL=31536000000);

CREATE TABLE if not exists table2 ();

CREATE TABLE tableC (
  "场站" STRING TAG,
  "温度" int32 FIELD
 ) with (TTL=DEFAULT);

1.1.2 通过 Session 写入自动创建表

在通过 Session 进行数据写入时，IoTDB 能够根据写入请求中的信息自动构建表结构，无需用户事先手动创建表即可直接执行数据写入操作。

示例：

try (ITableSession session =
    new TableSessionBuilder()
        .nodeUrls(Collections.singletonList("127.0.0.1:6667"))
        .username("root")
        .password("root")
        .build()) {

  session.executeNonQueryStatement("CREATE DATABASE db1");
  session.executeNonQueryStatement("use db1");

  // 不创建表直接写入数据
  List<String> columnNameList =
      Arrays.asList("region_id", "plant_id", "device_id", "model", "temperature", "humidity");
  List<TSDataType> dataTypeList =
      Arrays.asList(
          TSDataType.STRING,
          TSDataType.STRING,
          TSDataType.STRING,
          TSDataType.STRING,
          TSDataType.FLOAT,
          TSDataType.DOUBLE);
  List<Tablet.ColumnCategory> columnTypeList =
      new ArrayList<>(
          Arrays.asList(
              Tablet.ColumnCategory.TAG,
              Tablet.ColumnCategory.TAG,
              Tablet.ColumnCategory.TAG,
              Tablet.ColumnCategory.ATTRIBUTE,
              Tablet.ColumnCategory.FIELD,
              Tablet.ColumnCategory.FIELD));
  Tablet tablet = new Tablet("table1", columnNameList, dataTypeList, columnTypeList, 100);
  for (long timestamp = 0; timestamp < 100; timestamp++) {
    int rowIndex = tablet.getRowSize();
    tablet.addTimestamp(rowIndex, timestamp);
    tablet.addValue("region_id", rowIndex, "1");
    tablet.addValue("plant_id", rowIndex, "5");
    tablet.addValue("device_id", rowIndex, "3");
    tablet.addValue("model", rowIndex, "A");
    tablet.addValue("temperature", rowIndex, 37.6F);
    tablet.addValue("humidity", rowIndex, 111.1);
    if (tablet.getRowSize() == tablet.getMaxRowNumber()) {
      session.insert(tablet);
      tablet.reset();
    }
  }
  if (tablet.getRowSize() != 0) {
    session.insert(tablet);
    tablet.reset();
  }
}

在代码执行完成后，可以通过下述语句确认表已成功创建，其中包含了时间列、标签列、属性列以及测点列等各类信息。

IoTDB> desc table1
+-----------+---------+-----------+
| ColumnName| DataType|   Category|
+-----------+---------+-----------+
|       time|TIMESTAMP|       TIME|
|  region_id|   STRING|        TAG|
|   plant_id|   STRING|        TAG|
|  device_id|   STRING|        TAG|
|      model|   STRING|  ATTRIBUTE|
|temperature|    FLOAT|      FIELD|
|   humidity|   DOUBLE|      FIELD|
+-----------+---------+-----------+

1.2 查看表

用于查看该数据库中或指定数据库中的所有表和表库的属性信息。

语法：

SHOW TABLES (DETAILS)? ((FROM | IN) database_name)?

说明：

  1. 在查询中指定了FROM或IN子句时，系统将展示指定数据库内的所有表。
  2. 如果未指定FROM或IN子句，系统将展示当前选定数据库中的所有表。如果用户未使用（use）某个数据库空间，系统将报错。
  3. 请求显示详细信息（指定DETAILS），系统将展示表的当前状态，包括：
    • USING：表示表处于正常可用状态。
    • PRE_CREATE：表示表正在创建中或创建失败，此时表不可用。
    • PRE_DELETE：表示表正在删除中或删除失败，此类表将永久不可用。

示例:

IoTDB> show tables from test_db
+---------+-------+
|TableName|TTL(ms)|
+---------+-------+
|     test|    INF|
+---------+-------+

IoTDB> show tables details from test_db
+---------+-------+----------+
|TableName|TTL(ms)|    Status|
+---------+-------+----------+
|     test|    INF|     USING|
|  turbine|    INF|PRE_CREATE|
|      car|   1000|PRE_DELETE|
+---------+-------+----------+

1.3 查看表的列

用于查看表的列名、数据类型、类别、状态。

语法：

(DESC | DESCRIBE) <TABLE_NAME> (DETAILS)?

说明：

  • 如果设置了DETAILS选项，系统将展示列的详细状态信息，包括：
    • USING：表示列目前处于正常使用状态。
    • PRE_DELETE：表示列正在被删除或删除操作失败，该列将永久无法使用。

示例:

IoTDB> desc tableB
+----------+---------+-----------+
|ColumnName| DataType|   Category|
+----------+---------+-----------+
|      time|TIMESTAMP|       TIME|
|         a|   STRING|        TAG|
|         b|   STRING|  ATTRIBUTE|
|         c|    INT32|      FIELD|
+----------+---------+-----------+

IoTDB> desc tableB details
+----------+---------+-----------+----------+
|ColumnName| DataType|   Category|    Status|
+----------+---------+-----------+----------+
|      time|TIMESTAMP|       TIME|     USING|
|         a|   STRING|        TAG|     USING|
|         b|   STRING|  ATTRIBUTE|     USING|
|         c|    INT32|      FIELD|     USING|
|         d|    INT32|      FIELD|PRE_DELETE|
+----------+---------+-----------+----------+

1.4 修改表

用于修改表，包括添加列、删除列以及设置表的属性。

语法：

ALTER TABLE (IF EXISTS)? tableName=qualifiedName ADD COLUMN (IF NOT EXISTS)? column=columnDefinition                #addColumn
| ALTER TABLE (IF EXISTS)? tableName=qualifiedName DROP COLUMN (IF EXISTS)? column=identifier                     #dropColumn
// set TTL can use this
| ALTER TABLE (IF EXISTS)? tableName=qualifiedName SET PROPERTIES propertyAssignments                #setTableProperties

说明：

  1. SET PROPERTIES操作目前仅支持对表的 TTL 属性进行配置。
  2. 删除列功能，仅支持删除属性列(ATTRIBUTE)和物理量列(FIELD)，标识列(TAG)不支持删除。

示例:

ALTER TABLE tableB ADD COLUMN IF NOT EXISTS a TAG
ALTER TABLE tableB set properties TTL=3600

1.5 删除表

用于删除表。

语法：

DROP TABLE (IF EXISTS)? <TABLE_NAME>

示例:

DROP TABLE tableA
DROP TABLE test.tableB

版权所有 © 2025 Apache软件基金会。 Apache IoTDB，IoTDB，Apache，Apache 羽毛标志和 Apache IoTDB 项目标志是 Apache 软件基金会在所有国家的注册商标或商标

有问题吗？ 在 QQ、微信或 Slack 上联系我们。 立即加入社区