Variable Query¶

View variable queries are used to define the value range and data source of a variable. They support configuring whether the value range follows the dashboard time widget, meeting different data filtering needs.

Value Range Control¶

The selectable values obtained by a query can be configured to be affected by the dashboard time range:

Main Query Types¶

View variables support five query types. You can choose as needed:

DQL Query¶

Supports all data types including metrics, logs, infrastructure, objects, traces, and RUM. The most comprehensive.

Click Learn more about DQL definition and syntax.

Basic Syntax Structure¶

<data_type>::<data_source>:(distinct('<attribute_field_name>')){<filter_conditions>}

Example:

# Get host names of all Docker containers
O::docker_containers:(distinct(`host`))

Time Range Specification¶

DQL supports specifying time ranges directly in the statement, which takes precedence over the dashboard time widget:

Example:

# Show only hosts with data in the last 10 minutes
O::docker_containers:(distinct(`host`)) [10m]

Show Function Query¶

Used to query metric-related metadata information. Does not support time range.

Syntax Structure¶

Click Learn more about DQL functions.

Example:

# Query all measurements
SHOW METRIC_SET()

# Query all tags of a specified measurement
SHOW LABELS FROM M::cpu

PromQL Query¶

PromQL queries support writing query statements manually. By default, they use the time range selected in the dashboard time widget to query and return data.

For more information about PromQL queries, refer to PromQL Quick Start.

Data Type Query¶

If you need quick configuration without writing query statements, you can directly select a data type and choose filter conditions on the page.

Supported data types:

• Metrics
• Basic Objects (hosts, containers, processes, etc.)
• Resource Catalog
• Logs
• APM
• RUM

In this mode, you cannot add time ranges or configure cascading queries.

External Database¶

If the target selectable values are stored in an external database (such as MySQL, PostgreSQL), you can choose this query type to directly connect to an existing data system.

1. Select a data source;
2. Enter a query statement;
3. Choose the sorting method.

For more details, refer to External Data Source.

External Function¶

If the target selectable values need to be obtained through custom function logic, you can choose this query type to call external functions registered in the workspace to dynamically generate the candidate value list.

1. Select a function: choose from the external functions registered in the current workspace;
2. Add function parameters as needed, fill in the parameter name and corresponding value; supports referencing other view variables in the dashboard using the format #{variable_name}. When the referenced variable changes, the system automatically re-calls the function and refreshes the candidate values;
3. Value field: specifies which field in the function's returned data will be used as the candidate value for the variable (❗️Optional; if not set, the system defaults to the first field in the returned data; to return the value of a specific field, manually enter the field name).

This query type does not support adding time ranges or configuring cascading queries.

Custom Query¶

If the target selectable values are fixed and limited in number, no database query is needed. You can directly define a set of values for the view variable, separated by commas ,. For example: prod,test,dev,staging.

This query type does not support adding time ranges or configuring cascading queries.

Cascading Query¶

Used when multiple variables have a hierarchical relationship. For example:

• After selecting a "service", the "environment" dropdown only shows the environments of that service (not all environments).
• After selecting an "environment", the "version" dropdown only shows the versions of that environment.

Configuration Conditions¶

1. Only DQL queries support cascading configuration;
2. In the child variable's query statement, use #{parent_variable_name} to reference the current value of the parent variable.

Configuration Example¶

The following uses the view variable cascading filter in the Web application overview of RUM as an example, illustrating the configuration of cascading queries based on service, environment, and version:

You need to configure three variable query statements in the dashboard. The second and third query statements use #{variable_name} configured in the first query:

• Variable 1 (Service): Query all application lists:

T::re(`.*`):(distinct(service))

• Variable 2 (Environment): Query the environment list filtered by the selected service in Variable 1:

T::re(`.*`):(distinct(env)) { service = '#{service}'}

• Variable 3 (Version): Query the version list filtered by the selected environment in Variable 2:

T::re(`.*`):(distinct(version)) {service = '#{service}'}

Query Scenario Examples¶

Linking to Charts¶

1. In the chart query, when filtering a field, select the variable as the value;
2. Switch the variable value in the scene view, and the chart will be filtered and displayed according to the variable tag.

Reverse Application from Chart¶

1. Click on a specific time series or data point in the chart;
2. Select Apply to View Variable;
3. The system automatically fills in the query.