Semantic Layer

Source on GitHub | Package README

The Semantic Layer is a standalone dbt package that reshapes Tuva Core and selected data mart outputs into reusable dimensions and facts for BI tools and downstream analytics. It replaces the semantic-layer mart that was bundled with Tuva through v0.18.0.

Requirements

The package requires claims data in Tuva Core and these standalone data marts:

Dependency	Purpose
Tuva Core	Core claims, member-month, cost, encounter, patient, practitioner, pharmacy, and terminology models
AHRQ Quality Indicators	Prevention Quality Indicator results used by admissions
CCSR	Diagnosis classification used by claims
CMS HCC	Risk scores, risk factors, and HCC suspecting outputs
NYU ED Classification	Emergency department classifications
Quality Measures	Quality measure and readmission outputs

Installation

Install Tuva Core and the required packages together in the root project. Use their v1.0.0 Git tags; this installation does not require a dbt Hub listing. See the release installation instructions for the complete package set and version checks:

packages.yml

packages:
  - git: "https://github.com/tuva-health/tuva-core.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/ahrq_quality_indicators.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/ccsr.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/cms_hcc.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/nyu_ed_classification.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/quality_measures.git"
    revision: "v1.0.0"
  - git: "https://github.com/tuva-health/semantic-layer.git"
    revision: "v1.0.0"

Enable claims in the consuming project:

dbt_project.yml

vars:
  claims_enabled: true

Installing the package is its enablement contract; there is no semantic_layer_enabled variable. Install and build the package graph with:

dbt deps
dbt build --select +package:semantic_layer --indirect-selection cautious

Models are created in semantic_layer, or <tuva_schema_prefix>_semantic_layer when tuva_schema_prefix is configured.

Outputs

Dimensions

Model	Description
semantic_layer.dim_data_source	Data sources represented in Core claims and eligibility.
semantic_layer.dim_date	Calendar dates spanning medical claim activity.
semantic_layer.dim_encounter_group	Stable semantic keys for encounter groups.
semantic_layer.dim_encounter_provider	Deterministically selected rendering provider for each encounter and data source.
semantic_layer.dim_encounter_type	Stable semantic keys for encounter types.
semantic_layer.dim_member	Member and patient attributes.
semantic_layer.dim_member_months	Member-month coverage and attribution attributes.
semantic_layer.dim_service_category	Service category hierarchy and semantic keys.

Facts

Model	Description
semantic_layer.fact_admissions	Acute inpatient admissions with readmission and AHRQ PQI attributes.
semantic_layer.fact_claims	Enrolled medical claim lines with encounter, service category, provider, and CCSR attributes.
semantic_layer.fact_ed_visits	Emergency department encounters with NYU classifications.
semantic_layer.fact_encounter_service_bridge	Bridge between encounters and service categories.
semantic_layer.fact_encounters	Claims-based encounters with stable encounter group and type keys.
semantic_layer.fact_hcc_gaps	HCC suspecting and recapture gaps.
semantic_layer.fact_member_months	Member-month enrollment, attribution, cost, and utilization facts.
semantic_layer.fact_pharmacy_claims	Core pharmacy claim lines with drug terminology and specialty-tier attributes.
semantic_layer.fact_quality_measures	Long-form quality measure results.
semantic_layer.fact_risk_factors	CMS-HCC risk factors.
semantic_layer.fact_risk_scores	CMS-HCC risk scores.

Migrating from v0.18.0

Two-argument refs must use the new dbt package name. For example, change ref('the_tuva_project', 'semantic_layer__fact_claims') to ref('semantic_layer', 'semantic_layer__fact_claims'). Final relation aliases such as fact_claims are retained.

The standalone package intentionally removes the following retired scope:

• dim_condition and fact_member_condition_bridge;
• fact_expected_values and its benchmark dependencies;
• the financial_pmpm staging dependency, which is replaced by Core core__cost; and
• pharmacy generic-opportunity fields formerly supplied by the retired pharmacy mart.

fact_pharmacy_claims remains available and is built directly from Core. Member-month models now use Core's member_month_id and full coverage grain; the legacy member_month_sk is retained only as a deprecated compatibility field.

Scope and limitations

Encounter-centric outputs retain the legacy claims-based boundary and consume only Core encounters where encounter_source_type = 'claim'. They do not include clinical encounters.

The 1.0 package set preserves data_source in person, encounter, claim, provider, and coverage joins. Quality-measure, risk-factor, risk-score, and HCC-gap facts include it in their tested grains. Date, encounter-type, encounter-group, and service-category dimensions are intentionally source-neutral. Use member_month_id for coverage joins; the deprecated member_month_sk contains only person and month and is not guaranteed unique. See the released source-scoping contract.

Data assets and medication terminology

The package loads its two encounter group/type key assets from data-marts/semantic-layer/<asset-version>/. semantic_layer_data_asset_version defaults to 1.0.0 and is independent of the code version. Seeding or building the selected package seeds loads these assets; no separate asset enablement flag is required.

Pharmacy facts use Core's shared CodeRx interfaces. Set use_coderx_enterprise: true only when the root project provides the user-managed coderx.packages, coderx.drugs, and coderx.classes relations. The specialty-tier threshold is configured through semantic_layer_specialty_tier_threshold (default 950) and compares the 30-day equivalent paid amount.