# DESCRIBE QUERY METRICS
## Syntax
```sql
DESCRIBE QUERY METRICS [query_id | query_name[:query_version]]
[WITH (query_metrics_parameter = value [, ...])];
```
## Description
This command provides a snapshot of metrics for a [Streaming or Continuous Query](/overview/core-concepts/queries.md#_streaming_or_continuous_query).\
\
The 4 metrics shown are:
1. `NumRecordsInPerSecond`
2. `NumRecordsOutPerSecond`
3. `NumBytesInPerSecond`
4. `NumBytesOutPerSecond`.
Returned metrics represent a snapshot of the value of each metric at the time this command was run.
{% hint style="info" %}
**Note** Metrics may not always be available for queries. In this case, stats are replaced with `n/a` or with a `02000` SQL error code. The example below displays a query in a terminal state.
{% endhint %}
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
#### 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 latest `query_version` is used.
#### WITH (query\_metrics\_parameter = value \[, ...])
Optionally, this clause specifies [#query-metrics-parameters](#query-metrics-parameters "mention").
### Query Metrics Parameters
| Parameter Name | Description |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FOR METRICS(name[,...])` | Specifies the list of query metrics names to describe.
Required: Yes
Type: METRICS\_NAME
Valid values: numRecordsInPerSecond, numRecordsOutPerSecond, numBytesInPerSecond, numBytesOutPerSecond, consumerRecordsLagMax
|
| `from` | How far in the past from which to return metrics data points.
Required: Yes
Type: METRICS\_RANGE
Valid values: LAST 15 MINUTES, LAST 30 MINUTES, LAST HOUR, LAST 3 HOURS, LAST 6 HOURS, LAST 12 HOURS, LAST DAY
|
## 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 METRICS b2041101-c37c-4807-93d4-2de876b7bd39;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | 6 |
+------------------------+--------+
| NumRecordsOutPerSecond | 5 |
+------------------------+--------+
| NumBytesInPerSecond | 6870 |
+------------------------+--------+
| NumBytesOutPerSecond | 4690 |
+------------------------+--------+
demodb.analytics/demostore# DESCRIBE QUERY METRICS demoquery:1;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | 6 |
+------------------------+--------+
| NumRecordsOutPerSecond | 5 |
+------------------------+--------+
| NumBytesInPerSecond | 6870 |
+------------------------+--------+
| NumBytesOutPerSecond | 4690 |
+------------------------+--------+
```
#### 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 METRICS c81fc632-a043-472d-a1fe-aa81bc9078df;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | 20 |
+------------------------+--------+
| NumRecordsOutPerSecond | 25 |
+------------------------+--------+
| NumBytesInPerSecond | 16870 |
+------------------------+--------+
| NumBytesOutPerSecond | 10690 |
+------------------------+--------+
demodb.analytics/demostore# DESCRIBE QUERY METRICS demoquery:1;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | 20 |
+------------------------+--------+
| NumRecordsOutPerSecond | 25 |
+------------------------+--------+
| NumBytesInPerSecond | 16870 |
+------------------------+--------+
| NumBytesOutPerSecond | 10690 |
+------------------------+--------+
```
#### 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 METRICS c81fc632-a043-472d-a1fe-aa81bc9078df;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | n/a |
+------------------------+--------+
| NumRecordsOutPerSecond | n/a |
+------------------------+--------+
| NumBytesInPerSecond | n/a |
+------------------------+--------+
| NumBytesOutPerSecond | n/a |
+------------------------+--------+
demodb.analytics/demostore# DESCRIBE QUERY METRICS demoquery:1;
+------------------------+--------+
| Key | Value |
+========================+========+
| NumRecordsInPerSecond | n/a |
+------------------------+--------+
| NumRecordsOutPerSecond | n/a |
+------------------------+--------+
| NumBytesInPerSecond | n/a |
+------------------------+--------+
| NumBytesOutPerSecond | n/a |
+------------------------+--------+
```
#### Describe a query's metrics from the last 15 minutes
The following example shows metrics data points available from the last 15 minutes of a given query for the metrics name `numRecordsInPerSecond`, `numRecordsOutPerSecond`, `numBytesInPerSecond`, `numBytesOutPerSecond`, and `consumerRecordsLagMax`:
```bash
demodb.public/demostore# DESCRIBE QUERY METRICS 9c36c3c1-c45e-42ff-b2e4-2e069b313ac3 WITH ('from' = LAST 15 MINUTES , FOR METRICS (numRecordsInPerSecond, numRecordsOutPerSecond, numBytesInPerSecond, numBytesOutPerSecond, consumerRecordsLagMax));
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| Name | Reference Name | Values |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numRecordsInPerSecond | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"6"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numRecordsInPerSecond | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"1"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"1"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numRecordsOutPerSecond | KafkaSink:mr_metrics_082124:_Writer | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"6"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numBytesInPerSecond | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"570 B"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"532 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numBytesInPerSecond | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"177 B"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"169 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| numBytesOutPerSecond | KafkaSink:mr_metrics_082124:_Writer | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"931 B"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"942 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| consumerRecordsLagMax | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"0"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
| consumerRecordsLagMax | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T16:12:34.692-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:27:34.692-07:00","Value":"0"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------+
```
#### Describe a query's metrics from the last 3 hours
The following example shows metrics data points available from the last 15 minutes of a given query for the metrics name `numRecordsInPerSecond`, `numRecordsOutPerSecond`, `numBytesInPerSecond`, `numBytesOutPerSecond`, and `consumerRecordsLagMax`:
```bash
demodb.public/demostore# DESCRIBE QUERY METRICS 9c36c3c1-c45e-42ff-b2e4-2e069b313ac3 WITH ('from' = LAST 3 HOURS, FOR METRICS (numRecordsInPerSecond, numRecordsOutPerSecond, numBytesInPerSecond, numBytesOutPerSecond, consumerRecordsLagMax));
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Reference Name | Values |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numRecordsInPerSecond | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"2"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"4"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numRecordsInPerSecond | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"1"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"1"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numRecordsOutPerSecond | KafkaSink:mr_metrics_082124:_Writer | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"2"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"6"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"5"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"4"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"6"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"5"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numBytesInPerSecond | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"426 B"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"169 B"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"492 B"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"447 B"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"418 B"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"495 B"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"495 B"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"402 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numBytesInPerSecond | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"138 B"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"69 B"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"165 B"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"142 B"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"138 B"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"153 B"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"157 B"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"119 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| numBytesOutPerSecond | KafkaSink:mr_metrics_082124:_Writer | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"787 B"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"243 B"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"904 B"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"729 B"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"578 B"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"950 B"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"872 B"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"714 B"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| consumerRecordsLagMax | Source:_KafkaSource:pv | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"0"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| consumerRecordsLagMax | Source:_KafkaSource:users_log | [{"Timestamp":"2024-08-21T14:43:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T14:58:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:13:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:28:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:43:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T15:58:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:13:22.883-07:00","Value":"0"},{"Timestamp":"2024-08-21T16:28:22.883-07:00","Value":"0"}] |
+------------------------+-------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
```
#### Describe metrics for a query in the `STOPPED` state
The following example show that when a query is in a terminated state — in this case, `STOPPED` — the system returns a SQL code of `02000` instead:
```bash
demodb.public/demostore# DESCRIBE QUERY METRICS 4f5f6a0f-1f71-40ec-902a-0ec821bc36f3 WITH ('from' = LAST 3 HOURS, FOR METRICS (numRecordsInPerSecond));
sql error: no data found (SQLState: 02000) (request ID: ...)
```
---
# 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-metrics.md?ask=
```
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.