<!--

    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at
    
        http://www.apache.org/licenses/LICENSE-2.0
    
    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.

-->

# 元数据操作

## 1. 数据库管理

### 1.1 创建数据库

**语法：**

```SQL
CREATE DATABASE (IF NOT EXISTS)? <DATABASE_NAME> (WITH properties)?
```

更多详细语法说明请参考：[创建数据库](../Basic-Concept/Database-Management_apache.md#_1-1-创建数据库)

**示例：**

创建一个名为 database1 的数据库, 数据库的 TTL 时间默认永久。
```SQL
CREATE DATABASE database1;
CREATE DATABASE IF NOT EXISTS database1;
```

创建一个名为 database1 的数据库，并将数据库的 TTL 时间设置为1年。
```SQL
CREATE DATABASE IF NOT EXISTS database1 with(TTL=31536000000);
```

### 1.2 使用数据库

**语法：**

```SQL
USE <DATABASE_NAME>
```

**示例:**

```SQL
USE database1;
```

### 1.3 查看当前数据库

**语法：**

```SQL
SHOW CURRENT_DATABASE;
```

**示例：**

未执行过 `use`语句指定数据库
```SQL
SHOW CURRENT_DATABASE;
```
```shell
+---------------+
|CurrentDatabase|
+---------------+
|           null|
+---------------+
```
执行 `use`语句指定数据库 database1
```sql
USE database1;
SHOW CURRENT_DATABASE;
```
```shell
+---------------+
|CurrentDatabase|
+---------------+
|      database1|
+---------------+
```

### 1.4 查看所有数据库

**语法：**

```SQL
SHOW DATABASES (DETAILS)?
```

更多返回结果详细说明请参考：[查看所有数据库](../Basic-Concept/Database-Management_apache.md#_1-4-查看所有数据库)

**示例:**

查看所有数据库
```SQL
SHOW DATABASES;
```
```shell
+------------------+-------+-----------------------+---------------------+---------------------+
|          Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|
+------------------+-------+-----------------------+---------------------+---------------------+
|         database1|    INF|                      1|                    1|            604800000|
|information_schema|    INF|                   null|                 null|                 null|
+------------------+-------+-----------------------+---------------------+---------------------+
```

查看所有数据库详情
```sql
SHOW DATABASES DETAILS;
```
```shell
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+
|          Database|TTL(ms)|SchemaReplicationFactor|DataReplicationFactor|TimePartitionInterval|SchemaRegionGroupNum|DataRegionGroupNum|
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+
|         database1|    INF|                      1|                    1|            604800000|                   1|                 2|
|information_schema|    INF|                   null|                 null|                 null|                null|              null|
+------------------+-------+-----------------------+---------------------+---------------------+--------------------+------------------+
```

### 1.5 修改数据库

**语法：**

```SQL
ALTER DATABASE (IF EXISTS)? database=identifier SET PROPERTIES propertyAssignments;
```

**示例:**

修改数据库 database1 的 TTL 时间为1年
```SQL
ALTER DATABASE database1 SET PROPERTIES TTL=31536000000;
```

### 1.6 删除数据库

**语法：**

```SQL
DROP DATABASE (IF EXISTS)? <DATABASE_NAME>;
```

**示例:**

删除数据库 database1
```SQL
DROP DATABASE IF EXISTS database1;
```

## 2. 表管理

### 2.1 创建表

**语法：**

```SQL
createTableStatement
    : CREATE TABLE (IF NOT EXISTS)? qualifiedName
        '(' (columnDefinition (',' columnDefinition)*)? ')'
        charsetDesc?
        comment?
        (WITH properties)?
     ;

charsetDesc
    : DEFAULT? (CHAR SET | CHARSET | CHARACTER SET) EQ? identifierOrString
    ;

columnDefinition
    : identifier columnCategory=(TAG | ATTRIBUTE | TIME) charsetName? comment?
    | identifier type (columnCategory=(TAG | ATTRIBUTE | TIME | FIELD))? charsetName? comment?
    ;

charsetName
    : CHAR SET identifier
    | CHARSET identifier
    | CHARACTER SET identifier
    ;

comment
    : COMMENT string
    ;
```

更多详细语法说明请参考：[创建表](../Basic-Concept/Table-Management_apache.md#_1-1-创建表)

**示例:**

创建表 table1 并将表的 TTL 设置为1年
```SQL
CREATE TABLE table1 (
  time TIMESTAMP TIME,
  region STRING TAG,
  plant_id STRING TAG,
  device_id STRING TAG,
  model_id STRING ATTRIBUTE,
  maintenance STRING ATTRIBUTE COMMENT 'maintenance',
  temperature FLOAT FIELD COMMENT 'temperature',
  humidity FLOAT FIELD COMMENT 'humidity',
  status Boolean FIELD COMMENT 'status',
  arrival_time TIMESTAMP FIELD COMMENT 'arrival_time'
) COMMENT 'table1' WITH (TTL=31536000000);
```

创建空表 tableB
```SQL
CREATE TABLE if not exists tableB ();
```

创建表 tableC 
```SQL
CREATE TABLE tableC (
  station STRING TAG,
  temperature int32 FIELD COMMENT 'temperature'
 ) with (TTL=DEFAULT);
```

创建表 table1 并自定义时间列:命名为time_test, 位于表的第二列 (V2.0.8 起支持）
```SQL
CREATE TABLE table1 (
 region STRING TAG, 
 time_user_defined TIMESTAMP TIME, 
 temperature FLOAT FIELD
);
```

注意：若您使用的终端不支持多行粘贴（例如 Windows CMD），请将 SQL 语句调整为单行格式后再执行。

### 2.2 查看表

**语法：**

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

**示例:**

查看数据库 database1 下的所有表
```SQL
show tables from database1;
```
```shell
+---------+---------------+
|TableName|        TTL(ms)|
+---------+---------------+
|   table1|    31536000000|
+---------+---------------+
```

查看数据库 database1 下的所有表及其属性信息
```sql
show tables details from database1;
```
```shell
+---------------+-----------+------+-------+
|      TableName|    TTL(ms)|Status|Comment|
+---------------+-----------+------+-------+
|         table1|31536000000| USING| table1|
+---------------+-----------+------+-------+
```

### 2.3 查看表的列

**语法：**

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

**示例:**

查看表 table1 的列信息
```SQL
desc table1;
```
```shell
+------------+---------+---------+
|  ColumnName| DataType| Category|
+------------+---------+---------+
|        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|
+------------+---------+---------+
```
查看表 table1 的列详细信息
```sql
desc table1 details;
```
```shell
+------------+---------+---------+------+------------+
|  ColumnName| DataType| Category|Status|     Comment|
+------------+---------+---------+------+------------+
|        time|TIMESTAMP|     TIME| USING|        null|
|      region|   STRING|      TAG| USING|        null|
|    plant_id|   STRING|      TAG| USING|        null|
|   device_id|   STRING|      TAG| USING|        null|
|    model_id|   STRING|ATTRIBUTE| USING|        null|
| maintenance|   STRING|ATTRIBUTE| USING| maintenance|
| temperature|    FLOAT|    FIELD| USING| temperature|
|    humidity|    FLOAT|    FIELD| USING|    humidity|
|      status|  BOOLEAN|    FIELD| USING|      status|
|arrival_time|TIMESTAMP|    FIELD| USING|arrival_time|
+------------+---------+---------+------+------------+
```

### 2.4 查看表的创建信息

**语法：**

```SQL
SHOW CREATE TABLE <TABLE_NAME>
```

**示例:**

查看表 table1 的创建信息
```SQL
show create table table1;
```
```shell
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Table|                                                                                                                                                                                                                                                                     Create Table|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|table1|CREATE TABLE "table1" ("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)|
+------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```


### 2.5 修改表

**语法：**

```SQL
#addColumn;
ALTER TABLE (IF EXISTS)? tableName=qualifiedName ADD COLUMN (IF NOT EXISTS)? column=columnDefinition COMMENT 'column_comment';               
#dropColumn;
ALTER TABLE (IF EXISTS)? tableName=qualifiedName DROP COLUMN (IF EXISTS)? column=identifier;     
#setTableProperties;               
// set TTL can use this;
| ALTER TABLE (IF EXISTS)? tableName=qualifiedName SET PROPERTIES propertyAssignments;                
| COMMENT ON TABLE tableName=qualifiedName IS 'table_comment';
| COMMENT ON COLUMN tableName.column IS 'column_comment';
```

**示例:**

表 table1 增加 tag 列 a
```SQL
ALTER TABLE table1 ADD COLUMN IF NOT EXISTS a TAG COMMENT 'a';
```
表 table1 增加 field 列 b
```SQL
ALTER TABLE table1 ADD COLUMN IF NOT EXISTS b FLOAT FIELD COMMENT 'b';
```
修改表 table1 的 TTL
```SQL
ALTER TABLE table1 set properties TTL=3600; 
```
表 table1 增加注释
```SQL
COMMENT ON TABLE table1 IS 'table1';
```
表 table1 的 a 列去掉注释
```SQL
COMMENT ON COLUMN table1.a IS null;
```

### 2.6 删除表

**语法：**

```SQL
DROP TABLE (IF EXISTS)? <TABLE_NAME>;
```

**示例:**

```SQL
DROP TABLE table1;
DROP TABLE database1.table1;
```