This article explores vector matching in PromQL, focusing on arithmetic operations between instant vectors with shared and differing labels.
In this article, we explore vector matching in PromQL, focusing on arithmetic operations between two instant vectors. Previously, most examples demonstrated operations between an instant vector and a scalar. Here, we dive deeper into matching vectors based on shared and differing labels.
You may want to calculate the percentage of free filesystem space by dividing available bytes by total size bytes and multiplying by 100. For example, assume you have these sample data points:
PromQL performs this operation by matching series that have exactly the same labels. In the example above, both metrics contain the labels instance, job, and mountpoint. A perfect match on these labels ensures that each division occurs correctly.
Every label must match exactly. A mismatch or an extra label on either metric will prevent the match from occurring.
For example, this mismatch will not produce a result:
One-to-one matching is the default behavior where every element in the left-hand vector matches with a single element in the right-hand vector. This scenario occurs when all series have identical sets of labels.
Many-to-one matching occurs when each element on one side corresponds to multiple elements on the other side. For instance, consider an HTTP error metric where multiple error codes exist for a single endpoint paired with a single total requests metric.When there are more matching series on one side, PromQL produces an error stating “multiple matches for labels.” To manage this, use group_left or group_right to explicitly define the matching relationship:
group_left: Indicates that multiple series on the left should match with a single series on the right.
group_right: Indicates that a single series on the left should match with multiple series on the right.
For example, if HTTP errors are on the left and HTTP requests on the right, and you want to match on the path label, the query would be:
This query aggregates multiple error series (grouped on the left) with the corresponding request series (on the right).
If the situation were reversed, you could use group_right.The image below demonstrates a concrete example of a query utilizing group_right for many-to-one matching in PromQL:
Prometheus processes this query by matching each series in the available bytes metric with the corresponding series in the size bytes metric. Labels such as device, fstype, instance, job, and mountpoint must match exactly. Any discrepancy—such as an extra or missing label—will cause the operation to fail.
Both approaches yield a value of 0.48, meaning 48% of the requests resulted in an error.If you have multiple error series (e.g., separate series for error 400 and error 500) corresponding to a single request series, you must use group_left (or group_right, depending on your data structure):
By mastering vector matching techniques—whether one-to-one or many-to-one using ignoring, on, group_left, or group_right—you can construct sophisticated PromQL queries that accurately aggregate and compare metrics. For further reading, consider exploring these resources:
