DQL Query¶

Click Guance console's Shortcut > Query Tool to open the query explorer, or you can directly open the query tool via shortcut keys Alt+Q or option+Q.

Click the Simple Query and PromQL Query buttons on the right side of the DQL Query to switch the query method.

Return Results¶

Enter a query statement in the DQL query window and click Execute to view the query results in the Return Results section.

The query results will be displayed in table format, and the system defaults to returning up to 2,000 data entries. You can also export these data as a CSV file.

Note: When using DQL query statements, you can use the slimit parameter to control the number of returned query results.

JSON¶

Query results support viewing in JSON format. If the DQL query returns an error result, the error message will be directly prompted in the JSON.

Query History¶

Query history supports viewing up to 100 query history records for the last 7 days on a daily basis, and it supports fuzzy search for query statements.

Click the execute button on the right side of the query history data to directly display the corresponding query statement and its results.

DQL Syntax¶

DQL queries follow the syntax paradigm below; the relative order between parts cannot be changed. From a syntactic perspective, data-source is mandatory (similar to the FROM clause in SQL), while other parts are optional.

For more DQL syntax introduction, refer to the document DQL Definition.

namespace::
    data-source
    target-clause
    filter-clause
    time-expr
    by-clause
    limit-clause
    offset-clause
    slimit-clause
    soffset-clause

Example Explanation¶

Below is a simple example, querying the usage_idle (CPU idle rate) field of the time-series Metrics set cpu through DQL, filtering by host, and grouping the results by host. Here, #{host} is a view variable set in the Guance dashboard used for filtering.

Applying the above statement to the chart query of the Guance scenario dashboard, the following figure combines expression queries and DQL queries to display the CPU usage rate for the past 15 minutes.

DQL Functions¶

In addition to being used in scenario dashboards, DQL queries can also be used to query various data collected by DataKit, such as data sources, fields, tags, etc., via DQL functions.

SHOW Function¶

The SHOW function is used to display various types of data. If there is no clear understanding of the data sources, fields, tags, etc., collected by DataKit, the SHOW function can be used to query them in the DQL query explorer.

Below, the SHOW function is used to query the sources, fields, etc., of "objects" and "logs".

For more function introductions, refer to the documents DQL Functions and DQL Outer Functions.

show_object_source()¶

Displays the Metrics sets for object data.

show_object_field()¶

Displays the fields list for objects.

show_object_label()¶

Displays the label information included in the object.

show_logging_source()¶

Displays the Metrics sets for log data.

show_logging_field()¶

Displays all fields lists under the specified source.

Time Query¶

In DQL query statements, you can specify [today], [yesterday], [this week], [last week], [this month], [last month] time parameters.

today: from 0 o'clock today to the current time;

yesterday: from 0 o'clock yesterday to 0 o'clock today;

this week: from 0 o'clock this Monday to the current time;

last week: from 0 o'clock last Monday to 0 o'clock this Monday;

this month: from 0 o'clock on the first day of this month to the current time;

last month: from 0 o'clock on the first day of last month to 0 o'clock on the first day of this month;

Example Writing¶

Query data from 0 o'clock today to now without a time interval, returning one data point:

M::cpu:(avg(`useage`)) [today]

For example, query data from 0 o'clock today to now with a 5-minute time interval, returning aggregated data points:

M::cpu:(avg(`usage`)) [today:5m]

Expression calculations can also support querying data from two different time periods for final result calculations. If there are multiple different time parameter definitions in the expression, such as subquery A and subquery B defining time parameters as [today] and [yesterday], respectively, the final data return value's time will be filled according to the now() time at the time of the query, ultimately returning one data point.

If a time interval is defined in the expression, and the time points of multiple queries do not align, such as subquery A and subquery B defining time parameters as [today:5m] and [yesterday:5m], respectively, the data points' times do not match, making addition, subtraction, multiplication, and division impossible. In this case, Guance will default to returning a null value.