Metric attribution¶
Every dashboard raises the same question: why did this metric change? Dosi answers it with two tools, one call each:
attribute_metricssplits 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_dimensionssplits 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")
{
"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,CASEand 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,includeandexcludemetrics, andfixedfields used as dimensions or filters. COUNT(DISTINCT x)byattribute_dimensionsonly by fieldsxdetermines — each value ofxhas 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 whenxis its key, the fields of a datasetxleads to through a many-to-one relationship, a relationship's column whose pairxdetermines, afixedfield keyed byxwhose 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 adeterminesdeclaration 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'sonly_bylists them. Byattribute_metrics, always. OtherDISTINCTaggregates 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
unsupportedwithstate_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_secsin 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. |