Skip to content

Metric attribution

Every dashboard raises the same question: why did this metric change? Dosi answers it with two tools, one call each:

  • attribute_metrics splits the change over the metric's formula. Average order value fell by 106: falling revenue took 731 off it, fewer orders added 624 back.
  • attribute_dimensions splits the change by the groups of one or more fields. Of the same 106, the west region accounts for 262, and orders with no customer region pulled the other way by 195.

Both give every part its contribution to the change (its effect), and the contributions add up to the change exactly. Each is a Shapley value: the part's average effect on the metric over every order in which the parts can be switched from the baseline to the current period. A ratio, a product or a CASE therefore gets one split that does not depend on which part is looked at first. A contribution says how much a part moved the metric, not why the part itself moved.

The two tools are on every surface: the CLI (dosi attribute-metrics, dosi attribute-dimensions), REST (POST /v1/query/attribute-metrics, /v1/query/attribute-dimensions), MCP (the attribute_metrics and attribute_dimensions tools) and Python (Engine.attribute_metrics, Engine.attribute_dimensions).

Quick start

The example model's avg_order_value is SUM(orders.amount) / COUNT(orders.order_id). Between January and February 2025 it fell from 687.36 to 581.00. First, which part of the formula did it:

export DOSI_EXAMPLES=~/.local/share/dosi/examples
duckdb orders.duckdb < "$DOSI_EXAMPLES/orders/seed.sql"
dosi --model "$DOSI_EXAMPLES/orders/model.yaml" --format json attribute-metrics \
  --metric avg_order_value \
  --baseline 2025-01-01..2025-02-01 \
  --current  2025-02-01..2025-03-01 \
  --db orders.duckdb
import os
from dosi_engine import Engine

engine = Engine(os.path.join(os.environ["DOSI_EXAMPLES"], "orders/model.yaml"))
result = engine.attribute_metrics({
    "metric": "avg_order_value",
    "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
    "current":  {"start": "2025-02-01", "end": "2025-03-01"},
}, db_path="orders.duckdb")
curl -s localhost:8080/v1/query/attribute-metrics \
  -H 'content-type: application/json' \
  -d '{"metric": "avg_order_value",
       "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
       "current":  {"start": "2025-02-01", "end": "2025-03-01"}}'
{"name": "attribute_metrics",
 "arguments": {"metric": "avg_order_value",
               "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
               "current":  {"start": "2025-02-01", "end": "2025-03-01"}}}
{
  "schema_version": 3,
  "status": "complete",
  "metric": "avg_order_value",
  "algorithm": "exact_subset",
  "accuracy": "exact",
  "tree": {
    "label": "avg_order_value", "metric": "avg_order_value",
    "expression": "SUM(orders.amount) / COUNT(orders.order_id)",
    "baseline": 687.36, "current": 581.0, "delta": -106.36,
    "effect": -106.36, "share": 1.0,
    "children": [
      {"label": "revenue", "metric": "revenue", "atom": "revenue",
       "expression": "SUM(amount)",
       "baseline": 4811.49, "current": 1743.0, "delta": -3068.49,
       "effect": -730.59, "share": 6.87},
      {"label": "order_count", "metric": "order_count", "atom": "order_count",
       "expression": "COUNT(order_id)",
       "baseline": 7.0, "current": 3.0, "delta": -4.0,
       "effect": 624.24, "share": -5.87}
    ]
  },
  "issues": [],
  "execution": {"queries_executed": 2, "rows_fetched": 2, ...}
}

Revenue fell by two thirds, and on its own that would have cut the average by 731. The order count fell too, which on its own raises the average, by 624. The two pull against each other, which is why the shares are larger than 1 and of opposite signs.

Then, where it moved. revenue and order_count are metrics, so either can go to the second tool; so can avg_order_value itself:

