dbt-semantic-interfaces

0.10.5 · active · verified Sun Mar 29

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.

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

pip install dbt-semantic-interfaces Install latest version

Imports

SemanticModel

from dbt_semantic_interfaces.models.semantic_model import SemanticModel

Metric

from dbt_semantic_interfaces.models.metric import Metric

Quickstart

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]}")

view raw JSON →