Registry /
data / dbt-semantic-interfaces
Install & Compatibility
Where this runs
tested against v0.10.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.298s · 38.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 0.268s · 39MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaseModel
✓ from dsi_pydantic_shim import BaseModel
✗ from dbt_semantic_interfaces.models.semantic_model import SemanticModel
Field
✓ from dsi_pydantic_shim import Field
validator
✓ from dsi_pydantic_shim import validator
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]}")
Debug
Known issues
breakingUpgrades 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.fixConsult 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.
affects: >=0.8.0, >=0.10.0
gotchadbt-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.fixUnderstand 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.
affects: All
breakingThe 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.fixUpdate 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.
affects: <0.7.0 (when definitions were internal)
gotchaWhen 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.fixFor 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.
affects: All (latest YAML spec)
Upgrade
Version history
0.10.5latest on PyPI · released Feb 10, 2026
Audit
Dependencies
pydanticrequiredData validation and settings management.
pyyamlrequiredYAML parsing and serialization.
clickrequiredCommand line interface creation.
python-dateutilrequiredExtensions to the datetime module.
more-itertoolsrequiredToolbox of useful iteration helpers.
jsonschemarequiredJSON Schema validation.
jinja2requiredTemplating engine.
importlib-metadatarequiredRead metadata from installed packages.
typing-extensionsrequiredBackports and experimental type hints.