docs: clarify dimension interaction with distinct_keys

references/metrics.mdx

@@ -1055,6 +1055,20 @@ With `distinct_keys: [order_id, item_warehouse_location]`:
   </Tab>
 </Tabs>
 
+**How selected dimensions interact with `distinct_keys`**
+
+Deduplication is always performed globally on the `distinct_keys` you defined on the metric, regardless of which dimensions you select in a query. This matches the semantics of equivalent metrics in Looker.
+
+- If a selected dimension is also a `distinct_key`, the metric is grouped by that dimension and you get one deduplicated value per group.
+- If a selected dimension is **not** part of `distinct_keys`, it does not affect deduplication. The globally deduplicated value is repeated across every row that shares the same `distinct_keys` value.
+
+For example, with `distinct_keys: [order_id]`:
+
+- Selecting `order_id` returns one deduplicated shipping cost per order.
+- Selecting an unrelated dimension such as `customer_country` returns the same global deduplicated total alongside each country row, because `customer_country` is orthogonal to the `order_id` grain.
+
+If you want a per-group total that varies with an unrelated dimension, add that dimension to `distinct_keys` so it becomes part of the dedup grain.
+
 ### average_distinct
 
 <Warning>
@@ -1233,6 +1247,8 @@ With `distinct_keys: [order_id, item_warehouse_location]`:
   </Tab>
 </Tabs>
 
+`average_distinct` follows the same rules as `sum_distinct` for how selected dimensions interact with `distinct_keys`. See [How selected dimensions interact with `distinct_keys`](#sum_distinct) for details.
+
 ### string
 
 Used with fields that include letters or special characters.