Query Output Schema

1. Overview

The DESCRIBE QUERY and DESCRIBE OUTPUT statements are used to display schema information for query results, including column names and data types, without actually executing the query. Specifically:

• DESCRIBE QUERY: directly displays the result schema of the target query.
• DESCRIBE OUTPUT: displays the result schema of a prepared statement.

Note: This feature is supported starting from V2.0.10.1.

2. Syntax

2.1 Describe Query

DESCRIBE <query>;

2.2 Describe Output

-- Prepared statement without parameters
DESCRIBE OUTPUT <prepareStatementName>;

-- Prepared statement with parameters
DESCRIBE OUTPUT <prepareStatementName> USING <literalExpression> [, <literalExpression>]*;

An exception is thrown in the following cases:

• The prepared statement does not exist, that is, there is no statement named prepareStatementName.

• Required parameters are missing, that is, no parameters required by the statement are provided at runtime.

2.3 Result Set

Column Name	Data Type	Description
ColumnName	STRING	Column name. Expression columns are automatically named, for example _col2.
DataType	STRING	Data type of the column.

Note: Unlike DESCRIBE TABLE, DESCRIBE QUERY does not display the Category column, which contains TIME/TAG/FIELD category information.

3. Examples

Use table table1 in Sample Data as the source data.

3.1 Describe Query

Query statement:

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

The result is as follows. The result column of the expression temperature+1 is automatically named _col2.

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

3.2 Describe Output

3.2.1 Without Dynamic Parameters

Prepared statement:

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

Query statement:

describe output select1;

Result:

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

3.2.2 With Dynamic Parameters

Prepared statement:

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

Query statement 1: pass the parameter correctly.

describe output select2 using '100';

Result:

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

Query statement 2: no parameter is passed.

describe output select2;

Error message:

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

3.2.3 Prepared Statement Does Not Exist

Query statement:

describe output select_not_exists;

Error message:

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

4. Permission Description

The access control permissions for DESCRIBE QUERY and DESCRIBE OUTPUT are the same as those required to execute the corresponding SELECT query.