dosi --model "$DOSI_EXAMPLES/orders/model.yaml" --format json attribute-dimensions \
  --metric avg_order_value \
  --dimensions customers.region \
  --baseline 2025-01-01..2025-02-01 \
  --current  2025-02-01..2025-03-01 \
  --db orders.duckdb
{
  "status": "complete",
  "metric": "avg_order_value",
  "dimensions": ["customers.region"],
  "tree": {
    "label": "avg_order_value",
    "baseline": 687.36, "current": 581.0, "delta": -106.36, "effect": -106.36,
    "groups_total": 3, "others": null,
    "children": [
      {"label": "west", "key": {"region": "west"},
       "baseline": 1212.0, "current": 62.0, "delta": -1150.0,
       "effect": -262.40, "share": 2.47},
      {"label": "(null)", "key": {"region": null},
       "baseline": 351.50, "current": null, "current_status": "missing_row",
       "delta": null, "effect": 194.73, "share": -1.83},
      {"label": "east", "key": {"region": "east"},
       "baseline": 848.33, "current": 840.5, "delta": -7.83,
       "effect": -38.69, "share": 0.36}
    ]
  },
  "issues": []
}

A group's baseline and current are the metric computed on that group alone: the west's own average order fell from 1212 to 62. Its effect is what that did to the whole, −262.40. The orders without a region were all in January; their absence in February raised the overall average by 194.73. The three effects add up to −106.36.

Reading a result

Every result has schema_version: 3, the metric, a status, the tree, issues and execution (statements sent, rows read, time taken).

Nodes. Every node has its own two values, baseline and current, their delta, and its effect: what it contributed to the root's change, in the metric's unit. share is the effect over the root's delta (null when the metric did not change). A share above 1 or below 0 means other parts moved the other way. The root's effect is the whole change, and a parent's is the sum of its children's.

The metric tree (attribute_metrics). The root is the metric. A composed metric's children are the metrics and aggregates it is computed from, as deep as the formula goes. A leaf is one place an aggregate is read, with its atom name and binding (datasets, the filter it is computed under, its time axis). Contributions are computed per aggregate: one aggregate read in several places, such as a revenue that is both a ratio's numerator and part of its denominator, has a leaf in each place, and its whole effect is the sum of the leaves with that atom. A node's metric is the model metric it is; it is null for a formula in between, and for a metric whose members are read differently inside this one. A node with a metric can be passed to attribute_dimensions.

The dimension tree (attribute_dimensions). The root is the metric. Under it are the groups of the first field, under each of those its groups by the next field, and so on. Each group has its label (its value) and key (every field fixed down to its level). The tree lists at most top_groups groups (20 unless the request says otherwise): the ones with the largest effects across all levels, together with the groups above them. Under each node, groups_total is how many groups it has and others sums the ones not listed (group_count, effect, share). The listed effects plus others add up to the node's effect. Every group is in the computation, listed or not, so top_groups changes what is listed, never a number.

Several dimensions are one drill-down: --dimensions customers.region,orders.status splits each region by status, and the regions' effects are the same as with customers.region alone. To compare two views that are not one inside the other (by region, and by status), make two calls.

Missing values. A null value says why next to it: baseline_status / current_status is null_value (the query returned NULL), missing_row (the period has no row for the group) or not_defined (the group has no value of its own, as a group of a ranked row has no rank). Its effect is still there.

Exact, derived or sampled. An exact Shapley value takes a number of evaluations that doubles with every participant (an aggregate, or a group at one level). Up to 20 participants it is computed exactly. Beyond that, a metric whose aggregates add up across groups gets its group effects from those sums, still exactly; otherwise the engine samples orders of the participants until the standard error is small. accuracy is exact, derived (from additive aggregates), sampled or mixed. A sampled node carries uncertainty (sample_stddev, standard_error), and a group whose place among its siblings is within that noise has rank_unstable: true.

Status and issues. status is about the metric, not the call:

status Meaning
complete Done, within the precision asked. A sampled result can be complete.
partial Not finished: a budget ran out or a check did not pass. issues say what is usable.
not_computable There is nothing to split: the metric has no value in a period, or in a state between the two (a denominator that is zero there).
unsupported Not attributed by the engine, or not within its limits.
invalid_request The target is not one: an unknown metric, a binding or a filter the metric does not take.

