# DESCRIBE QUERY STATE

## Syntax

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

## Description

This command provides a snapshot of the source relations' position in a terminated [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.

### 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 the user has 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 the user has 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 the user has access. The column (`Version`) in the response corresponds with the `query_version`. If `query_name` is provided without a `query_version`, the system uses the latest `query_version`.

## Examples

#### State for an active query

The following example shows that an active query does not report any state information:

```sh
demodb.public/demostore# DESCRIBE QUERY STATE 24f5a97b-97e9-40eb-8dbf-431b96474972;
+----------------+-------------+-------+
|  Relation Name |  Store Type |  Info |
+================+=============+=======+
+----------------+-------------+-------+

demodb.public/demostore# DESCRIBE QUERY STATE demoquery:1;
+----------------+-------------+-------+
|  Relation Name |  Store Type |  Info |
+================+=============+=======+
+----------------+-------------+-------+
```

#### State for a terminated query

The following example shows that the described query was operating on a single source, `demodb.public.pagevviews`, in a store of type Kafka, and was at the offset `28899068` in partition `0` when the query was terminated:

```bash
demodb.public/demostore# DESCRIBE QUERY STATE 24f5a97b-97e9-40eb-8dbf-431b96474972;
+---------------------------+-------------+-----------------------------+
|  Relation Name            |  Store Type |  Info                       |
+===========================+=============+=============================+
| demodb.public.pagevviews  | KAFKA       | partition:0,offset:28899068 |
+---------------------------+-------------+-----------------------------+

demodb.public/demostore# DESCRIBE QUERY STATE demoquery:1;
+---------------------------+-------------+-----------------------------+
|  Relation Name            |  Store Type |  Info                       |
+===========================+=============+=============================+
| demodb.public.pagevviews  | KAFKA       | partition:0,offset:28899068 |
+---------------------------+-------------+-----------------------------+
```


---

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