查询结果集结构

1. 功能概述

Describe Query/Output 语句用于展示查询语句的表结构信息，包括列名和数据类型，无需实际执行查询。其中：

• Describe Query：直接查看目标查询的表结构

• Describe Output：查看已预编译的 Prepared Statement 的表结构

注意：该功能自 V2.0.10.1 版本起支持。

2. 语法定义

2.1 Describe Query

DESCRIBE <query>;

2.2 Describe Output

-- 无参数预编译语句
DESCRIBE OUTPUT <prepareStatementName>;

-- 含参数预编译语句
DESCRIBE OUTPUT <prepareStatementName> USING <literalExpression> [, <literalExpression>]*;

以下情况会抛出语法异常：

• 预编译语句不存在，即不存在名称为目标 prepareStatementName 的 statement

• 缺少必需参数，即没有提供 describe 的 statement 运行时所必要的 parameter

2.3 结果集

列名	数据类型	说明
ColumnName	STRING	列名（表达式列自动生成如 _col2 的名称）
DataType	STRING	该列的数据类型

注意：与 DESCRIBE TABLE 不同，DESCRIBE QUERY 不显示 Category 列（TIME/TAG/FIELD 分类信息）。

3. 使用示例

以示例数据 中表 table1 为原始数据。

3.1 Describe Query

查询语句

describe select time, device_id, temperature+1 from table1;

返回结果如下，其中表达式 s1+1 的结果列自动生成名称为 _col2。

+----------+---------+
|ColumnName| DataType|
+----------+---------+
|      time|TIMESTAMP|
| device_id|   STRING|
|     _col2|    FLOAT|
+----------+---------+

3.2 Describe Output

3.2.1 不含动态参数

预编译语句

prepare select1 from select time, device_id, temperature+1 from table1;

查询语句

describe output select1;

返回结果

+----------+---------+
|ColumnName| DataType|
+----------+---------+
|      time|TIMESTAMP|
| device_id|   STRING|
|     _col2|    FLOAT|
+----------+---------+

3.2.2 包含动态参数

预编译语句

prepare select2 from select time, device_id, temperature from table1 where device_id = ?;

查询语句1：正确传入参数

describe output select2 using '100';

返回结果

+-----------+---------+
| ColumnName| DataType|
+-----------+---------+
|       time|TIMESTAMP|
|  device_id|   STRING|
|temperature|    FLOAT|
+-----------+---------+

查询语句2：未传入参数

describe output select2;

错误信息

Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Invalid number of parameters: expected 1, got 0

3.2.3 预编译语句不存在

查询语句

describe output select_not_exists;

错误信息

Msg: org.apache.iotdb.jdbc.IoTDBSQLException: 701: Prepared statement 'select_not_exists' does not exist

4. 权限说明

DESCRIBE QUERY 和 DESCRIBE OUTPUT 的访问控制权限与执行对应 SELECT 查询所需的权限保持一致。