marivo.semantic#

marivo.semantic - Python-native semantic layer (v1.1).

Public surface:

import marivo.datasource as md
import marivo.semantic as ms

catalog = ms.load()                # returns SemanticCatalog
catalog = ms.load(domains=['sales'])  # filter to specific domains
catalog.domains.show()
catalog.metrics.show()                                  # all metrics across domains

ms.domain(name="sales", owner="Mina Zhang", default=True)
warehouse = md.duckdb("warehouse").ref
orders = ms.entity(name="orders", datasource=warehouse, source=md.table("orders"))
amount = ms.measure_column(
    name="amount", entity=orders, column="amount",
    additivity="additive", unit="USD",
)

revenue = ms.aggregate(name="revenue", measure=amount, agg="sum")

Declaration decorators#

These public constructors are documented inline because their lowercase names collide with the corresponding catalog-object class filenames on case-insensitive filesystems.

marivo.semantic.entity(*, name, datasource, source, primary_key=None, versioning=None, domain=None, ai_context=None)[source]#

Declare an entity over a structured physical source.

Parameters:

name (str) – Entity name.
datasource (Ref[DatasourceKind]) – Datasource ref returned by ms.ref.datasource(...).
source (TableSourceIR | ParquetSourceIR | CsvSourceIR | JsonSourceIR) – Structured physical source, usually md.table(...), md.parquet(...), md.csv(...), or md.json(...).
primary_key (list[str] | None) – Optional list of column names forming the primary key.
domain (Ref[DomainKind] | None) – Override the active domain namespace with a Ref[domain] returned by ms.domain(...). Defaults to the file’s default domain.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.
versioning (SnapshotVersioningIR | ValidityVersioningIR | None)

Returns:

An Ref[entity] usable by @ms.dimension and @ms.metric.

Raises:

SemanticDecoratorError – datasource is not a datasource ref, name collides with another object, or source is not an entity source.

Return type:

Ref[EntityKind]

Example

>>> orders = ms.entity(
...     name="orders",
...     datasource=ms.ref.datasource("warehouse"),
...     source=md.table("orders", database="sales_mart"),
... )

marivo.semantic.dimension(*, name=None, entity, domain=None, ai_context=None)[source]#

Declare a categorical dimension whose body returns an ibis expression over its entity.

The decorated function takes the entity table and returns a single expression (single-return AST). Use this for both raw columns and derived expressions (e.g. table.region).

For quantitative measures, use @ms.measure(entity=..., additivity=...) instead.

Parameters:

name (str | None) – Dimension name. Defaults to the function name.
entity (Ref[EntityKind]) – Owning entity ref returned by ms.entity(...).
domain (Ref[DomainKind] | None) – Override the active domain namespace with a Ref[domain] returned by ms.domain(...). Defaults to the file’s default domain.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A decorator that returns a Ref[dimension].

Raises:

SemanticDecoratorError – entity is unknown, name collides, or the body violates the AST whitelist.

Return type:

Callable[[Callable[[…], Any]], Ref[DimensionKind]]

Example

>>> @ms.dimension(entity=orders)
... def region(orders_table):
...     return orders_table.region

marivo.semantic.measure(*, name=None, entity, additivity, unit=None, domain=None, ai_context=None)[source]#

Declare a row-level quantitative measure whose expression can be aggregated.

Measures represent quantitative facts (e.g. amount, quantity) that can be aggregated using ms.aggregate(). The decorated function takes the entity table and returns a single ibis expression.

Parameters:

name (str | None) – Measure name. Defaults to the function name.
entity (Ref[EntityKind]) – Owning entity ref returned by ms.entity(...).
additivity (Literal['additive', 'non_additive'] | ~marivo.semantic.ir.SemiAdditive) – Whether the measure is "additive", "non_additive", or ms.semi_additive(over=..., fold=...).
unit (str | None) – UCUM unit token (e.g. "USD", "CNY", "%").
domain (Ref[DomainKind] | None) – Override the active domain namespace with a Ref[domain] returned by ms.domain(...). Defaults to the file’s default domain.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A decorator that returns a Ref[measure].

Raises:

SemanticDecoratorError – entity is unknown, name collides, or the body violates the AST whitelist.

Return type:

Callable[[Callable[[…], Any]], Ref[MeasureKind]]

Example

>>> @ms.measure(entity=orders, additivity="additive", unit="USD")
... def amount(orders_table):
...     return orders_table.amount

marivo.semantic.metric(*, name=None, entities, additivity, root_entity=None, fanout_policy='block', unit=None, provenance=None, domain=None, ai_context=None)[source]#

Declare a metric from an ibis body. Declares additivity directly.

Parameters:

name (str | None) – Metric name. Defaults to the function name.
entities (list[Ref[EntityKind]]) – List of entity refs.
additivity (Literal['additive', 'non_additive'] | ~marivo.semantic.ir.SemiAdditive) – "additive", "non_additive", or ms.semi_additive(over, fold).
root_entity (Ref[EntityKind] | None) – Required when more than one entity is provided.
fanout_policy (Literal['block', 'aggregate_then_join']) – "block" (default) or "aggregate_then_join".
unit (str | None) – UCUM unit token.
provenance (SqlProvenance | None) – Optional SqlProvenance from ms.from_sql(sql=..., dialect=...).
domain (Ref[DomainKind] | None) – Override the active domain namespace.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A decorator that returns a Ref[metric].

Return type:

Callable[[Callable[[…], Any]], Ref[MetricKind]]

Example

>>> @ms.metric(entities=[orders], additivity="additive")
... def gmv(orders):
...     return (orders.price * orders.qty).sum()

marivo.semantic.event(*, name=None, identity, occurred_at, participants, domain=None, ai_context=None)[source]#

Declare immutable business occurrences over one existing Entity.

Parameters:

name (str | None) – Event name. Defaults to the decorated function name.
identity (tuple[Ref[DimensionKind], ...]) – Ordered non-empty occurrence identity Dimensions.
occurred_at (Ref[TimeDimensionKind]) – Business occurrence-time Dimension.
participants (tuple[Participant, ...]) – One or more participant role declarations.
domain (Ref[DomainKind] | None) – Optional explicit domain override.
ai_context (AiContextValue | None) – Business definition and authoring guidance.

Returns:

A decorator replacing the function with Ref[event].

Return type:

Callable[[Callable[[…], Any]], Ref[EventKind]]

Example

>>> @ms.event(
...     identity=(event_id,),
...     occurred_at=event_time,
...     participants=(ms.participant(name="order", cardinality="one"),),
... )
... def order_created(rows):
...     return ms.all_rows()

Constraints:: The function must return ms.all_rows() or one restricted boolean expression built from source Dimensions through ms.bind.

marivo.semantic.relationship(*, name, from_entity, to_entity, keys, domain=None, ai_context=None)[source]#

Declare a join relationship between two entities.

Top-level call (not a decorator). Used by the compiler to plan joins when a metric or dimension references dimensions across related entities.

Parameters:

name (str) – Required relationship name.
from_entity (Ref[EntityKind]) – Source entity ref.
to_entity (Ref[EntityKind]) – Target entity ref.
keys (list[JoinKey]) – List of ms.join_on(from_key, to_key) pairs.
domain (Ref[DomainKind] | None) – Override the active domain namespace with a Ref[domain] returned by ms.domain(...). Defaults to the file’s default domain.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A Ref[relationship].

Raises:

SemanticDecoratorError – name is missing, the entities are unknown, or keys is empty.

Return type:

Ref[RelationshipKind]

Example

>>> ms.relationship(
...     name="orders_to_customers",
...     from_entity=orders, to_entity=customers,
...     keys=[ms.join_on(customer_id, id)],
... )

marivo.semantic.time_dimension(*, name=None, entity, granularity, parse=None, is_default=False, domain=None, ai_context=None)[source]#

Declare a time-aware dimension that carries grain and parsing metadata.

Time dimensions are the only dimensions usable as window axes by session.observe. The body may return any ibis expression that represents the intended time axis. When parse is omitted, the parse variant is inferred from the column type at analysis time. Use ms.datetime(timezone=...) or ms.timestamp(timezone=...) for a native naive source axis so readiness can block an undeclared datasource-timezone fallback. Use ms.strptime(...) or ms.hour_prefix(...) for string/integer parsing.

Parameters:

name (str | None) – Dimension name. Defaults to the function name.
entity (Ref[EntityKind]) – Owning entity ref returned by ms.entity(...).
granularity (Literal['year', 'quarter', 'month', 'week', 'day', 'hour', 'minute', 'second']) – year | quarter | month | week | day | hour | minute | second — the finest grain at which queries are meaningful.
parse (DateParse | DatetimeParse | TimestampParse | StrptimeParse | HourPrefixParse | None) – Optional parse variant. Omit for native temporal columns (the parse is inferred at analysis time). Use ms.datetime(timezone=...), ms.timestamp(timezone=...), ms.strptime(format), or ms.hour_prefix(prefix) when explicit configuration is needed.
is_default (bool) – Mark this dimension as the default time axis when multiple time dimensions exist on the entity. At most one time dimension per entity may carry is_default=True. When observe() is called without time_dimension=, the default dimension is used automatically.
domain (Ref[DomainKind] | None) – Override the active domain namespace with a Ref[domain] returned by ms.domain(...). Defaults to the file’s default domain.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A decorator that returns a Ref[time_dimension].

Raises:

SemanticDecoratorError – entity is unknown, name collides, the body violates the AST whitelist, or the parse variant is incompatible with the declared granularity.

Return type:

Callable[[Callable[[…], Any]], Ref[TimeDimensionKind]]

Example

>>> @ms.time_dimension(entity=orders, granularity="day")
... def created_at(orders):
...     return orders.created_at

marivo.semantic.domain(*, name, owner, default=True, ai_context=None)[source]#

Declare a semantic domain namespace inside a project file.

A domain groups entities, dimensions, metrics, and relationships under a single qualified name (<domain>.<object>). Must be called at module top-level inside a models/semantic/<model>/*.py project file.

Parameters:

name (str) – Domain namespace, e.g. "sales".
owner (str) – Human owner accountable for this domain’s semantic correctness and quality.
default (bool) – If True, subsequent decorators in this file resolve to this domain when no explicit domain= kwarg is passed.
ai_context (AiContextValue | None) – Optional AiContextValue from ms.ai_context(...) with extra agent-facing hints.

Returns:

A Ref[domain] that can be passed as the domain= kwarg to other decorators to override the default domain context.

Raises:

OutsideLoaderContextError – Called outside a semantic loader pass.
SemanticDecoratorError – name collides with another domain in the project.

Return type:

Ref[DomainKind]

Example

>>> import marivo.semantic as ms
>>> sales = ms.domain(name="sales", owner="Mina Zhang", default=True)

Event helpers#

event is the only Event declaration entrypoint. Filtered Event bodies return a restricted boolean expression; unfiltered bodies explicitly return all_rows().

marivo.semantic.participant(*, name, path=None, cardinality)[source]#

Declare one named participant role inside @ms.event(...).

Parameters:

name (str) – Stable lowercase snake-case role name.
path (tuple[Ref[RelationshipKind], ...] | None) – Directed non-empty relationship path from the Event source. Omit when the source Entity itself plays this role.
cardinality (Literal['one', 'optional_one']) – "one" or "optional_one".

Returns:

Immutable participant authoring value.

Return type:

Participant

Example

>>> buyer = ms.participant(
...     name="buyer",
...     path=(event_to_buyer,),
...     cardinality="one",
... )

marivo.semantic.participant_role(*, event, name)[source]#

Create the typed handle for one named Event participant role.

Parameters:

event (Ref[EventKind]) – Exact Event ref returned by @ms.event(...).
name (str) – Declared participant role name.

Returns:

Immutable role handle resolved against the catalog by consumers.

Return type:

ParticipantRoleHandle

Example

>>> buyer = ms.participant_role(event=payment_succeeded, name="buyer")

marivo.semantic.all_rows()[source]#

Return the explicit unfiltered Event predicate.

This value is valid only as the complete return expression of an @ms.event(...) body.

Return type:: BooleanValue

Aggregation & measure helpers#

`aggregate`	Declare a tier-1 simple metric: an aggregation over a measure.
`count`	Declare a row-count metric for an entity.
`where`	Build an AND-joined filter for `ms.count` / `ms.aggregate`.
`linear`	Declare a derived linear metric (no body): sum of `add` minus `subtract`.
`ratio`	Declare a derived ratio metric (no body).
`weighted_mean`	Declare an exact tier-1 weighted mean over two row-level measures.
`semi_additive`	Declare a semi-additive nature: additive off the `over` time axis, folded by `fold`.
`snapshot`	Declare daily snapshot partition versioning for an entity.
`validity`	Declare SCD2 validity interval versioning for an entity.
`join_on`	Build one relationship key pair for `ms.relationship(keys=[...])`.
`cumulative`	Declare a cumulative metric over a tier-1 base metric.
`grain_to_date`	Select a grain-to-date cumulative anchor (MTD / QTD / YTD resets).
`trailing`	Select a fixed-size trailing cumulative anchor (rolling N).

Column helpers#

`dimension_column`	Declare a categorical dimension directly from one physical column.
`measure_column`	Declare a quantitative measure directly from one physical column.
`time_dimension_column`	Declare a time dimension directly from one physical column.
`period_calendar`	Declare one finite governed calendar over an exhaustive civil-date spine.
`period_correspondence`	Declare the baseline-key field for one named calendar correspondence.
`temporal_set`	Declare one finite governed set of named temporal occurrences.
`work_schedule`	Declare one finite governed daily final working-status schedule.
`calendar_grain`	Construct one semantic aggregation grain from a period-calendar level.

Time parsing#

`datetime`	Declare an already-temporal datetime column parse.
`timestamp`	Declare an already-temporal timestamp column parse.
`strptime`	Declare a string/integer strptime parse.
`hour_prefix`	Declare an hour-only partition parse using a day prefix column.

Provenance#

from_sql

Declare SQL parity provenance for a Python metric body.

Readiness & verification#

`richness`	Return a demand-ranked advisory richness report.
`parity_check`	Run parity check for a metric against its source SQL.

Refs, binding & loading#

ref is the immutable exact-kind factory namespace. Ref values themselves are immutable identities and are never callable; use bind to apply a field ref to a direct entity alias inside a decorated expression body.

marivo.semantic.ref#: Exact semantic-ref factories kept separate from immutable identities.

marivo.semantic.bind(field, entity_alias, /)[source]#

Apply a semantic field ref to an entity alias in an expression body.

Parameters#

field:: Exact dimension, time-dimension, or measure ref declared in the loaded semantic project.
entity_alias:: Direct entity parameter of the active decorated expression body.

Returns#

ibis.expr.types.Value: The referenced field expression evaluated on entity_alias.

Example#

>>> @ms.metric(entities=[orders], additivity="additive")
... def revenue(orders):
...     return ms.bind(amount, orders).sum()

Constraints#

Only valid inside a loaded semantic expression body. The field must belong to the bound entity and must be captured as a direct ms.bind argument.

Parameters:

field (Ref[DimensionKind | TimeDimensionKind | MeasureKind])
entity_alias (Table)

Return type:

Value

`Ref`	Sealed semantic identity created only by an exact kind factory.
`load`	Load a semantic project and return a browseable SemanticCatalog.

Focused help#

python -m marivo help only validates the active interpreter, package version, and environment fingerprint. Use the sole public coordinator, marivo.help("semantic.<target>"), for bounded constructor, catalog, and validation contracts rendered from the semantic registry. The ms namespace executes semantic operations and intentionally has no ms.help() alias.

A legal ms.where(...) declaration that cannot be compared with the resolved runtime dtype raises filter_value_runtime_incompatible before query submission. Its authored literal is preserved until the user or business owner confirms any required code/label mapping.

Details types#

`EntityDetails`	Details for an entity object.
`DimensionDetails`	Details for a categorical dimension object.
`MeasureDetails`	Details for a row-level quantitative measure object.
`MetricDetails`	Represent a PEP 604 union type
`RelationshipDetails`	Details for a relationship between entities.
`EventDetails`	Details for one executable Event definition.
`TimeDimensionDetails`	Details for a time dimension object.
`DomainDetails`	Details for a domain object.
`DatasourceDetails`	Details for a datasource object.
`DerivedMetricDetails`	Details for a derived (composed) metric.
`SimpleMetricDetails`	Details for a simple (entity-backed) metric.
`PeriodCalendarDetails`	Static source contract for one governed period calendar.
`CalendarLevelDetails`	Certification-derived facts for one owned period-calendar level.
`TemporalSetDetails`	Static source contract for one governed temporal set.
`WorkScheduleDetails`	Static source contract for one governed final daily work schedule.

Catalog & objects#

Typed collections resolve a local name, a full semantic path, or an exact same-kind Ref within the collection’s current scope. Scoped collections do not widen to out-of-scope objects. catalog.require(ref) remains the strict, global, ref-only lookup for configured, persisted, or logged identity.

catalog.verify(...), catalog.preview(...), catalog.preview_many(...), and catalog-leaf catalog.readiness(refs=[...]) accept either an exact entry owned by the current compiled catalog or its exact ref. Entries normalize immediately to refs; readiness results, preview evidence, persistence, and recovery remain ref-based.

`SemanticCatalog`	Read-only object graph over a loaded semantic project.
`CatalogCollection`	Read-only typed collection scoped by exact kind and optional owner.
`CatalogEntry`	One immutable browsable object in one compiled semantic catalog.
`SemanticKind`	Closed runtime kind registry for every semantic identity.
`PeriodCalendarEntry`	Loaded period-calendar declaration with direct semantic-grain lookup.
`CalendarPeriodPage`	Bounded snapshot-bound page of exact period scopes.
`TemporalSetEntry`	Loaded temporal-set declaration with exact occurrence navigation.
`TemporalOccurrencePage`	Bounded snapshot-bound page of exact occurrence scopes.
`WorkScheduleEntry`	Loaded work-schedule declaration with certified-status navigation.

Sources & provenance#

SqlProvenance

SQL parity provenance for a Python-authored metric body.

Readiness & assessment#

`ReadinessReport`
`ReadinessIssue`
`ReadinessInputSummary`
`RichnessReport`
`ParityResult`	Result of a single metric parity check.
`VerifyResult`
`PreviewBatchResult`	Successful bounded previews for an explicitly requested ref batch.

Keys & kinds#

JoinKey

One left/right relationship key pair.

AI context#

`ai_context`	Construct a validated AiContext for semantic objects.
`AiContextValue`	Validated AI-facing context for semantic and datasource objects.

Submodules#

`marivo.semantic.errors`	Typed semantic errors and warnings raised across the semantic layer.
`marivo.semantic.typing`	Shared type aliases for the semantic surface.