marivo.semantic.cumulative#

marivo.semantic.cumulative(*, name, base, over=None, anchor=None, unit=None, domain=None, ai_context=None)[source]#

Declare a cumulative metric over a tier-1 base metric.

The anchor selects the accumulation shape. None (default) is the v1 all-history running total: the observe window clips displayed rows but does not reset the value. ms.grain_to_date(grain=...) resets at each reset-grain boundary (MTD/QTD/YTD). ms.trailing(count=..., unit=...) is a fixed-size rolling window where empty windows are true zero.

Parameters:

  • name (str) – Metric name.

  • base (Ref[MetricKind]) – Tier-1 simple aggregate metric ref to accumulate.

  • over (Ref[TimeDimensionKind] | None) – Time dimension ref defining the accumulation axis. Prefer passing this explicitly. When omitted, load succeeds only if the base metric root entity has exactly one time dimension.

  • anchor (GrainToDate | Trailing | None) – Accumulation anchor. None for all history (default), ms.grain_to_date(...) for period resets, or ms.trailing(...) for a rolling window.

  • unit (str | None) – Optional output unit override. Defaults to the base metric unit at load.

  • domain (Ref[DomainKind] | None) – Override the active domain namespace.

  • ai_context (AiContextValue | None) – Optional agent-facing context.

Returns:

A Ref[metric] for the derived cumulative metric.

Return type:

Ref[MetricKind]

Example

>>> # MTD revenue
>>> mtd_revenue = ms.cumulative(
...     name="mtd_revenue", base=revenue, over=event_time,
...     anchor=ms.grain_to_date(grain=mv.grain("month")),
... )
>>> # Rolling-7d active users
>>> rolling7_active = ms.cumulative(
...     name="rolling7_active", base=active_users, over=event_time,
...     anchor=ms.trailing(count=7, unit="day"),
... )
Constraints:

The base aggregation must be sum, count, or count_distinct. grain_to_date requires a grain-compatible query grain; trailing requires a fixed-size span that is an integer multiple of the query grain and a time grain.