Using the Query Editor

This section describes the features of the Query Editor for Monitoring Query Language (MQL) Query Editor. The editor is available in the Google Cloud Console and provides suggestions, error detection, and other support for creating valid MQL queries.

This page doesn't cover the MQL language; for a set of examples and for more information about the language, see Examples and About the MQL language. MQL Reference provides a comprehensive reference for the language.

Accessing the Query Editor

You access the Query Editor from the following pages in the Google Cloud Console:

  • Metrics Explorer
  • Add Chart when creating dashboards

The following screenshot uses Metrics Explorer as an example:

The MQL selector appears just above the "Resource type and metric" box.

To bring up the Query Editor, click Query Editor on the Metric tab. The following screenshot shows the Query Editor:

The MQL Query Editor.

Using the Query Editor

To use the Query Editor, type your query into the text box and click Run Query:

MQL query in the Query Editor.

Autocompletion

As you type your query, the editor displays a list of syntactically valid completions. You can manually bring up the autocompletion menu by pressing Control+Space, and you can dismiss it by pressing Escape.

To navigate the list of options, use the arrow keys. Pressing Enter inserts the selected choice.

To insert the prefix common to all available choices, press Tab.

Error messages

Error messages appear at the bottom of the editor pane.

If there are errors in the query that interfere with autocompletion suggestions, error messages appear as you type. Otherwise, error messages appear when you run the query.

Leaving the Query Editor

To exit the Query Editor without saving a chart or condition, click Return to Basic Editor. Any query text in the editor is discarded, but you are given the option to save it to the clipboard.

Editor controls

The editor has three controls that determine how it works.

The MQL Query Editor controls.

By default, your query is executed only when you click Run Query. You can set up the Query Editor to automatically execute your query as you type, but this option is disabled by default.

To enable the auto-execute option, use the Auto-execute toggle. When this option is enabled, the editor works as follows:

  • The Run Query button isn't displayed.
  • Errors messages appear continuously as you type.
  • If your cursor is at the end of a query that is incomplete but has no errors, the editor shows a yellow triangle in the control bar. If there is room, the text Incomplete query also appears.

    The Query Editor does not attempt to evaluate incomplete queries.

To reformat the query so that it's more readable, click Format. Reformatting the query doesn't change the meaning of the query. Reformatting uses a line-length of 80 characters, so if your Query Editor window is less than that, the lines wrap.

There is also a grab-bar between the Query Editor and the chart region. Use this bar to change the relative sizes of the two regions.

Saving charts

From Metrics Explorer

From the Query Editor in Metrics Explorer, you have the option to save your chart to a dashboard. To save your chart, do the following:

  1. If you do not have the auto-execute option enabled, run your query by clicking Run Query before saving the chart. If you don't run your query first, the Query Editor saves the last query you ran.

  2. Click Save Chart. A dialog box tells you that saving the chart replaces the query with a strict form. For more information, see Strict-form queries.

  3. To continue saving the chart:

    1. Give the chart a descriptive title.
    2. Select the desired dashboard for the new chart.
    3. Click Save on the dialog.

From a dashboard

To save a chart that you are adding to a dashboard, do the following:

  1. Give the chart a descriptive title.

  2. If you do not have the auto-execute option enabled, run your query by clicking Run Query before saving the chart. If you don't run your query first, the Query Editor saves the last query you ran.

  3. Click Save. A dialog box tells you that saving the chart replaces the query with a strict form. For more information, see Strict-form queries.

  4. Click Save on the dialog to save your chart and return to the dashboard.

Time ranges, charts, and the Query Editor

Except for MQL queries used in conditions for alerting policies, MQL queries in the Query Editor must include a time period. The time period specifies the subset of data to return as part of the query.

The time period can be expressed implicitly by using the chart's time selector or explicitly in your MQL query text.

For information on creating alerting policies with the Query Editor, see Creating MQL alerting policies.

Using chart settings for time selection

You can set the time period for a query by using the chart's time selector. This selector is the default way to set the time period. To change the time period, select a different time option on the chart. If you select, for example, one week, then your query returns the data from now to a week ago.

MQL can use chart-specified times.

When you use this default mechanism, you don't have to specify an explicit time range in the text of your query. The value on the chart is used implicitly.

Using within for time selection

You can specify the time range for the query explicitly in the query by using the within operation. This operation determines the range of returned data. If your query includes a within operation, then the time-selection options on the chart are disabled, and the time range specified in the query is used.

If you remove an explicit within operation from your query, the chart options are automatically re-enabled, ensuring that your query always includes a time period.

You must use explicit time selection if you want to use the API method timeSeries.query to issue the query. For more information, see Using MQL from the Monitoring API.

Time settings and saved charts

If you use MQL to create a chart and then save the chart to a dashboard, two things happen to your query:

  1. The query you provided in the editor is converted into a canonical, or strict, form. The conversion doesn't change the meaning of your query, but it makes explicit things that are assumed in the query, like full column names or alignment operations. For more information, see Strict-form queries.

  2. The time-range selection in your query is removed. Charts on dashboards share a time selector, and changes to that selector apply to all charts on the dashboard. Therefore, the time-range selector from the original query is no longer needed.

For information on managing dashboards and editing charts, see Managing dashboards.

Query, alignment, and display periods

MQL has a number of potentially confusing operations that specify time periods. The following operations are related to the range of a query:

  • within: specifies the query-output window. This operation determines how much data is returned. If, for example, you specify within 1h, then the query produces only points whose timestamps are within the last hour, which is why this operation overrides the chart's time-selector options.

  • The following operations relate to the alignment period of their output tables. Both require an aligned table as input, or they supply a default:

    • every: specifies the period for aligned table output.

    • window: specifies the window for alignment operations.

    In both cases, if an align operation is provided with an explicit alignment window, it must match the period specified for the window operation, if provided. For the delta alignment function, the alignment window and period must be the same; if an explicit alignment window is given, then the every operation, if given, must agree. In all cases, the alignment window must be at least as large as the alignment period or input data will be ignored.

MQL also has a graph_period operation, which specifies the period of output points for charts. This operation is useful in queries given to the API whose output is being charted by third-party software. The Monitoring charting software ignores the graph_period operation in queries, setting the period of points according to the width in time of the output chart.

In Monitoring charts, the graph period is set based on the value of the chart's time-range selector. For example, if you select one week, the graph period might be one hour. This value is shown on a small box with rounded corners, called a chip, in the chart region. The chip showing the graph period has a label like 1 hr interval. The following screenshot shows a graph-period chip indicating a one-hour interval and the chart's time selector set to one week:

The chart's time selector determines the graph period, seen on a chip on the chart.

The relationship between the query alignment period and the graph period can change the way a chart looks. This relationship is described in the following section.

Min/max bands

When the query alignment period is close to the graph period, the chart represents each graphed time series with a single line. If the query alignment period is less than half of the graph period of the chart, the chart includes a shaded region around each line. This region, called a min/max band, shows the range of values that produced the mean value.

For example, assume the following simple MQL query:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by [zone], mean(val())
| every 1h

This query returns the mean CPU uilization of VMs by zone, with a one-hour alignment period.

If the chart's time selector is set to one week, then the graph period is one hour, which is indicated on a chip. For the example query, the graph period and alignment period are equal. Running the query produces a chart that looks like the following:

A line chart with equal alignment and graph periods shows only lines.

For example, if you change the alignmnent period passed to the every operation from 1h to 1m in the previous query, then the query produces a chart that includes the min/max bands:

A line chart with an alignment period less than half the graph period shows lines and min-max bands.

The chart lines are graphed with a graph period of one hour, based on the one-week selection for the chart, so the lines are the same as those in the previous example. But the query produces a point every minute, so the min/max bands show the range of one-minute values from the query that fall into each one-hour graph point.

If the every operation is omitted, the default query alignment period is either the value of the alignment window or, if the alignment window is not specified, one minute.

MQL-based alerting policies

You can also use MQL and the Query Editor to create queries for use in alerting policies.

To create a MQL-based alerting policy from the Google Cloud Console, you follow the usual steps for creating the policy, described in Managing alerting policies, but when you create the condition for the alerting policy, you use the Query Editor instead of the form-based metric selector.

For more information, see Creating MQL alerting policies.

Query conversion

You can use the metric selector for charts or in Metrics Explorer to create a query, and then convert that query to MQL by clicking Query Editor. The corresponding MQL query is shown in the editor.

Consider a very simple request, such as "Get the CPU usage from my Compute Engine VM instances." This query involves the gce_instance monitored-resource type and the compute.googleapis.com/instance/cpu/usage_time metric type.

The following screenshot shows this query in the form-based metrics selector:

Selecting a metric and resource type in the metrics selector.

The metric and monitored-resource types were entered manually. The Aligner and Alignment Period values under Advanced Aggregation are defaults.

When you click Query Editor, the query in the form-based selector is converted into a MQL query. The following screenshot shows the result of the conversion:

Editor shows the result of converting the form's values to MQL.

The MQL query fetches the time series for the specified metric and resource types and performs rate alignment on 1 minute intervals. The converted query is in strict format.