DESCRIBE QUERY

Syntax

DESCRIBE QUERY query_uid;

Description

This provides the definition of a Streaming or Continuous Query, in addition to the metadata and metrics that show the state of the query within the system. The four metrics that are shown are NumRecordsInPerSecond, NumRecordsOutPerSecond, NumBytesInPerSecond, and NumBytesOutPerSecond. The records in/out represent the current rate of messages being processed in and out at the time the DESCRIBE QUERY call was made. The Bytes in/out represent the current rate of data being processed and represented in binary Bytes at the time the call was made as well.

Note: Metrics may not always be available for queries, and when unavailable the stats will be replaced with n/a; see the example below with a query that has ERRORED.

See Query on how streaming queries operate in DeltaStream.

The Query will only be visible if the current role has USAGE privileges.

Arguments

query_uid

This is the unique identifier of the query to describe. See LIST QUERIES to find out how to list all queries that the user has access to. The first column (ID) in the response corresponds with the query_id.

Examples

Describe a simple query

The following describes a simple query with a Changelog source Relation, users_log, filtering on a userid column and writing the results into a Changelog sink Relation, users2468_log:

demodb.analytics/demostore# DESCRIBE QUERY b2041101-c37c-4807-93d4-2de876b7bd39;
                   ID                  |  State  |                                                                          DSQL                                                                           |  Owner   |      Created at      |      Updated at       
---------------------------------------+---------+---------------------------------------------------------------------------------------------------------------------------------------------------------+----------+----------------------+-----------------------
  b2041101-c37c-4807-93d4-2de876b7bd39 | RUNNING | CREATE CHANGELOG users2468_log   AS SELECT *   FROM users_log   WHERE userid = 'User_2' OR userid = 'User_4' OR userid = 'User_6' OR userid = 'User_8'; | sysadmin | 2023-01-12T20:46:00Z | 2023-01-12T20:46:00Z  
Sources:
    Changelog users_log
Sinks:
    Changelog users2468_log

Query Stats:
  NumRecordsInPerSecond | NumRecordsOutPerSecond | NumBytesInPerSecond | NumBytesOutPerSecond  
------------------------+------------------------+---------------------+-----------------------
                      6 |                      5 | 67 B                | 49 B                  

Describe a multi-source query

The following describes a JOIN query that joins a Stream, pageviews, and a Changelog Relation, users_log, on a userid column and writes the resulting records into a pv_user2468_interest Changelog Relation:

demodb.analytics/demostore# DESCRIBE QUERY c81fc632-a043-472d-a1fe-aa81bc9078df;
                   ID                  |  State  |                                                                                                               DSQL                                                                                                               |  Owner   |      Created at      |      Updated at       
---------------------------------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+----------------------+-----------------------
  c81fc632-a043-472d-a1fe-aa81bc9078df | RUNNING | CREATE STREAM pv_user2468_interest WITH ('store'='kinesis_main')   AS SELECT p.userid AS pvid, u.userid AS uid, u.gender, p.pageid, u.interests[1] AS top_interest   FROM pageviews p   JOIN users_log u ON u.userid = p.userid; | sysadmin | 2023-01-12T20:46:27Z | 2023-01-12T20:46:27Z  
Sources:
    Changelog users_log
    Stream pageviews
Sinks:
    Stream pv_user2468_interest

Query Stats:
  NumRecordsInPerSecond | NumRecordsOutPerSecond | NumBytesInPerSecond | NumBytesOutPerSecond  
------------------------+------------------------+---------------------+-----------------------
                     20 |                     25 | 160 B               | 200 B                  

Describe an ERRORED query

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

demodb.analytics/demostore# DESCRIBE QUERY e2f995eb-1ece-4c19-8909-72cf75910091;
                   ID                  |  State  |                                  Dsql                                   |  Owner   |      Created At      |      Updated At       
---------------------------------------+---------+-------------------------------------------------------------------------+----------+----------------------+-----------------------
  e2f995eb-1ece-4c19-8909-72cf75910091 | ERRORED | CREATE STREAM userid AS SELECT userid as userid, pageid FROM pageviews; | sysadmin | 2022-05-25T15:37:01Z | 2022-05-25T15:37:01Z  
Sources:
    Stream pageviews
Sinks:
    Stream userid

Query Stats:
  NumRecordsInPerSecond | NumRecordsOutPerSecond | NumBytesInPerSecond | NumBytesOutPerSecond  
------------------------+------------------------+---------------------+-----------------------
                    n/a |                    n/a | n/a                 | n/a   
Errors:
    <error stack is printed here>