Grafana Query Editor
The query editor is the engine inside every panel. It sends requests to your data source and retrieves the numbers that Grafana draws as charts. Each data source has its own query language and editor interface, but all of them follow the same pattern: you describe what you want, Grafana fetches it, and the panel shows it.
The Library Card Analogy
A query is like a library request slip. You fill in the title, author, and publication year. The librarian (data source) fetches the exact book (data) that matches your request. A vague request returns many books; a precise request returns the exact one you need. Good queries are specific and efficient.
Anatomy of the Query Editor
┌───────────────────────────────────────────────────────────────────┐
│ Query A [Run query] [🗑] │
│ ──────────────────────────────────────────────────────────────────│
│ Data source: Prometheus │
│ Metric: [node_cpu_seconds_total ] │
│ Labels: [mode="idle" ] │
│ Operations: rate() → avg by(instance) → multiply(-100) + 100 │
│ Legend: {{instance}} │
│ Min interval: 1m │
└───────────────────────────────────────────────────────────────────┘
Builder Mode vs Code Mode
The Prometheus query editor in Grafana offers two modes, selectable with a toggle at the top right of the query section.
Builder Mode
Builder mode presents dropdown menus and form fields. You pick the metric name from a list, select label filters from dropdowns, and add mathematical operations by clicking buttons. No knowledge of PromQL syntax is required. Builder mode is ideal for beginners.
Code Mode
Code mode shows a plain text input field where you type raw query language directly — PromQL for Prometheus, SQL for MySQL, LogQL for Loki. Code mode gives you full power and flexibility, including complex functions and multi-step calculations. Switch between modes freely; they show the same query in different forms.
Query Options
Each query has a set of options that control how Grafana requests and processes data.
Min Interval
The minimum time bucket Grafana uses when requesting data. If you view a 24-hour window, Grafana might request per-minute data. If you set Min Interval to 5m, it requests per-5-minute data instead, reducing the number of data points and improving load speed.
Max Data Points
Limits the maximum number of data points returned. Grafana calculates this from the panel width — a 300-pixel-wide panel does not need more than 300 data points because you cannot see the difference.
Instant Query (Prometheus)
An instant query returns a single value at the current moment rather than a range over time. Use it for Stat and Gauge panels where you want the current reading, not a trend line.
Time Range Override
By default, all panels on a dashboard use the same time range. The Time Range Override lets a specific panel use a different range — for example, always show the last 30 days even when the dashboard is set to Last 1 hour. This is useful for KPI summary panels at the top of a dashboard.
Multiple Queries and Aliases
Add multiple queries (A, B, C…) to the same panel to overlay multiple series on one chart. Each query produces one or more lines. The Legend field of each query labels the lines in the chart.
Query A: rate(http_requests_total{status="200"}[5m])
Legend: Successful Requests
Query B: rate(http_requests_total{status="500"}[5m])
Legend: Error Requests
Result on chart:
── Successful Requests (blue line)
── Error Requests (red line)
Disabling a Query Without Deleting It
Click the eye icon next to a query label to hide that query's result from the chart without deleting the query. This is useful for temporarily removing a noisy line while investigating an incident.
MySQL / SQL Query Editor
When using a SQL database as the data source, the query editor shows a SQL input box. You write standard SELECT statements. Grafana provides special macros to make time filtering easier.
SELECT $__timeGroupAlias(created_at, $__interval), count(*) AS "New Users" FROM users WHERE $__timeFilter(created_at) GROUP BY 1 ORDER BY 1
The macros $__timeFilter and $__timeGroupAlias automatically use the dashboard's current time range. You do not hard-code date values in the query — Grafana fills them in dynamically.
Inspect Panel – Viewing Raw Query Results
Hover over any panel and click the three-dot menu → Inspect → Data. Grafana shows the raw data table returned by the query. This helps you verify whether the query returned the expected values before worrying about chart settings.
Inspect → Data view: ┌────────────────────┬──────────────┐ │ Time │ Value │ ├────────────────────┼──────────────┤ │ 2024-03-01 12:00 │ 45.3 │ │ 2024-03-01 12:01 │ 47.1 │ │ 2024-03-01 12:02 │ 46.8 │ └────────────────────┴──────────────┘
The Inspect → Query tab shows the exact query string sent to the data source, including any variable substitutions. This is the most valuable debugging tool in Grafana when a panel does not show the expected data.
Explore – Testing Queries Before Adding to a Dashboard
Use the Explore section (left sidebar → compass icon) to experiment with queries without being inside a dashboard panel. Explore gives you a quick chart and a table view of results. Paste a working query from Explore into a panel editor once you confirm it returns the right data.