DESCRIBE RELATION

Syntax

DESCRIBE [
    RELATION | STREAM | CHANGELOG | TABLE | MATERIALIZED VIEW | INDEX
] relation_name;

Description

This command provides the runtime information of an existing Relation in a Database's schema. This command can also be used to inspect a specific Relation type. See LIST RELATIONS for a list of available Relations to describe.

This command can be used to inspect an existing Relation. The output of this command also provides any errors that may have prevented the Relation and its underlying Entity to be created in the namespace.

Relations will only be visible if the current role has USAGE privileges on the Database and Schema and SELECT or INSERT privilege on the Relation.

See also DESCRIBE RELATION COLUMNS.

Arguments

relation_name

This is the name of the Relation to describe. For case-sensitive names, the name must be wrapped in double quotes; otherwise, the lowercase name will be used.

The Relation name optionally be fully qualified in the format <database_name>.<schema_name>.<relation_name> or <schema_name>.<relation_name>. If the Database name or Schema name are not provided, then the current session's Database/Schema will be used (see USE).

Examples

Describe a Relation using a current Database/Schema

The following describes the pageviews Stream Relation in the current demodb Database and public Schema:

demodb.public/demostore# DESCRIBE RELATION pageviews;
+-----------+---------+
|  Property |  Value  |
+===========+=========+
| state     | created |
+-----------+---------+

Describe a Relation using a fully qualified name

The following describes the pageviews Stream Relation in the demodb Database and public Schema, using its fully qualified Relation name:

demodb.public/demostore# DESCRIBE RELATION demodb.public.pageviews;
+-----------+---------+
|  Property |  Value  |
+===========+=========+
| state     | created |
+-----------+---------+

Describe a Changelog

The following describes the users_log Changelog in the demodb Database and public Schema, using its fully qualified Relation name:

demodb.public/demostore# DESCRIBE CHANGELOG demodb.public.users_log;
+-----------+---------+
|  Property |  Value  |
+===========+=========+
| state     | created |
+-----------+---------+

Describe a Stream in a specific Database/Schema

The following describes the total_views Stream in the demodb Database and analytics Schema, using its fully qualified Relation name:

demodb.public/demostore# DESCRIBE RELATION demodb.analytics.total_views;
+-----------+---------+
|  Property |  Value  |
+===========+=========+
| state     | created |
+-----------+---------+

Describe a Table in errored state

The following describes the dbx_pv Table in the current Database and Schema which had failed due to an issue:

demodb.analytics/demostore# DESCRIBE TABLE dbx_pv;
+-----------+------------------------------------------+
|  Property |  Value                                   |
+===========+==========================================+
| state     | errored                                  |
+-----------+------------------------------------------+
| error     | schema not found: verify the spelling    |
|           | and correctness of the Databricks        |
|           | schema and catalog                       |
+-----------+------------------------------------------+

Describe a Relation with a case-sensitive name

The following describes the Pageviews Stream Relation in the current demodb Database and public Schema:

demodb.public/demostore# DESCRIBE RELATION "Pageviews";
+-----------+---------+
|  Property |  Value  |
+===========+=========+
| state     | created |
+-----------+---------+