# DESCRIBE RELATION

## Syntax

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

## Description

This command provides the runtime information of an existing [Relation](/overview/core-concepts/databases.md#relation) in a [Database's](/overview/core-concepts/databases.md) [schema](/overview/core-concepts/databases.md#schema). You can also use this command to inspect a specific relation type. See [LIST RELATIONS](/reference/sql-syntax/command/list-relations.md) 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](/reference/sql-syntax/command/describe-relation-columns.md).

### Arguments <a href="#parameters" id="parameters"></a>

#### 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`](/reference/sql-syntax/command/use.md)).

## Examples

#### Describe a relation using a current database/schema

The following describes the `pageviews` [Stream](/overview/core-concepts/databases.md#stream) relation in the current `demodb` database and `public` schema:

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

#### Describe a relation using a fully qualified name

The following describes the `pageviews` [Stream](/overview/core-concepts/databases.md#stream) relation in the `demodb` database and `public` schema, using its fully-qualified relation name:

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

#### Describe a changelog

The following describes the `users_log` [Changelog](/overview/core-concepts/databases.md#changelog) in the `demodb` database and `public` schema, using its fully-qualified relation name:

```sh
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](/overview/core-concepts/databases.md#stream) in the `demodb` database and `analytics` schema, using its fully-qualified relation name:

```sh
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](/overview/core-concepts/databases.md#table) in the current database and schema that failed:

```sh
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](/overview/core-concepts/databases.md#stream) relation in the current `demodb` database and `public` schema:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deltastream.io/reference/sql-syntax/command/describe-relation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.