--- title: "Querying Metrics" description: "Learn how to query metrics in Middleware dashboards, from picking a data source and metric to filtering, aggregating, grouping and transforming the results." section: "Metrics" breadcrumb: "Metrics > Querying Metrics" canonical: "https://docs.middleware.io/features/metrics/querying-metrics" --- # Querying Metrics You query metrics in the widget editor of a dashboard. Each widget holds one or more **queries**, and each query describes which metric to read, which data to keep, and how to combine it into the lines, bars or numbers the widget shows. You build queries with the visual query builder, so there's no query language to learn. This page gives an overview of the query flow. For every option in detail, see the [Dashboard builder](/features/dashboards/builder) guide. ## Open the query builder 1. Go to **Dashboards** and open a dashboard, or create one with **Create Dashboard**. 2. Click **Add Widget** and choose a data source. 3. Pick a **Graph Type**, such as Timeseries, List Value or Query Value. The graph type affects which query options are available. The widget editor shows a live preview at the top and the query builder below it. ![Widget editor with the graph types on the left, the live chart preview at the top, and the query builder with Look For, the metric picker, from filter, aggregation and group by below it.](/images/v2/dashboard-builder/understand-the-widget-editor.webp) ## Build a query step by step A query reads from left to right in the query builder. Each step narrows or shapes the data a little more. ### 1. Choose the data source Use **Look For** to pick the resource that emits the metric, such as Host, Container or Service. It defaults to **All Metrics**, which lets you search every metric. [Learn more](/features/dashboards/builder#look-for). ### 2. Pick a metric Search for the metric in the metric picker. Each metric shows a badge for its type (**GAUGE**, **SUM**, **HIST**, **SUMMARY**, **EXP_HIST**), and hovering over it shows its unit, description and attributes. The type decides which aggregations and functions are offered; see [Types of Metrics](/features/metrics/types-of-metrics). You can also pick an attribute instead of a metric, for example `host.id`, to count its unique values. [Learn more](/features/dashboards/builder#define-the-query). ### 3. Filter the data Use the **from** box to keep only the data you need, for example `host.name = metrics-anomaly`. You can use operators such as `=`, `!=`, `IN`, `LIKE` and `REGEX`, and combine conditions with `AND`, `OR` and brackets. The default, **everywhere**, keeps data from all sources. [Learn more](/features/dashboards/builder#define-the-query). Keep in mind: - `LIKE` always matches values that **contain** the text: `host.name LIKE prod` matches `prod-1` and `eu-prod`. Use `REGEX ^prod` for "starts with". - `AND` and `OR` are applied from left to right with the same precedence, so use brackets when you mix them. - Quote values that contain brackets or operator words with straight double quotes, for example `service.name = "orders (in queue)"`. ![Query for system.cpu.utilization filtered with host.name = metrics-anomaly in the from box, aggregated avg by host.name.](/images/v2/dashboard-builder/metric-and-filter.webp) ### 4. Aggregate and group Choose how to combine data from many sources into one series, with the aggregation dropdown: **avg by**, **sum by**, **min by**, **max by**, **last**, **uniq by** or **count by**. Add one or more attributes in **group by**, such as `host.name`, to get one series per value instead of one combined series. [Learn more](/features/dashboards/builder#4.4-choose-aggregation-and-aggregation-group). ### 5. Set the time aggregation Under **Show Advanced Options**, **Roll Up** controls how data points are combined over time: the method (**Average**, **Sum**, **Minimum**, **Maximum**, **Last**) and the bucket size in seconds. Leave the size on `auto` to let Middleware pick it from the time range. A size smaller than the automatic one for the time range is raised to it. Metric queries cover at most the last 7 days of the selected range, but the bucket size still follows the range you selected, so a 30-day range shows 7 days in 8-hour buckets. [Learn more](/features/dashboards/builder#roll-up). ### 6. Transform with functions Click **Add Function** to apply functions to the result, for example **Rate** to turn a counter into a per-second rate, **EWMA** to smooth a noisy line, **Week before** to compare with last week, or **Top** to keep only the busiest groups. [Learn more](/features/dashboards/builder#4.8-transform-results-with-functions). ### 7. Reduce to one value (single-value widgets) On widgets that show one number per group, such as List Value or Query Value, **Reduce values in timeframe to** collapses the selected time range into that number with **avg**, **sum**, **min**, **max** or **last**. [Learn more](/features/dashboards/builder#reduce-values-in-timeframe-to). ## Combine queries with formulas Add several queries to one widget with **Add Query**. Each query gets a letter (a, b, c…), and **Add Formula** lets you combine them with `+`, `-`, `*`, `/`, numbers and brackets, for example `(a / b) * 100` to calculate a percentage. Give the queries the same **group by** so their series line up. Division by zero gives 0, not a gap. [Learn more](/features/dashboards/builder#4.7-compose-results-with-formulas). ## Polish the result - **Alias Name** replaces the metric name in the legend and tooltips. [Learn more](/features/dashboards/builder#5.1-alias-name). - **Unit** sets how values are displayed, such as bytes, percent or `/s`. [Learn more](/features/dashboards/builder#unit). - **Sort by** and **Limit** control the order and number of results on single-value widgets. [Learn more](/features/dashboards/builder#5.4-sort-by-and-limit). ## Quick reference | I want to… | Use | | --- | --- | | See one line per host | **group by** `host.name` | | See the busiest host, not the average | **max by** in the aggregation dropdown | | Turn a request counter into requests per second | **Add Function → Rate → Rate** | | Smooth a noisy line | **Add Function → Smoothing → EWMA** | | Compare today with last week | A second query with **Add Function → Timeshift → Week before** | | Show one number per host in a table | List Value widget, **group by** `host.name`, **Reduce values in timeframe to** | | Calculate a ratio or percentage | Two queries and **Add Formula** | ## Next steps - Learn how each metric type behaves in [Types of Metrics](/features/metrics/types-of-metrics). - See exactly how values are combined in [Understanding Aggregations](/features/metrics/understanding-aggregations). - Explore every option in the [Dashboard builder](/features/dashboards/builder) guide. Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us page or join our Slack channel.