Skip to content

Numera Semantic Model

The Numera semantic model is a YAML-defined schema that describes the complete star schema for the EWE Numera platform — which dimension tables exist, what columns they contain, and how each fact table joins to them. It is the authoritative source for understanding what data is available, how tables relate, and which measures can be aggregated.

Not dbt MetricFlow

The Numera semantic model is a custom format specific to the Numera platform. It is distinct from the dbt MetricFlow semantic layer (semantic_manifest.json), which is empty in this project. The semantic model predates MetricFlow and serves a broader purpose: describing the full star schema for query construction, regression testing, and documentation.

The design rationale is documented in ADR-0008 (docs/adr/ADR-0008-semantic-star-schema-model.md in the repo).

Two-File Composition

The merged model is composed from two YAML files using an import/merge mechanism:

  1. numera-core/semantic_model.yaml — the core Numera schema, defining the standard dimensions and facts shared across all Numera deployments.
  2. semantic_model.yaml (EWE project root) — EWE-specific extensions. It imports the core model and adds one additional dimension and 14 EWE-specific facts.
File Role Dimensions Facts
numera-core/semantic_model.yaml Core schema 42 30
semantic_model.yaml (EWE) EWE extensions +1 +14
Merged Complete model 43 44

Merge rules:

  • Same-name entries in the EWE file override the core definition field-by-field.
  • New dimensions and facts in the EWE file are addended to the merged model.
  • The imports key resolves paths relative to the importing file, with circular-import detection.

The Python loader at numera-util/numera_util/regress_test/semantic_model_loader.py implements this merge and returns a SemanticModel object used by the regression test suite and documentation tooling.

Dimension Families

The 43 dimensions are grouped into 11 domain families:

Family Count Dimensions Purpose
Deal 9 dim_deal_attribute, dim_deal_sub_attribute, dim_deal_physical, dim_deal_financial, dim_tran_info, dim_tran_status, dim_tran_info_type, dim_exchange_traded_product, dim_ins_option Deal and transaction attributes
Party 4 dim_party_internal, dim_party_external, dim_party_agreement, dim_party_agreement_attribute (EWE) Internal BUs, external counterparties, agreements
Location 3 dim_delivery_location, dim_point_of_delivery_location, dim_point_of_receipt_location Physical delivery and receipt points
Date / Time 4 dim_date, dim_month, dim_metric_date, dim_current_date Calendar and valuation dates
Metric / Scenario 2 dim_metric_scenario, dim_reval_type Valuation scenarios and reval types
Portfolio 2 dim_portfolio, dim_pfolio Portfolio groupings
Index / Price 4 dim_index_attribute, dim_ref_source, dim_index (deprecated), dim_index_gpt (deprecated) Price indices and gridpoints
Volume 2 dim_volume_type, dim_volume_15m_shape Volume shape and classification
Fee / Payment 6 dim_payment, dim_fee_def, dim_broker_fee, dim_document, dim_keep_whole, dim_settle_profile (high cardinality) Fees, payments, and settlement
Reference / Utility 6 dim_reference, dim_currency, dim_unit, dim_calendar, dim_version, dim_numera_version Reference data and utility
Volatility 1 dim_volatility Volatility surface data

Fact Families

The 44 facts are grouped into 13 domain families. Facts marked EWE are defined in the EWE extension file; all others come from the core schema.

Family Count Facts Description
P&L 4 fct_pnl, fct_pnl_deal, fct_deal_pnl_current, fct_stress_deal Profit and loss across scenarios
Delta / Risk 3 fct_delta, fct_delta_profile, fct_delta_profile_period Delta and gamma risk
Vega 3 fct_vega, fct_vega_profile, fct_vega_var_pfolio Vega risk and vega VaR
VaR 1 fct_var_pfolio Value-at-Risk at portfolio level
15-Min Volume 3 fct_volume_15m, fct_volume_15m_deal, fct_volume_factor_deal Granular 15-minute volumes
Index / Price 2 fct_index_rate, fct_index_price_history Pricing curves and history
Deal 10 fct_deal, fct_deal_side, fct_deal_fee, fct_deal_physcash, fct_deal_commodity_pricing, fct_deal_commodity_pricing_index, fct_deal_tran_info_history, fct_broker_fee, fct_cerqlar_deal, fct_futures_cascade Deal master and attributes
Schedule 2 fct_schedule, fct_schedule_history Delivery schedule data
Settlement 2 fct_settle_deal, fct_event_deal Settlement events
Credit Exposure (EWE) 5 fct_credit_exposure, fct_credit_exposure_month, fct_credit_stress_test, fct_credit_stress_test_month, fct_credit_pex_factor Credit risk and exposure
Clearing (EWE) 1 fct_clearing_statement_open_position Clearing bank positions
Short-Term Power (EWE) 6 fct_ewe_volume_pwr_by_business_case, fct_ewe_volume_pwr_by_business_case_deal, fct_ewe_volume_pwr_floating_by_business_case, fct_ewe_volume_pwr_floating_by_business_case_deal, fct_volume_pwr_quarter_fixed_price, fct_volume_pwr_quarter_fixed_price_deal 15-minute power volumes
Monitoring (EWE) 2 fct_data_arrival, fct_sim_expectation Operational pipeline health

When to Use This Reference vs dbt Documentation

Need Use
Which dimensions can I join to fct_pnl? Semantic Model → Facts catalogue
What columns does dim_deal_attribute have? Semantic Model → Dimensions catalogue
Is fct_credit_exposure a finer or coarser grain than fct_credit_exposure_month? Semantic Model → Aggregation chain pattern
What SQL tests are defined on dim_party_external? dbt Documentation
What is the upstream source lineage of fct_pnl? dbt Documentation
What does exposure_limit mean in business terms? Business Glossary

See Also