From 186fb94aae98a5d43f9ff1004d457b4187a0f324 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 18 May 2026 11:25:29 +0000
Subject: [PATCH] docs: clarify global deduplication behavior for sum_distinct
and average_distinct
---
references/metrics.mdx | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/references/metrics.mdx b/references/metrics.mdx
index 9fc40e6e..b2e19f28 100644
--- a/references/metrics.mdx
+++ b/references/metrics.mdx
@@ -899,6 +899,10 @@ The `sum_distinct` metric requires:
The metric orders by the value being summed and takes the first occurrence for each unique combination of distinct keys. If there are different values for the same distinct key combination, the first one encountered will be used.
+
+Deduplication always happens globally on the `distinct_keys` you define, regardless of which dimensions you select in a query. The resulting total is the same value across every output row — selecting an extra dimension does not break the total down per group. If you need per-group results, set `distinct_keys` to include the grouping field.
+
+
**Example: Summing order shipping costs**
Consider a model containing `order_id`, `order_item_id`, and `order_shipping_cost`:
@@ -1073,6 +1077,10 @@ The `average_distinct` metric requires:
The metric orders by the value being averaged and takes the first occurrence for each unique combination of distinct keys. If there are different values for the same distinct key combination, the first one encountered will be used.
+
+Deduplication always happens globally on the `distinct_keys` you define, regardless of which dimensions you select in a query. The resulting average is the same value across every output row — selecting an extra dimension does not break the average down per group. If you need per-group results, set `distinct_keys` to include the grouping field.
+
+
**Example: Averaging order shipping costs**
Consider a model containing `order_id`, `order_item_id`, and `order_shipping_cost`: