Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Queries and Transformations

The Grafana Query Editor, Query Options and Query Inspector

Learn how the Grafana query editor works: queries A, B, C, max data points, min interval, $__interval, relative time and the Query Inspector for debugging.

Every panel in Grafana is driven by one or more queries. You write them in the query editor below the panel preview, and each query belongs to one data source. This lesson explains the parts of that editor, the options that control how much data comes back, and the Query Inspector, the tool you open when a panel shows something strange.

Grafana itself cannot run on this site, so the steps below describe the interface in words. The TryIt blocks are small Python stand-ins that reproduce the arithmetic Grafana performs, so you can see why a panel behaves the way it does. They are not Grafana.

Anatomy of the query editor

When you edit a panel, the lower half of the screen has three tabs: Queries, Transformations and Alert (the alert tab appears for visualizations that can drive alerts). On the Queries tab you see:

  • A data source picker at the top. Choosing -- Mixed -- lets each query use a different data source.
  • One or more query rows, named A, B, C and so on. The letter is the query's reference ID (refId). Expressions and transformations use that letter to point at the query.
  • A Query options button next to the data source picker.
  • A Query inspector button.
  • + Query and + Expression buttons.

Each row has an eye icon to hide the query without deleting it, a duplicate button, a trash button, and a menu for the editor mode. Many data sources offer a Builder mode (pick metrics and labels from dropdowns) and a Code mode (type the raw query). You can switch between them, and the builder can usually parse a query you typed by hand, but a complex query may only work in code mode.

The shape of the query depends on the data source. A Prometheus row holds PromQL, a PostgreSQL row holds SQL, a Loki row holds LogQL. What every row has in common is the same model on the wire: Grafana sends the browser's request to its own backend, the backend calls the data source, and the answer comes back as one or more data frames. A data frame is a table of typed columns; a time series is a frame with a time column and a number column.

Query options

Click Query options and you see the settings that apply to all queries in the panel:

Option What it does
Max data points The most points per series the panel will ask for. Defaults to the width of the panel in pixels.
Min interval The smallest step between points. Normally set to the data source's scrape or collect interval.
Interval Read-only: the step Grafana calculated from the time range and max data points.
Relative time Replaces the dashboard time range for this panel, for example now-1h.
Time shift Moves the panel's range backwards, for example 1d to compare with yesterday.
Cache timeout Time to live of a cached result, when query caching is available.
Hide time info Hides the small "Last 1h" label that relative time and time shift add.

The calculation behind Interval is the reason a panel for a 30-day range does not download millions of points. Grafana divides the time range by max data points, then rounds up to a "nice" step such as 10s, 1m, 5m, 1h or 1d, and never goes below the min interval. The result is available inside the query as the built-in variables $__interval (for example 5m) and $__interval_ms (milliseconds). SQL and Prometheus queries use it for GROUP BY and for range selectors.

Python Stand-in: how Grafana picks the interval

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You will see that wider ranges get coarser steps, and that the min interval (15s here) acts as a floor. If your data is scraped every minute, set the min interval to 1m; otherwise Grafana may ask for 15-second steps and you get gaps or repeated values.

Relative time and time shift

The dashboard time picker sets one range for every panel. Relative time overrides it for a single panel: setting now-5m makes a "last 5 minutes" stat on a dashboard that otherwise shows 24 hours. Time shift keeps the length of the range but slides it back, which is how you draw "this week versus last week": duplicate the query's panel, set a time shift of 7d on the copy, and overlay them. The panel header shows a small note such as "Last 5 minutes" so viewers are not misled, unless you tick Hide time info.

Query Inspector

When a panel is empty, wrong or slow, press Query inspector (or the keyboard shortcut i while hovering a panel, or choose Inspect in the panel menu). The drawer has these tabs:

  • Stats: total request time, data processing time, number of queries, and the total rows returned.
  • Query: the request and response for each query as the browser saw them. Click Refresh to re-run and watch the exact request URL or body. This is where you copy the real SQL or PromQL after variables were substituted.
  • JSON: the panel JSON, the raw data frames, or the DataFrame JSON (after transformations). Handy for filing bug reports and for copying a panel to another dashboard.
  • Data: the result as a table, with options to apply transformations, format the time, and Download CSV.
  • Error: visible only when a query failed, with the message from the data source.

A typical debugging flow is: open the inspector, read the Error tab, then check the Query tab to see whether $__interval or a dashboard variable expanded the way you expected, and finally compare the Data tab against what the visualization displays.

Python Stand-in: expand variables like the Query tab shows

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second line shows a typo ($regoin) that Grafana leaves unreplaced; the inspector makes this obvious because the sent query still contains the dollar sign.

flowchart LR
    P["Panel"] --> Q["Queries A, B, C"]
    Q --> O["Query options<br/>interval, relative time"]
    O --> B["Grafana backend"]
    B --> D["Data source"]
    D --> F["Data frames"]
    F --> T["Transformations"]
    T --> V["Visualization"]

Queries produce data frames, transformations reshape them, and the visualization draws the result. The inspector sits across the whole chain.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the letter on a query row (A, B, C) identify?

    The letter is the query's refId, used by expressions and transformations.
  2. 2. A panel covers 30 days and has max data points of 1000. What stops Grafana from requesting a point every second?

    Interval is range divided by max data points, rounded to a nice step, with min interval as the floor.
  3. 3. Which setting draws 'this week versus last week' by moving a copy of the panel's range back by seven days?

    Time shift slides the range backwards while keeping its length; relative time replaces the range.
  4. 4. Where do you see the exact query text sent to the data source after variables were expanded?

    The Query tab shows the request and response; the Data tab shows the returned rows.

Summary

  • The query editor holds one row per query (A, B, C), each with a data source and a builder or code mode.
  • Query options control max data points, min interval, relative time and time shift for the whole panel.
  • $__interval and $__interval_ms come from the time range, max data points and min interval.
  • The Query inspector has Stats, Query, JSON, Data and (on failure) Error tabs; start there when a panel looks wrong.
  • Results travel as data frames, which transformations can reshape before they are drawn.

Next: Prometheus Queries in Grafana