dbt¶

context ¶

Types and DbtContext for working with a dbt project's models, sources, and schema.

Relation `dataclass` ¶

Relation(
    database: str, schema: str, identifier: str, quoted: str
)

A warehouse relation: its database/schema/identifier parts and dbt's quoted name.

Column `dataclass` ¶

Column(
    name: str, type: str | None, description: str | None
)

A table column: its name, resolved SQL type (when known), and description (when documented).

TableSchema `dataclass` ¶

TableSchema(
    name: str,
    relation: Relation,
    columns: tuple[Column, ...],
    description: str | None,
)

A queryable table — a dbt model or source — as name, relation, columns, and description.

ModelRef `dataclass` ¶

ModelRef(
    name: str,
    unique_id: str,
    relation: Relation,
    compiled_sql: str | None,
    description: str | None,
    columns: tuple[Column, ...],
)

A dbt model: its name, unique id, target relation, compiled SQL, columns, and description.

SourceRef `dataclass` ¶

SourceRef(
    name: str,
    source_name: str,
    relation: Relation,
    description: str | None,
    columns: tuple[Column, ...],
)

A dbt source table: its table name, source collection, relation, columns, and description.

DbtTest `dataclass` ¶

DbtTest(name: str, model: str, column: str | None)

A dbt data test: its type, the model it guards, and the column it targets (if any).

Entity `dataclass` ¶

Entity(name: str, type: str, expr: str | None)

A semantic model's join key: the column expression that links semantic models together.

Dimension `dataclass` ¶

Dimension(
    name: str,
    type: str,
    expr: str | None,
    granularity: str | None,
    description: str | None,
)

A semantic model's dimension: a categorical or time attribute queries can group by.

Measure `dataclass` ¶

Measure(
    name: str,
    agg: str,
    expr: str | None,
    description: str | None,
)

A semantic model's measure: a column aggregation that metrics are built from.

SemanticModel `dataclass` ¶

SemanticModel(
    name: str,
    description: str | None,
    relation: Relation,
    entities: tuple[Entity, ...],
    dimensions: tuple[Dimension, ...],
    measures: tuple[Measure, ...],
)

A dbt semantic model: the relation it sits on and its entities, dimensions, and measures.

Metric `dataclass` ¶

Metric(
    name: str,
    type: str,
    label: str | None,
    description: str | None,
)

A dbt metric exposed by the semantic layer.

SemanticLayerContext `dataclass` ¶

SemanticLayerContext(
    metrics: tuple[Metric, ...],
    semantic_models: tuple[SemanticModel, ...],
)

A project's metrics and semantic models as prompt context for an SL-query solver.

as_text ¶

as_text() -> str

Render the metrics and each semantic model's entities, dimensions, and measures.

Sections with no members are omitted; an empty layer renders as the empty string.

Returns:

Type	Description
`str`	The rendered semantic-layer context block.

SchemaContext `dataclass` ¶

SchemaContext(tables: tuple[TableSchema, ...])

A selection of tables rendered as schema context for a text-to-SQL prompt.

as_text ¶

as_text() -> str

Render the tables as CREATE TABLE statements for prompt injection.

Each table renders its description as a leading comment (when documented), its quoted relation name, and one line per column (name type, with the column description as a trailing comment when documented). Tables are separated by a blank line.

Returns:

Type	Description
`str`	The rendered schema text, or the empty string when there are no tables.

DbtContext ¶

DbtContext(
    *,
    models: Iterable[ModelRef],
    sources: Iterable[SourceRef],
    tests: Iterable[DbtTest],
    schema_version: str,
    semantic_models: Iterable[SemanticModel] = (),
    metrics: Iterable[Metric] = (),
)

A dbt project's models, sources, and schema, normalised from its target/ artifacts.

Build one with from_target_dir. Models are addressable by short name or unique id; column types come from catalog.json (the resolved warehouse types) when present, falling back to the manifest's declared types otherwise.

Build a context from pre-built models, sources, tests, and semantic-layer parts.

Parameters:

Name	Type	Description	Default
`models`	`Iterable[ModelRef]`	The project's models.	required
`sources`	`Iterable[SourceRef]`	The project's source tables.	required
`tests`	`Iterable[DbtTest]`	The project's data tests.	required
`schema_version`	`str`	The manifest schema version the parts were read from.	required
`semantic_models`	`Iterable[SemanticModel]`	The project's semantic models.	`()`
`metrics`	`Iterable[Metric]`	The project's metrics.	`()`

from_target_dir `classmethod` ¶

from_target_dir(path: str | Path) -> DbtContext | DbtError

Build a context from a dbt target/ directory.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to a dbt `target/` directory holding `manifest.json` (and optionally `catalog.json` and `semantic_manifest.json`).	required

Returns:

Type	Description
`DbtContext \| DbtError`	A `DbtContext` on success, or a `DbtError` if the artifacts are missing, malformed,
`DbtContext \| DbtError`	or an unsupported schema version.

model ¶

model(name_or_uid: str) -> ModelRef | None

Return the model addressed by short name or unique id, or None if there is none.

Parameters:

Name	Type	Description	Default
`name_or_uid`	`str`	A model's short name (e.g. `customers`) or unique id (e.g. `model.my_project.customers`).	required

Returns:

Type	Description
`ModelRef \| None`	The matching `ModelRef`, or `None`.

compiled_sql ¶

compiled_sql(name_or_uid: str) -> str | None

Return a model's compiled SQL, or None if the model or its compiled SQL is absent.

Parameters:

Name	Type	Description	Default
`name_or_uid`	`str`	A model's short name or unique id.	required

Returns:

Type	Description
`str \| None`	The model's `compiled_code`, or `None`.

relation ¶

relation(name_or_uid: str) -> Relation | None

Return a model's target relation, or None if there is no such model.

Parameters:

Name	Type	Description	Default
`name_or_uid`	`str`	A model's short name or unique id.	required

Returns:

Type	Description
`Relation \| None`	The model's `Relation`, or `None`.

tables ¶

tables() -> list[TableSchema]

Return every queryable table — sources then models — as table schemas.

Returns:

Type	Description
`list[TableSchema]`	The source tables followed by the model tables.

models ¶

models() -> list[ModelRef]

Return the project's models.

Returns:

Type	Description
`list[ModelRef]`	The models, in manifest order.

tests ¶

tests() -> list[DbtTest]

Return the project's data tests attached to models.

Returns:

Type	Description
`list[DbtTest]`	The data tests, in manifest order.

sources ¶

sources() -> list[SourceRef]

Return the project's source tables.

Returns:

Type	Description
`list[SourceRef]`	The source tables, in manifest order.

schema_version ¶

schema_version() -> str

Return the manifest schema version the project was read from.

Returns:

Type	Description
`str`	The schema version token (e.g. `v12`).

semantic_models ¶

semantic_models() -> list[SemanticModel]

Return the project's semantic models.

Returns:

Type	Description
`list[SemanticModel]`	The semantic models, in semantic-manifest order (empty when the project has no
`list[SemanticModel]`	semantic layer).

metrics ¶

metrics() -> list[Metric]

Return the project's metrics.

Returns:

Type	Description
`list[Metric]`	The metrics, in semantic-manifest order (empty when the project has no semantic layer).

dimensions ¶

dimensions() -> list[Dimension]

Return the semantic layer's group-by dimensions, deduplicated by name.

Returns:

Type	Description
`list[Dimension]`	The dimensions across all semantic models, first occurrence kept, in order.

sl_context ¶

sl_context() -> SemanticLayerContext

Build a SemanticLayerContext from the project's metrics and semantic models.

Returns:

Type	Description
`SemanticLayerContext`	A `SemanticLayerContext` over the project's metrics and semantic models.

schema_context ¶

schema_context(
    *,
    include_sources: bool = True,
    include_models: bool = True,
    select: Iterable[str] | None = None,
) -> SchemaContext

Build schema context for a text-to-SQL prompt from the project's tables.

Parameters:

Name	Type	Description	Default
`include_sources`	`bool`	Include the project's source tables.	`True`
`include_models`	`bool`	Include the project's models.	`True`
`select`	`Iterable[str] \| None`	If given, keep only tables whose name is in this collection.	`None`

Returns:

Type	Description
`SchemaContext`	A `SchemaContext` over the selected tables.

loader ¶

Build EvalCases (and Semantic Layer MetricCases) from a dbt project.

load_dbt ¶

load_dbt(
    target_dir: str | Path,
    *,
    platform: PlatformRef,
    cases: str | Path | None = None,
    mode: Mode = "authored",
) -> list[EvalCase] | DbtError

Build SQL eval cases from a built dbt project's artifacts.

The schema context for each case is the project's tables (sources and models) rendered as CREATE TABLE statements into metadata["schema_ddl"], ready for a schema-aware solver.

In authored mode, cases is a YAML/JSON file of {question, gold_sql, select?, id?} entries; select scopes the schema context to named tables. In model mode, each documented, compiled model becomes a case whose question is the model's description and whose gold query is the model's compiled SQL. In tests mode, each documented model with not_null or unique tests becomes a case whose expected outcome is an ExpectationSuite built from those tests. For Semantic Layer cases, use load_dbt_metrics.

Parameters:

Name	Type	Description	Default
`target_dir`	`str \| Path`	A dbt `target/` directory holding `manifest.json` (and optionally `catalog.json`).	required
`platform`	`PlatformRef`	The warehouse the project is built in; every case runs against it.	required
`cases`	`str \| Path \| None`	Path to the cases file (required for `authored`; ignored for `model` and `tests`).	`None`
`mode`	`Mode`	`authored` to read `cases`, `model` to derive cases from documented models, or `tests` to build expectation suites from documented models' data tests.	`'authored'`

Returns:

Type	Description
`list[EvalCase] \| DbtError`	The eval cases, or a `DbtError` if the artifacts, cases, or mode inputs cannot be read.

load_dbt_metrics ¶

load_dbt_metrics(
    target_dir: str | Path,
    *,
    platform: PlatformRef,
    cases: str | Path,
    profiles_dir: str | Path | None = None,
) -> list[MetricCase] | DbtError

Build Semantic Layer MetricCases from a metric cases file.

Each entry in cases is a {question, metrics, group_by?, where?, order_by?, limit?, id?} mapping that becomes a case whose gold answer is the described MetricQuery. The project's semantic layer is rendered into each case's sl_context for a solver's prompt.

Parameters:

Name	Type	Description	Default
`target_dir`	`str \| Path`	A dbt `target/` directory holding `manifest.json` and `semantic_manifest.json`.	required
`platform`	`PlatformRef`	The warehouse the project is built in; every case runs against it.	required
`cases`	`str \| Path`	Path to the metric cases file.	required
`profiles_dir`	`str \| Path \| None`	Where `mf` looks for `profiles.yml` when running queries; defaults to the project directory.	`None`

Returns:

Type	Description
`list[MetricCase] \| DbtError`	The metric cases, or a `DbtError` if the artifacts or cases cannot be read.

profile ¶

Resolve a dbt profile target to an evaldata PlatformRef.

platform_from_profile ¶

platform_from_profile(
    project_dir: str | Path,
    *,
    profiles_dir: str | Path | None = None,
    target: str | None = None,
) -> PlatformRef | DbtError

Resolve a dbt project's profile target to a PlatformRef.

Reads the project's dbt_project.yml for its profile, then the matching entry in profiles.yml (in profiles_dir, defaulting to project_dir), and maps the selected output's warehouse type to an evaldata platform. Supports the duckdb and postgres adapters; a duckdb path is resolved relative to project_dir. The Postgres conninfo carries host/port/dbname/user; the password is left to libpq (PGPASSWORD, .pgpass).

Parameters:

Name	Type	Description	Default
`project_dir`	`str \| Path`	The dbt project directory (holding `dbt_project.yml`).	required
`profiles_dir`	`str \| Path \| None`	Directory holding `profiles.yml`; defaults to `project_dir`.	`None`
`target`	`str \| None`	The profile target (output) name; defaults to the profile's `target`.	`None`

Returns:

Type	Description
`PlatformRef \| DbtError`	A `PlatformRef` for the selected target, or a `DbtError` if the project or profile
`PlatformRef \| DbtError`	cannot be resolved (`profile_not_found`) or the warehouse type is unsupported
`PlatformRef \| DbtError`	(`unsupported_adapter`).

errors ¶

Failure types for dbt artifact loading.

DbtError ¶

Bases: Error

A failure from a dbt operation — artifact loading, profile resolution, or metric query resolution.

Semantic Layer¶

semantic_layer ¶

The dbt Semantic Layer evaluation vertical: query, case, output, and pluggable contracts.

MetricQuery ¶

Bases: BaseModel

A dbt Semantic Layer query: the metrics to compute and how to slice, filter, and limit them.

group_by holds MetricFlow group-by items (a dimension, an entity, or a time dimension with a grain, e.g. metric_time__month or customer__country). where holds MetricFlow filter expressions (e.g. {{ Dimension('order_id__is_food_order') }} = true). order_by holds group-by or metric names, each optionally prefixed with - for descending.

MetricCase ¶

Bases: BaseModel

One Semantic Layer evaluation case: a question, a gold metric query, and its resolution context.

MetricSolverOutput ¶

Bases: BaseModel

A Semantic Layer solver's output: either a candidate query or an error (exactly one set).

MetricSolver ¶

Bases: Protocol

Produces a MetricSolverOutput for a MetricCase.

solve ¶

solve(case: MetricCase) -> MetricSolverOutput

Produce a candidate metric query for case.

MetricScorer ¶

Bases: Protocol

Scores a candidate metric query against a case's gold query.

score ¶

score(case: MetricCase, query: MetricQuery) -> ScoreResult

Decide pass/fail with diagnostics for case given the candidate query.

metric_layer_solver ¶

MetricLayerSolver: an LLM MetricSolver that answers a question with a dbt Semantic Layer query.

MetricLayerSolver ¶

MetricLayerSolver(
    model: str | Llm,
    prompt_template: str = SL_PROMPT_TEMPLATE,
    timeout: float | None = None,
    temperature: float | None = None,
)

Single-prompt LLM MetricSolver: question -> a MetricQuery via structured output.

Configure the solver.

Parameters:

Name	Type	Description	Default
`model`	`str \| Llm`	A litellm model identifier (e.g. `"openai/gpt-4o-mini"`), or an `Llm` to use directly. `timeout` and `temperature` apply only to the model-string path.	required
`prompt_template`	`str`	A `str.format_map` template with `{semantic_layer}` and `{input}` fields; `{semantic_layer}` is filled from `case.sl_context`.	`SL_PROMPT_TEMPLATE`
`timeout`	`float \| None`	Per-request timeout in seconds.	`None`
`temperature`	`float \| None`	Sampling temperature; `None` leaves the provider default. Use `0` for deterministic output.	`None`

solve ¶

solve(case: MetricCase) -> MetricSolverOutput

Produce a metric query for case.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case to solve.	required

Returns:

Type	Description
`MetricSolverOutput`	A `MetricSolverOutput` with the metric query and telemetry on success, or a typed
`MetricSolverOutput`	`SolverError` on an expected provider failure.

metric_spec_equivalence ¶

MetricSpecEquivalence: confirm two metric queries match by resolving both through MetricFlow.

MetricSpecEquivalence ¶

Compares two metric queries by the forms MetricFlow resolves them to.

Equal forms pass (proven). A candidate MetricFlow rejects fails (proven). Everything else — unequal forms, an invalid gold, or the toolchain being unavailable — is inconclusive.

score ¶

score(case: MetricCase, query: MetricQuery) -> ScoreResult

Resolve the candidate and gold queries and confirm equivalence when they match.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case, supplying the gold query and the target directory.	required
`query`	`MetricQuery`	The candidate metric query.	required

Returns:

Type	Description
`ScoreResult`	A proven pass when the queries resolve to the same form, a proven fail when the
`ScoreResult`	candidate does not resolve against the manifest, else an inconclusive result.

metric_result_equivalence ¶

MetricResultEquivalence: decide equivalence by running both metric queries and diffing rows.

MetricResultEquivalence ¶

MetricResultEquivalence(
    *,
    on_error: Literal[
        "inconclusive", "fail"
    ] = "inconclusive",
)

Decides equivalence by running both metric queries and comparing their result rows.

Rows are compared as an order-insensitive multiset. Columns are aligned by value, so the same answer under a different metric or dimension label still matches, and numeric cells match within a small tolerance. A candidate that groups by extra columns still matches when they are redundant (dropping them keeps every row distinct). A failed model-query run is inconclusive by default, or incorrect when on_error="fail"; a failed gold-query run is always inconclusive.

Configure how a failed model-query run is scored.

Parameters:

Name	Type	Description	Default
`on_error`	`Literal['inconclusive', 'fail']`	`"inconclusive"` (default) to score a failed model query as inconclusive, or `"fail"` to score it as incorrect.	`'inconclusive'`

score ¶

score(case: MetricCase, query: MetricQuery) -> ScoreResult

Run both queries and decide equivalence from their result rows.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case, supplying the gold query and the target directory.	required
`query`	`MetricQuery`	The candidate metric query.	required

Returns:

Type	Description
`ScoreResult`	An observed `ScoreResult` when both queries run; inconclusive when a query fails, or
`ScoreResult`	failing for the model query when `on_error="fail"`.

metric_layer_judge ¶

MetricLayerJudge: an LLM-as-judge MetricScorer grading two metric queries for equivalence.

MetricLayerJudge ¶

MetricLayerJudge(
    model: str | Llm,
    *,
    criteria: str = SL_JUDGE_CRITERIA,
    threshold: float = 0.5,
    temperature: float | None = 0.0,
    timeout: float | None = None,
)

LLM-as-judge MetricScorer: a grader model scores the candidate query against the gold query.

The grader's 0-1 score is compared to a threshold for the pass/fail verdict; the score and rationale are recorded. A provider failure or a malformed reply yields an inconclusive result.

Configure the judge.

Parameters:

Name	Type	Description	Default
`model`	`str \| Llm`	A litellm grader-model identifier (separate from any solver model), or an `Llm` to use directly. `temperature` and `timeout` apply only to the model-string path.	required
`criteria`	`str`	The natural-language standard the grader scores the queries against.	`SL_JUDGE_CRITERIA`
`threshold`	`float`	The minimum score (inclusive) for a passing verdict.	`0.5`
`temperature`	`float \| None`	Sampling temperature; defaults to `0.0` for deterministic grading.	`0.0`
`timeout`	`float \| None`	Per-request timeout in seconds.	`None`

score ¶

score(case: MetricCase, query: MetricQuery) -> ScoreResult

Grade the candidate query against the gold query and return a graded ScoreResult.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case, supplying the question and the gold query.	required
`query`	`MetricQuery`	The candidate metric query.	required

Returns:

Type	Description
`ScoreResult`	A `ScoreResult` whose verdict is pass or fail with the graded score and rationale, or
`ScoreResult`	inconclusive when the grader call fails.

combinators ¶

MetricFirstDecisive: run member MetricScorers in order, stopping at the first decisive result.

MetricFirstDecisive ¶

MetricFirstDecisive(scorers: Sequence[MetricScorer])

Runs member scorers in order; the first that decides wins, else the last result stands.

Members run while each is inconclusive; the first decisive verdict (pass or fail) is returned immediately, so a later member cannot override an earlier decision. If every member is inconclusive, the last member's result is returned.

Bind the combinator to an ordered list of member scorers.

Parameters:

Name	Type	Description	Default
`scorers`	`Sequence[MetricScorer]`	The member scorers, in priority order.	required

Raises:

Type	Description
`ValueError`	If `scorers` is empty.

score ¶

score(case: MetricCase, query: MetricQuery) -> ScoreResult

Run members in order, returning the first decisive result, else the last.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case, forwarded to each member.	required
`query`	`MetricQuery`	The candidate metric query, forwarded to each member.	required

Returns:

Type	Description
`ScoreResult`	The first decisive member's `ScoreResult` (verdict `pass` or `fail`), or the last
`ScoreResult`	member's result when every member is `inconclusive`, with the `"first_decisive"` trail
`ScoreResult`	merged into its metadata.

presets ¶

Preset Semantic Layer scorers: the ready-made metric_layer_equivalence cascade.

metric_layer_equivalence ¶

metric_layer_equivalence(
    model: str | Llm, *, temperature: float | None = 0.0
) -> MetricFirstDecisive

Return a cost-ordered MetricFirstDecisive cascade: spec-compare → run-compare → LLM judge.

Parameters:

Name	Type	Description	Default
`model`	`str \| Llm`	A litellm grader-model identifier, or an `Llm` to use directly, for the judge tier.	required
`temperature`	`float \| None`	Sampling temperature for the judge; some reasoning models accept only `1.0`.	`0.0`

Returns:

Type	Description
`MetricFirstDecisive`	A `MetricFirstDecisive` over `MetricSpecEquivalence`, `MetricResultEquivalence`, and
`MetricFirstDecisive`	`MetricLayerJudge(model)`.

strict_metric_equivalence ¶

strict_metric_equivalence() -> MetricFirstDecisive

Return a strict spec -> run cascade with no judge, scoring a failed run as incorrect.

A candidate passes only when its resolved form or its result rows match the gold; a query that fails to run is scored as incorrect.

Returns:

Type	Description
`MetricFirstDecisive`	A `MetricFirstDecisive` over `MetricSpecEquivalence` and `MetricResultEquivalence`.

eval ¶

Run Semantic Layer cases through a solver and scorers: per-case, pytest, and batch runners.

evaluate_metric_case ¶

evaluate_metric_case(
    case: MetricCase,
    solver: MetricSolver,
    *,
    scorers: Sequence[MetricScorer],
) -> CaseReport

Run case through solver and scorers, returning its outcome.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case to run.	required
`solver`	`MetricSolver`	The solver that produces a metric query for the case.	required
`scorers`	`Sequence[MetricScorer]`	Scorers applied to the candidate query; all must pass for the case to pass.	required

Returns:

Type	Description
`CaseReport`	A `CaseReport` with per-scorer results, or a solver error when the solver failed.

Raises:

Type	Description
`AssertionError`	If the solver returns neither a query nor an error (unreachable).

assert_metric_eval ¶

assert_metric_eval(
    case: MetricCase,
    solver: MetricSolver,
    *,
    scorers: Sequence[MetricScorer],
) -> None

Run case through solver and scorers; record the outcome and raise on any failure.

Parameters:

Name	Type	Description	Default
`case`	`MetricCase`	The eval case to run.	required
`solver`	`MetricSolver`	The solver that produces a metric query for the case.	required
`scorers`	`Sequence[MetricScorer]`	Scorers applied to the candidate query; all must pass.	required

Raises:

Type	Description
`AssertionError`	If the solver failed or any scorer did not pass.

run_metric_benchmark ¶

run_metric_benchmark(
    cases: Iterable[MetricCase],
    solver: MetricSolver,
    *,
    scorers: Sequence[MetricScorer],
    limit: int | None = None,
) -> BenchmarkSummary

Run cases through solver and scorers and return aggregate accuracy.

Parameters:

Name	Type	Description	Default
`cases`	`Iterable[MetricCase]`	The eval cases to run, in order.	required
`solver`	`MetricSolver`	The solver under test.	required
`scorers`	`Sequence[MetricScorer]`	Scorers applied to each case; all must pass for the case to count as passed.	required
`limit`	`int \| None`	Run at most this many cases, or `None` for all of them.	`None`

Returns:

Type	Description
`BenchmarkSummary`	A `BenchmarkSummary` with the total, the passed count, the accuracy
`BenchmarkSummary`	(`passed / total`, or `0.0` when no cases ran), and every case report.

metricflow ¶

canonicalize and run: resolve and execute a MetricQuery through MetricFlow.

Requires the optional dbt-metricflow toolchain (dbt-sl extra).

CanonicalMetricQuery `dataclass` ¶

CanonicalMetricQuery(
    metrics: frozenset[str],
    group_by: frozenset[SpecKey],
    order_by: tuple[tuple[SpecKey, bool], ...],
    limit: int | None,
    where: frozenset[str],
)

A metric query resolved through MetricFlow: two queries with equal values are the same query.

canonicalize ¶

canonicalize(
    query: MetricQuery, target_dir: str | Path
) -> CanonicalMetricQuery | DbtError

Resolve query against the project's semantic manifest into a comparable form.

MetricFlow resolves default time grains and entity-linked paths, so semantically equal queries produce equal CanonicalMetricQuery values.

Parameters:

Name	Type	Description	Default
`query`	`MetricQuery`	The metric query to resolve.	required
`target_dir`	`str \| Path`	A dbt `target/` directory holding `semantic_manifest.json`.	required

Returns:

Type	Description
`CanonicalMetricQuery \| DbtError`	A `CanonicalMetricQuery`, or a `DbtError` if MetricFlow is not installed
`CanonicalMetricQuery \| DbtError`	(`metricflow_unavailable`), the manifest is missing (`target_not_found`), or the query
`CanonicalMetricQuery \| DbtError`	does not resolve (`metric_query_invalid`).

group_by_items_by_metric ¶

group_by_items_by_metric(
    target_dir: str | Path, metric_names: list[str]
) -> dict[str, list[str]] | DbtError

List the queryable group-by names for each metric, in MetricFlow's entity__dimension grammar.

Each metric maps to the exact dimension names a query may group by, so a solver's prompt can offer them verbatim rather than leave the model to guess the entity path.

Parameters:

Name	Type	Description	Default
`target_dir`	`str \| Path`	A dbt `target/` directory holding `semantic_manifest.json`.	required
`metric_names`	`list[str]`	The metrics to enumerate group-by items for.	required

Returns:

Type	Description
`dict[str, list[str]] \| DbtError`	A mapping of metric name to its sorted group-by names, or a `DbtError` if MetricFlow is not
`dict[str, list[str]] \| DbtError`	installed (`metricflow_unavailable`), the manifest is missing (`target_not_found`), or a
`dict[str, list[str]] \| DbtError`	metric does not resolve (`metric_query_invalid`).

run ¶

run(
    query: MetricQuery,
    target_dir: str | Path,
    *,
    profiles_dir: str | Path | None = None,
) -> list[dict[str, str]] | DbtError

Execute query with the mf CLI against the project whose target/ is target_dir.

Parameters:

Name	Type	Description	Default
`query`	`MetricQuery`	The metric query to run.	required
`target_dir`	`str \| Path`	A dbt `target/` directory; its parent is the project root `mf` runs in.	required
`profiles_dir`	`str \| Path \| None`	Where `mf` looks for `profiles.yml`; defaults to the project root.	`None`

Returns:

Type	Description
`list[dict[str, str]] \| DbtError`	The result rows (column-to-value maps from the CSV export), or a `DbtError` if `mf`
`list[dict[str, str]] \| DbtError`	is not on PATH (`metricflow_unavailable`) or the query fails (`metric_query_invalid`).

dbt¶

context ¶

Relation dataclass ¶

Column dataclass ¶

TableSchema dataclass ¶

ModelRef dataclass ¶

SourceRef dataclass ¶

DbtTest dataclass ¶

Entity dataclass ¶

Dimension dataclass ¶

Measure dataclass ¶

SemanticModel dataclass ¶

Metric dataclass ¶

SemanticLayerContext dataclass ¶

as_text ¶

SchemaContext dataclass ¶

as_text ¶

DbtContext ¶

from_target_dir classmethod ¶

model ¶

compiled_sql ¶

relation ¶

tables ¶

models ¶

tests ¶

sources ¶

schema_version ¶

semantic_models ¶

metrics ¶

dimensions ¶

sl_context ¶

schema_context ¶

loader ¶

load_dbt ¶

load_dbt_metrics ¶

profile ¶

platform_from_profile ¶

errors ¶

DbtError ¶

Semantic Layer¶

semantic_layer ¶

MetricQuery ¶

MetricCase ¶

MetricSolverOutput ¶

MetricSolver ¶

solve ¶

MetricScorer ¶

score ¶

metric_layer_solver ¶

MetricLayerSolver ¶

solve ¶

metric_spec_equivalence ¶

MetricSpecEquivalence ¶

score ¶

metric_result_equivalence ¶

MetricResultEquivalence ¶

score ¶

metric_layer_judge ¶

MetricLayerJudge ¶

score ¶

combinators ¶

MetricFirstDecisive ¶

score ¶

presets ¶

metric_layer_equivalence ¶

strict_metric_equivalence ¶

eval ¶

evaluate_metric_case ¶

assert_metric_eval ¶

run_metric_benchmark ¶

metricflow ¶

CanonicalMetricQuery dataclass ¶

canonicalize ¶

group_by_items_by_metric ¶

run ¶

Relation `dataclass` ¶

Column `dataclass` ¶

TableSchema `dataclass` ¶

ModelRef `dataclass` ¶

SourceRef `dataclass` ¶

DbtTest `dataclass` ¶

Entity `dataclass` ¶

Dimension `dataclass` ¶

Measure `dataclass` ¶

SemanticModel `dataclass` ¶

Metric `dataclass` ¶

SemanticLayerContext `dataclass` ¶

SchemaContext `dataclass` ¶

from_target_dir `classmethod` ¶

CanonicalMetricQuery `dataclass` ¶