## Syntax
```mermaid
%%{init: {
'theme': 'base',
'flowchart': { 'padding': '7', 'nodeSpacing': '20', 'rankSpacing': '20' },
'themeVariables': {
'fontSize': '11px',
'fontFamily': 'Arial'
}
}}%%
flowchart LR
describeStatement_start((START))
describeStatement_start --> describeStatement_0_0[DESCRIBE]:::quoted
describeStatement_0_0 --> describeStatement_0_1[<a href="Invantive UniversalSQL/Grammar/Query Statement/Select Statement#selectStatement" class="internal-link">selectStatement</a>]
describeStatement_0_0 --> describeStatement_0_2[tableOrFunctionSpecWithRotator]
describeStatement_0_1 --> describeStatement_end((END))
describeStatement_0_2 --> describeStatement_end
```
## Purpose
The `describe` statement shows the columns that a `select` statement or a table returns, without reading a row. It returns one row per column, in the order of the result.
`describe` followed by a `select` statement builds the plan of the select, as [[Explain Statement (explainStatement)|explain]] does: the expressions are compiled and the data containers are asked for their metadata, but no rows are read. `describe` followed by a table, a view or a table function with its arguments describes the columns of `select * from` it, so that the result is the same as for that select. An alias and a data container, such as `describe range(5, 1)` or `describe systemtables@datadictionary`, may be given as in the `from` clause.
A person or an AI agent can learn the shape of a result before running it, which saves the calls a cloud platform counts and the rows that are not needed. A table function whose columns follow from what it returns may still have to make a call to know them. A table which does not exist fails as a `select` from it would. The word `describe` remains available as a name of a column, an alias and a table. Available from release 27.0.55 and the beta release 27.1.
The columns of the result:
- `POSITION`: the position of the column in the result, starting at 1.
- `COLUMN_NAME`: the name of the column, as a `select` returns it.
- `DATA_TYPE`: the data type of the column in Invantive UniversalSQL, such as `int64`, `varchar2`, `decimal` or `datetime`.
- `LENGTH`: the largest number of characters of a text; empty when it is not known.
- `PRECISION` and `SCALE`: the number of digits of a number and the number of digits after the decimal separator; empty when they are not known.
- `NULLABLE`: whether the column can be empty.
- `LABEL` and `DOCUMENTATION`: the label for a person and the description of the column, in the language of the user, where the data container declares them.
## Examples
The following example describes a select with an expression and an alias. Printed by [[Invantive Data Hub/Invantive Data Hub|Invantive Data Hub]]:
```sql
describe
select value
, 'customer_' || value name
, value * 1.5 amount
from range(5, 1)
```
```
┌──────────┬─────────────┬───────────┬────────┬───────────┬───────┬──────────┬──────────┬──────────────────┐
│ POSITION │ COLUMN_NAME │ DATA_TYPE │ LENGTH │ PRECISION │ SCALE │ NULLABLE │ LABEL │ DOCUMENTATION │
│ int32 │ varchar2 │ varchar2 │ int32 │ int16 │ int16 │ boolean │ varchar2 │ varchar2 │
├──────────┼─────────────┼───────────┼────────┼───────────┼───────┼──────────┼──────────┼──────────────────┤
│ 1 │ value │ int64 │ NULL │ 10 │ 0 │ False │ Value │ Generated value. │
│ 2 │ NAME │ varchar2 │ NULL │ NULL │ NULL │ False │ NULL │ NULL │
│ 3 │ AMOUNT │ decimal │ NULL │ NULL │ NULL │ False │ NULL │ NULL │
└──────────┴─────────────┴───────────┴────────┴───────────┴───────┴──────────┴──────────┴──────────────────┘
```
The following example describes the table function `range`:
```sql
describe range(5, 1)
```
```
┌──────────┬────────────────────┬───────────┬────────┬───────────┬───────┬──────────┬──────────────────────┬─────────────────────────────────────────────┐
│ POSITION │ COLUMN_NAME │ DATA_TYPE │ LENGTH │ PRECISION │ SCALE │ NULLABLE │ LABEL │ DOCUMENTATION │
│ int32 │ varchar2 │ varchar2 │ int32 │ int16 │ int16 │ boolean │ varchar2 │ varchar2 │
├──────────┼────────────────────┼───────────┼────────┼───────────┼───────┼──────────┼──────────────────────┼─────────────────────────────────────────────┤
│ 1 │ value │ int64 │ NULL │ 10 │ 0 │ False │ Value │ Generated value. │
│ 2 │ date_generated_utc │ datetime │ NULL │ NULL │ NULL │ False │ Date Generated (UTC) │ System time at which the row was generated. │
│ 3 │ random_blob │ blob │ NULL │ NULL │ NULL │ True │ Random BLOB │ BLOB with random contents. │
└──────────┴────────────────────┴───────────┴────────┴───────────┴───────┴──────────┴──────────────────────┴─────────────────────────────────────────────┘
```
## See Also
- [[Explain Statement (explainStatement)|Explain Statement]], which shows how a select is executed.