# DESCRIBE QUERY

## Syntax

```sql
DESCRIBE QUERY [query_id | query_name[:query_version]];
```

## Description

This command provides additional information about a [Streaming or Continuous Query](/overview/core-concepts/queries.md#_streaming_or_continuous_query) created in the current [Organization](/overview/core-concepts/access-control.md#organiation).

See [Query](/overview/core-concepts/queries.md) on how streaming queries operate in DeltaStream.

The query is visible only if the current role has `USAGE` privileges.

See also [DESCRIBE QUERY METRICS](/reference/sql-syntax/command/describe-query-metrics.md), [DESCRIBE QUERY EVENTS](/reference/sql-syntax/command/describe-query-events.md), [DESCRIBE QUERY STATE](/reference/sql-syntax/command/describe-query-state.md).

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

#### query\_id

This is the unique identifier of the query to describe. See [LIST QUERIES](/reference/sql-syntax/command/list-queries.md) to find out how to list all queries to which you have access. The first column (`ID`) in the response corresponds with the `query_id`.

#### query\_name

This is the name of the query to describe. See [LIST QUERIES](/reference/sql-syntax/command/list-queries.md) to find out how to list all queries to which you have access. The column (`Name`) in the response corresponds with the `query_name`. The `query_version` property disambiguates between multiple queries with the same name.

#### query\_version

This is the version of the query to describe. See [LIST QUERIES](/reference/sql-syntax/command/list-queries.md) to find out how to list all queries to which you have access. The column (`Version`) in the response corresponds with the `query_version`.

## Examples

#### Describe a simple query

The following describes a simple query with a [Changelog](/overview/core-concepts/databases.md#_changelog) source relation, `users_log`, filtering on a `userid` column and writing the results into a Changelog sink relation, `users2468_log`:

```sh
demodb.analytics/demostore# DESCRIBE QUERY b2041101-c37c-4807-93d4-2de876b7bd39;
+-----------+--------------------------------+
|  Property |  Value                         |
+===========+================================+
| state     | running                        |
+-----------+--------------------------------+
| source    | changelog users_log            |
+-----------+--------------------------------+
| sink      | changelog users2468_log        |
+-----------+--------------------------------+

demodb.analytics/demostore# DESCRIBE QUERY demoquery:1;
+-----------+--------------------------------+
|  Property |  Value                         |
+===========+================================+
| state     | running                        |
+-----------+--------------------------------+
| source    | changelog users_log            |
+-----------+--------------------------------+
| sink      | changelog users2468_log        |
+-----------+--------------------------------+
```

#### Describe a multi-source query

The following describes a `JOIN` query that joins a [Stream](/overview/core-concepts/databases.md#_stream), `pageviews`, and a [Changelog](/overview/core-concepts/databases.md#_changelog) relation, `users_log`, on a `userid` column and writes the resulting records into a `pv_user2468_interest` changelog relation:

```sh
demodb.analytics/demostore# DESCRIBE QUERY c81fc632-a043-472d-a1fe-aa81bc9078df;
+-----------+--------------------------------+
|  Property |  Value                         |
+===========+================================+
| state     | running                        |
+-----------+--------------------------------+
| source    | changelog users_log            |
+-----------+--------------------------------+
| source    | stream pageviews               |
+-----------+--------------------------------+
| sink      | stream pv_user2468_interest    |
+-----------+--------------------------------+

demodb.analytics/demostore# DESCRIBE QUERY demoquery:1;
+-----------+--------------------------------+
|  Property |  Value                         |
+===========+================================+
| state     | running                        |
+-----------+--------------------------------+
| source    | changelog users_log            |
+-----------+--------------------------------+
| source    | stream pageviews               |
+-----------+--------------------------------+
| sink      | stream pv_user2468_interest    |
+-----------+--------------------------------+
```

#### Describe an ERRORED query

The following describes a query stopped due to an unrecoverable failure, leaving it in the `ERRORED` state:

```sh
demodb.analytics/demostore# DESCRIBE QUERY c81fc632-a043-472d-a1fe-aa81bc9078df;
+-----------+-----------------------+
|  Property |  Value                |
+===========+=======================+
| state     | errored               |
+-----------+-----------------------+
| source    | stream pageviews      |
+-----------+-----------------------+
| sink      | stream users          |
+-----------+-----------------------+
| error     | <error stack here>    |
+-----------+-----------------------+

demodb.analytics/demostore# DESCRIBE QUERY demoquery:1;
+-----------+-----------------------+
|  Property |  Value                |
+===========+=======================+
| state     | errored               |
+-----------+-----------------------+
| source    | stream pageviews      |
+-----------+-----------------------+
| sink      | stream users          |
+-----------+-----------------------+
| error     | <error stack here>    |
+-----------+-----------------------+
```


---

# 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-query.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.