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. You can also use this command to inspect a specific relation type. See LIST RELATIONS for a list of available relations to describe.

You can use this command 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 are visible only 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. If the name is case-sensitive, you must wrap it in double quotes; otherwise, the lowercase name is used.

The relation name optionally can 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 system uses the current session's database/schema (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 that failed:

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 |
+-----------+---------+