{"id":856,"library":"dbt-semantic-interfaces","title":"dbt-semantic-interfaces","description":"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.","status":"active","version":"0.10.5","language":"python","source_language":"en","source_url":"https://github.com/dbt-labs/dbt-semantic-interfaces","tags":["dbt","semantic-layer","data-modeling","pydantic","metricflow","data-governance"],"install":[{"cmd":"pip install dbt-semantic-interfaces","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Data validation and settings management.","package":"pydantic"},{"reason":"YAML parsing and serialization.","package":"pyyaml"},{"reason":"Command line interface creation.","package":"click"},{"reason":"Extensions to the datetime module.","package":"python-dateutil"},{"reason":"Toolbox of useful iteration helpers.","package":"more-itertools"},{"reason":"JSON Schema validation.","package":"jsonschema"},{"reason":"Templating engine.","package":"jinja2"},{"reason":"Read metadata from installed packages.","package":"importlib-metadata"},{"reason":"Backports and experimental type hints.","package":"typing-extensions"}],"imports":[{"symbol":"SemanticModel","correct":"from dbt_semantic_interfaces.models.semantic_model import SemanticModel"},{"symbol":"Metric","correct":"from dbt_semantic_interfaces.models.metric import Metric"}],"quickstart":{"code":"from dbt_semantic_interfaces.models.semantic_model import SemanticModel\nfrom dbt_semantic_interfaces.models.entities import PydanticEntity\nfrom dbt_semantic_interfaces.models.measures import PydanticMeasure\nfrom dbt_semantic_interfaces.type_enums import EntityType, TimeGranularity\n\n# A minimal example of defining a semantic model programmatically\nmy_entity = PydanticEntity(\n    name='customer_id',\n    type=EntityType.PRIMARY,\n    expr='id'\n)\n\nmy_measure = PydanticMeasure(\n    name='total_orders',\n    agg='count',\n    expr='order_id'\n)\n\nmy_semantic_model = SemanticModel(\n    name='customers_semantic_model',\n    description='A semantic model for customer data.',\n    node_relation=None, # This would typically link to a dbt model, omitted for brevity\n    entities=[my_entity],\n    measures=[my_measure],\n    dimensions=[]\n)\n\nprint(f\"Created Semantic Model: {my_semantic_model.name}\")\nprint(f\"Entities: {[e.name for e in my_semantic_model.entities]}\")\nprint(f\"Measures: {[m.name for m in my_semantic_model.measures]}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0, >=0.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.7.0 (when definitions were internal)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All (latest YAML spec)"}],"env_vars":null,"last_verified":"2026-05-12T20:27:12.523Z","next_check":"2026-06-29T00:00:00.000Z","problems":[{"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.","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.","error":"ImportError: cannot import name 'FilterCallParameterSets' from 'dbt_semantic_interfaces.call_parameter_sets'"},{"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.","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.","error":"Additional properties are not allowed ('metric-paths', 'semantic-model-paths' were unexpected)"},{"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.","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.","error":"Metric cannot reference a measure defined in the same semantic model (metric references non-existent measure)"},{"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.","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.","error":"ModuleNotFoundError: No module named 'dbt.adapters.factory'"}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.10.5","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","installed_version":"0.10.5","pypi_latest":"0.10.5","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"38.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":5.6,"import_time_s":null,"mem_mb":null,"disk_size":"39M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"42.8M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.8,"import_time_s":null,"mem_mb":null,"disk_size":"43M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"34.2M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":3.9,"import_time_s":null,"mem_mb":null,"disk_size":"34M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"33.9M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":4.1,"import_time_s":null,"mem_mb":null,"disk_size":"34M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"38.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"broken","install_time_s":6.3,"import_time_s":null,"mem_mb":null,"disk_size":"38M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"dbt-semantic-interfaces","exit_code":1,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}