dbt-semantic-interfaces

0.10.5 verified Tue May 12 auth: no python install: stale

dbt-semantic-interfaces is a Python library that centralizes the shared semantic layer definitions used by dbt-core and MetricFlow. Its primary purpose is to maintain consistency and reduce code duplication across these projects by providing common semantic classes, default validation, and tests. The current version is 0.10.5, with frequent updates indicated by its release history and ongoing development.

pip install dbt-semantic-interfaces

Common errors

error ImportError: cannot import name 'FilterCallParameterSets' from 'dbt_semantic_interfaces.call_parameter_sets' ↓

cause This error typically occurs when there's a version mismatch between `dbt-core` and `dbt-semantic-interfaces`, or a breaking change in `dbt-semantic-interfaces` where the `FilterCallParameterSets` class was renamed or moved.

fix

Upgrade both dbt-core and dbt-semantic-interfaces to compatible versions, or check the dbt-semantic-interfaces changelog for the correct import path if the class was refactored. Often, a pip install --upgrade dbt-core dbt-semantic-interfaces can resolve it.

error Additional properties are not allowed ('metric-paths', 'semantic-model-paths' were unexpected) ↓

cause This validation error indicates that you are using deprecated or invalid keys in your `dbt_project.yml` or semantic layer YAML configuration files. The schema for defining semantic models and metrics has evolved.

fix

Remove the metric-paths and semantic-model-paths keys from your YAML configurations. MetricFlow expects semantic layer definitions to be co-located or discovered differently, often under a semantic_models and metrics folder structure, and these specific keys are no longer valid.

error Metric cannot reference a measure defined in the same semantic model (metric references non-existent measure) ↓

cause This error occurs when a metric is defined and attempts to reference a measure that either doesn't exist, is misspelled, or is not correctly defined within the same semantic model or a reachable semantic model according to the dbt Semantic Layer's rules.

fix

Review your semantic model and metric definitions in your YAML files. Ensure that the measure referenced by the metric is correctly named, exists within the measures block of its respective semantic_model, and follows the correct scoping rules for the dbt Semantic Layer.

error ModuleNotFoundError: No module named 'dbt.adapters.factory' ↓

cause This common `ModuleNotFoundError` arises from an incompatibility or an incomplete installation of `dbt-core` and its adapter plugins (e.g., `dbt-bigquery`, `dbt-postgres`). It indicates that `dbt-core` cannot find the necessary adapter components.

fix

Perform a forced reinstallation of dbt-adapters and your specific dbt adapter (e.g., dbt-bigquery) alongside dbt-core. For example: pip install --force-reinstall dbt-core dbt-adapters dbt-<your_adapter>. Ensure your Python environment and dbt versions are compatible.

Warnings

breaking Upgrades to dbt-semantic-interfaces versions 0.8.x and 0.10.x have introduced breaking changes, particularly affecting adapter plugins and metadata interfaces within dbt-core and MetricFlow. Users integrating this library directly or maintaining custom adapters should review release notes carefully. ↓

fix Consult the dbt-semantic-interfaces GitHub repository and dbt Developer Hub for specific migration guides and updated interfaces when upgrading from older versions. Pinning versions is recommended during active development.

gotcha dbt-semantic-interfaces provides the *definitions* for the dbt Semantic Layer. While `dbt-core` users can define metrics in their projects using these definitions, full features like dynamic querying via APIs or integrations often require a dbt Cloud plan. ↓

fix Understand the distinction between using `dbt-semantic-interfaces` for defining semantic models and the dbt Cloud platform's capabilities for querying and integrating with the Semantic Layer. For full API and integration access, a dbt Cloud plan is typically required.

breaking The semantic definitions were originally integrated directly within `dbt-core` or `MetricFlow`. The introduction of `dbt-semantic-interfaces` as a separate, shared library means that older codebases might look for semantic objects in incorrect locations, leading to import errors or unexpected behavior. ↓

fix Update import paths and code references to point to the `dbt_semantic_interfaces` package for all semantic object definitions. Ensure `dbt-core` and `MetricFlow` versions are compatible with the `dbt-semantic-interfaces` version being used.

gotcha When using dbt Mesh with the Semantic Layer, cross-project references for semantic models are currently only supported in the *legacy* YAML specification (where semantic models are top-level resources). In the *latest* YAML specification, where semantic models are defined within model YAML files, cross-project references are not yet supported. ↓

fix For cross-project references in dbt Mesh with the Semantic Layer, continue to use the legacy YAML specification for defining semantic models as top-level resources. If using the latest YAML spec, avoid cross-project semantic model references until support is added.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 38.7M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 5.6s - 39M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 42.8M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 4.8s - 43M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 34.2M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 3.9s - 34M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 33.9M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 4.1s - 34M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 38.1M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 6.3s - 38M

3.9 slim (glibc) - - - -

Imports

SemanticModel

from dbt_semantic_interfaces.models.semantic_model import SemanticModel

Metric

from dbt_semantic_interfaces.models.metric import Metric

Quickstart last tested: 2026-04-24

This quickstart demonstrates how to programmatically define a basic `SemanticModel` object using the Pydantic models provided by `dbt-semantic-interfaces`. This showcases the library's core function of providing standardized definitions for semantic layer components, which are then typically used by dbt-core and MetricFlow for validation and processing. Note that in a full dbt project, semantic models are usually defined in YAML files and not directly instantiated in Python by end-users. This example is for understanding the library's internal structure.

from dbt_semantic_interfaces.models.semantic_model import SemanticModel
from dbt_semantic_interfaces.models.entities import PydanticEntity
from dbt_semantic_interfaces.models.measures import PydanticMeasure
from dbt_semantic_interfaces.type_enums import EntityType, TimeGranularity

# A minimal example of defining a semantic model programmatically
my_entity = PydanticEntity(
    name='customer_id',
    type=EntityType.PRIMARY,
    expr='id'
)

my_measure = PydanticMeasure(
    name='total_orders',
    agg='count',
    expr='order_id'
)

my_semantic_model = SemanticModel(
    name='customers_semantic_model',
    description='A semantic model for customer data.',
    node_relation=None, # This would typically link to a dbt model, omitted for brevity
    entities=[my_entity],
    measures=[my_measure],
    dimensions=[]
)

print(f"Created Semantic Model: {my_semantic_model.name}")
print(f"Entities: {[e.name for e in my_semantic_model.entities]}")
print(f"Measures: {[m.name for m in my_semantic_model.measures]}")