issues say why, each with a stable code, a severity, a message and often a suggested_action. When the status is not complete, report the issue rather than the numbers.

The request

Both tools take a metric query with two periods in place of one:

Field
metric One metric per call.
baseline, current Half-open {start, end} periods on the metric's time axis; dimension, the same on both, picks another axis. On the CLI: --baseline START..END, --current START..END, --time-dimension.
where_sql A condition on fields, as in a metric query. A condition on a metric is refused.
context_filter A condition on the rows, applied before anything is aggregated.
params D-PARAM bindings, one value per parameter (one set for a multiple parameter).
group_by The grain the metric is computed at. See below.
dimensions attribute_dimensions only: the fields to split by, dataset.field or dataset.field:grain.
top_groups attribute_dimensions only: how many groups to list, 1 to 200, default 20.

group_by is not dimensions. dimensions is what the change is split by. group_by is for a metric whose value depends on a grouping: a rank among markets, a share of the market total, a change on the period before, a moving average. The number explained is then one row of that grouped query, and where_sql fixes every grouped field with field = value. For a metric that ranks markets by revenue:

{"metric": "market_revenue_rank",
 "group_by": [{"field": "stores.market"}],
 "where_sql": "stores.market = 'east'",
 "baseline": {"start": "2025-01-01", "end": "2025-02-01"},
 "current":  {"start": "2025-02-01", "end": "2025-03-01"}}

An ordinary metric for one market needs no group_by: where_sql alone selects it. With group_by it is the same number, also in a period that has no data for the market and so no row in the grouped query: the row's value there is the metric over no rows, a count 0 and a sum NULL, and the result says so with a no_rows_in_period note. Three such rows have no value and are undefined_endpoint: one of a metric that reads other rows (a rank, a share, a window), one grouped by month in a month with no data, and one with no data in either period. A metric with required dimensions needs them in group_by, as a query does. A window over time reads the buckets before the one explained, so each period is whole buckets of the window's grain, and the last bucket of each is the one explained.

Which dimensions?

Which fields explain a change is a question about the business, so the engine does not pick them. dosi list dimensions --metric <name> (and the MCP list_dimensions tool) lists what a metric can be grouped by, recommended first; what feeds the list, declared or inferred, is described under D-DIM. A call without dimensions is refused with dimensions_required, whose candidates are the same list without the time axes: the two periods are the time axis already.

Requests that fail

A request that is not one fails the call, before any statement:

code
invalid_comparison The two periods are not ranges on one axis.
dimensions_required No dimensions. Its candidates are the fields the metric can be split by, best first.
dimension_repeated The same field twice.
top_groups_out_of_range top_groups outside 1 to 200.
bad_request A field the request does not have, or a value of the wrong type.

The error has the code and the field_path at fault: JSON on the CLI's stderr, HTTP 400 over REST, a tool error over MCP, a QueryError with detail["field_path"] in Python. A policy denial or a warehouse failure fails the call as it fails a metric query.

What can be attributed

The metric catalog says, per metric and per tool, what the model allows: dosi list metrics --format json, GET /v1/metrics and the MCP list_metrics / describe_metric tools give each metric an attribution field such as {"metrics": {"supported": true}, "dimensions": {"supported": false, "code": "insufficient_state", ...}}. When attribute_dimensions can split a metric by some of its fields only, dimensions lists every one of them by dataset: {"supported": true, "only_by": [{"name": "orders", "fields": ["region"]}, …]}. A call can still be refused for what only its request or the data decides.

