# 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](https://docs.deltastream.io/overview/core-concepts/queries#_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](https://docs.deltastream.io/overview/core-concepts/queries) 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](https://docs.deltastream.io/reference/sql-syntax/command/list-queries) 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](https://docs.deltastream.io/reference/sql-syntax/command/list-queries) 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](https://docs.deltastream.io/reference/sql-syntax/command/list-queries) 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](https://docs.deltastream.io/overview/core-concepts/databases#_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](https://docs.deltastream.io/overview/core-concepts/databases#_stream), `pageviews`, and a [Changelog](https://docs.deltastream.io/overview/core-concepts/databases#_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: ...)
```