Query metric data from Grafana Mimir on Grafana Labs

Best practices for querying Grafana Mimir

Wed, 03 Jun 2026 09:01:40 +0200

Best practices for querying Grafana Mimir

The way you write queries for Grafana Mimir affects the speed and quality of your results. Follow these best practices to ensure optimal performance and reliability for queries.

Use label matchers

To reduce the initial size of your dataset, apply label matchers to your query. Label matchers help you to filter your data based on its associated labels. For example, if you have a label called app_name, you can append app_name="myapp" to your query.

Whenever possible, use an exact label match, such as label="value", instead of a regular expression, such as label=~"pattern". Regular expressions are more computationally expensive.

For more information about how to query metric labels, refer to Query metric labels.

Narrow down your time range

Limit your query to a specific time period to reduce the number of metrics and samples Mimir needs to process. As a best practice, query the shortest feasible time range to narrow down your results. Larger time ranges require more computing resources and increase query latency.

Follow these guidelines for setting a time range based on your query type:

Dashboards: For dashboards, use a time range that matches the typical viewing window. While users can zoom out to view more history, the default view should be efficient and focused on recent, relevant data.
Alerting rules: Alerting rules should almost always operate on short, recent time windows to detect current states or recent trends, rather than long-term historical patterns. Timely alerts depend on the quick evaluations of fresh data.
Ad-hoc analysis: When exploring data, start with small time ranges and gradually expand if more historical context is required for your investigation. This iterative approach prevents unnecessary strain on the system during exploratory phases.

Additionally, choose a step interval that matches your requirements for running the query. Smaller step intervals increase a query’s cost but provide higher resolution.

Consider your query evaluation frequency and time range

Consider the evaluation frequency of your query when determining the time range. For instance, if a query runs every minute, such as for an alerting rule or a frequently refreshing dashboard panel, there’s no need for it to look back over a long time period, such as 30 days.

Queries with very long look-back periods, such as rate(my_metric[30d]), can be computationally expensive. They require Mimir to process a large volume of historical data, even if only the latest value is of interest.

Filter early in the query

Avoid running broad, large-scale queries and then filtering the results within Grafana. This approach is computationally expensive and inefficient. Instead, filter your data as early as possible in the query itself.

Filtering data in the query provides the following benefits:

Reduced data transfer: Filtering at the query level means Mimir sends only the data you need to Grafana, which reduces network overhead.
Lower processing load: Mimir can apply filters at the storage layer, allowing it to discard irrelevant time series and data points before they are retrieved, processed, and aggregated. This significantly reduces the computational load on the Mimir cluster.
Improved query speed: Queries that are pre-filtered are generally faster to run and return results.

Use these strategies to implement early filtering:

Use label selectors: Leverage precise label selectors within your PromQL query to narrow down the dataset from the start. For more information, refer to Use Label Selectors.
Apply functions and aggregations: If you need to transform or aggregate data, do so within the query. For example, sum by (job) (metric_name) is more efficient than retrieving all metric_name series and then summing them in Grafana.

Use recording rules

If you need to run a particularly expensive or complex query, consider creating a recording rule to minimize its load. Recording rules in Mimir involve precomputing queries at a predetermined time and then saving the results for faster retrieval later.

Recording rules are useful for the following types of queries:

Dashboard queries that run frequently
Complex aggregations across high-cardinality metrics
Queries spanning long time ranges

Recording rules are most beneficial for queries with results that you frequently evaluate. If you use a recording rule for a query and don’t frequently evaluate its results, it could lead to unnecessary computation and data storage.

For more information about recording rules, refer to Defining recording rules in the Prometheus documentation.

Query metric labels

Wed, 03 Jun 2026 09:01:40 +0200

Query metric labels

Grafana Mimir supports multiple HTTP API endpoints to query metric label names and values. There are differences and trade-off between these API endpoints.

Querying label names

The following API endpoints find the list of label names of all (or a subset of) series stored in Mimir:

Get label names
GET,POST <prometheus-http-prefix>/api/v1/labels
Label names cardinality
GET,POST <prometheus-http-prefix>/api/v1/cardinality/label_names

Note
<prometheus-http-prefix> is the Prometheus HTTP prefix as documented in the HTTP API reference. The default prefix is /prometheus.

Recommendations and performance trade-off

Prefer get label names over label names cardinality API, unless you need to know the number of unique label values for each label name.
The get label names API start and end parameters are optional. When omitted, Mimir will query label names for the whole retention period or up to the configured -store.max-labels-query-length. We recommend to always specify start and end parameters, and preferably set them to the shortest period that is feasible for your use case.
For both API endpoints, executing a request specifying the series selector is computationally more expensive than the same request without the series selector. However, the results set might be significantly smaller when the series selector reduces the series set.

Features comparison

The different API endpoints have different features, and the main differences follow.

Can specify the time range in the request?

Get label names
Yes. However, the actual time range granularity is restricted to TSDB block range periods, which are 2h for the most recent metrics, and up to 24h for historical metrics when running Mimir with the default configuration. In practice, the input start and end parameters are rounded to the TSDB block boundaries:
- The start parameter is rounded to the start of the nearest block containing samples with timestamps that are greater than or equal to the input timestamp.
- The end parameter is rounded to the end of the nearest block containing samples with timestamps that are less than or equal to the input timestamp.
Label names cardinality
No. The API queries only the in-memory series in the ingesters that hold series for the tenant.

Can specify the series selector in the request?

Get label names API
Yes. The optional match[] parameter makes it possible to select the series from which to read the label names. The match[] parameter can be specified multiple times. When omitted, label names are extracted from all series.
Label names cardinality API
Yes. The optional selector parameter makes it possible to select the series from which to read the label names. The selector parameter can be specified only once. When omitted, label names are extracted from all series.

Querying label values

The following API endpoints find the list of label values for a given label name:

Get label values
GET <prometheus-http-prefix>/api/v1/label/{name}/values
Label values cardinality
GET,POST <prometheus-http-prefix>/api/v1/cardinality/label_values

Note
<prometheus-http-prefix> is the Prometheus HTTP prefix as documented in the HTTP API reference. The default prefix is /prometheus.

Recommendations and performance trade-off

Prefer get label values over label values cardinality API, unless you need to know the number of series for each label name and value.
The get label values API makes it possible to specify a single label name, and the label values cardinality API makes it possible to specify multiple label names. If you need to get the label values for multiple label names, we recommend issuing multiple get label values requests instead of a single label values cardinality API call with multiple label names.
The get label values API start and end parameters are optional. When omitted, Mimir will query label values for the whole retention period or up to the configured -store.max-labels-query-length. We recommend to always specify start and end parameters, and preferably set them to the shortest period that is feasible for your use case. The longer the time range, the more computationally expensive the request is.
For both API endpoints, executing a request specifying the series selector is computationally more expensive than the same request without the series selector. However, the results set might be significantly smaller when the series selector reduces the series set.

Features comparison

The different API endpoints have different features, and the main differences follow.

Can specify the time range in the request?

Get label values API
Yes. However, the actual time range granularity is restricted to TSDB block range periods, which are 2h for the most recent metrics, and up to 24h for historical metrics when running Mimir with the default configuration. In practice, the input start and end parameters are rounded to the TSDB block boundaries:
- The start parameter is rounded to the start of the nearest block containing samples with timestamps that are greater than or equal to the input timestamp.
- The end parameter is rounded to the end of the nearest block containing samples with timestamps that are less than or equal to the input timestamp.
Label values cardinality API
No. The API queries only the in-memory series in the ingesters that hold series for the tenant.

Can specify the series selector in the request?

Get label values API
Yes. The optional match[] parameter makes it possible to select the series from which to read the label values. The match[] parameter can be specified multiple times. When omitted, label values are extracted from all series.
Label values cardinality API
Yes. The optional selector parameter makes it possible to select the series from which to read the label names and values. The selector parameter can be specified only once. When omitted, label names and values are extracted from all series.

Alternatives

The following API endpoints have not been explicitly designed to query metric label names and values, but label names and/or values can be extracted from the response:

Get series by label matchers
GET,POST <prometheus-http-prefix>/api/v1/series
Instant query
GET,POST <prometheus-http-prefix>/api/v1/query

Note
<prometheus-http-prefix> is the Prometheus HTTP prefix as documented in the HTTP API reference. The default prefix is /prometheus.

Recommendations and performance trade-off

Prefer get label names over other APIs to get the list of label names. The get label names is expected to always perform better than other APIs.
Prefer get label values over other APIs to get the list of label values.
- If you’re experiencing a slow response time when querying get label values API, the request includes a series selector and the series selector is expected to match a small set of series (order of few thousands), then consider using get series by label matchers instead of the get label values API.
- If you can’t use get series by label matchers API (e.g. the API is not available in the client you’re using), then fallback to the instant query API.