Supported by both tools unless noted:

  • SUM, COUNT, AVG, MIN, MAX, variance and standard deviation, and arithmetic, CASE and the common numeric functions over them.
  • Derived metrics: filters, composes at any depth, fills, and cross-fact composes, split by the dimensions both facts share.
  • Window metrics: period-over-period values, differences and ratios, moving and running windows, shares of a partition total, and ranks.
  • Levels of detail: fixed, include and exclude metrics, and fixed fields used as dimensions or filters.
  • COUNT(DISTINCT x) by attribute_dimensions only by fields x determines — each value of x has one value of them, so no value is counted in two groups and the groups add up to the whole: the fields of the dataset when x is its key, the fields of a dataset x leads to through a many-to-one relationship, a relationship's column whose pair x determines, a fixed field keyed by x whose value a period cannot move (the period does not land on its base's rows, or its keys decide the time field it lands on, the default one or the one the request names, and the count is cut on that field too) or a field that reads one, and the fields a determines declaration lists. So also where a rank, a partition total or an offset reads the count: each row's groups add up to the row. Not where a level of detail reads it. The catalog's only_by lists them. By attribute_metrics, always. Other DISTINCT aggregates are not split by dimensions.

Common reasons a result is unsupported or not_computable:

code What it means What to do
insufficient_state The aggregate's groups do not add up to the whole: a distinct count by a field its argument does not determine. Split by a field the issue's suggested action lists; otherwise split it with attribute_metrics, or split a metric it is computed from.
no_primary_time_dimension The metric has no time field to cut two periods on. The model has to give it one.
target_row_not_fixed group_by without where_sql fixing every grouped field. Add field = value for each.
dimension_is_time_axis A split by the axis the periods are on. Split by another field, and compare buckets with a query.
undefined_counterfactual A state between the two periods has no value (a denominator that is zero there). Pick other periods, or split the numerator and the denominator separately.
state_too_large, budget_exceeded More rows or evaluations than the limits allow. Fewer dimensions, a narrower where_sql, or shorter periods.
nondeterministic_order row_number or ntile with ties at the target row. Use a rank that allows ties.
dimension_not_aligned A group comes back twice (a NULL key on several branches of a cross-fact metric), or a distinct count's value is in two groups: a declaration the data breaks, or a relationship some of its rows do not match. Exclude the group with context_filter; for a distinct count, correct the declaration or split by another field.

Dry run

dry_run (--dry-run, ?dry_run=true, dry_run=True) sends nothing and opens no connection. It binds the request, compiles every statement a call would send for the dialect (dialect, else the connection's type, else DuckDB; DWS also needs dws_mode), and says whether anything refuses it before the data does:

{
  "dry_run": true,
  "status": "attributable",             // or unsupported / invalid_request
  "algorithm_candidates": ["exact_subset"],
  "evaluations_upper_bound": 6,
  "runtime_checks": ["endpoint_mismatch", "undefined_counterfactual", ...],
  "statements": [{"purpose": "totals", "period": "baseline",
                  "sql": "SELECT CAST(SUM(orders.amount) AS DOUBLE PRECISION) / ..."}, ...],
  "tree": {...}                         // the metric tree, without values
}

runtime_checks are the issue codes only the data can still raise. A dry run applies no SQL policy and takes none; over REST it is answered by a server whose execution is disabled. The MCP tools have no dry run: list_metrics already says whether a metric can be attributed.

Limits

  • At most 10,000 rows per aggregate and period are fetched for one split. A split that needs more is unsupported with state_too_large, and no number is reported.
  • Exact Shapley values for up to 20 participants; beyond that, derived from additive aggregates or sampled, as described above.
  • A dimension tree lists at most 200 groups.
  • The whole call runs under one timeout: timeout_secs in Python, the server's execute timeout over REST and MCP.

Moving from attribute

The earlier single tool is deprecated and will be removed: dosi attribute and Engine.attribute print a deprecation warning, and POST /v1/query/attribute is marked deprecated. The MCP tool attribute_metric has been replaced by the two tools. Its results map onto the new ones as follows:

attribute Now
total_change The root of either tree.
dimension_ranking, top_dimension_values One attribute_dimensions call per dimension; its tree is the groups.
mix_effect, rate_effect of a ratio attribute_metrics: the effects of the numerator and the denominator.
factors, per_member attribute_metrics: the metric tree.
drill_down.where_sql A group's key, written as field = value conditions.
segment_kind: entered / exited baseline_status / current_status: missing_row.
strategy: unsupported status: unsupported and its issues.
NotComputableError, HTTP 422 status: not_computable in the result.