Risk Adjustment Data Marts

Note that Zus Risk Adjustment features are currently in public preview and are subject to change.

Risk adjustment analytics are exposed via flattened, query-friendly tables derived from the underlying FHIR MeasureReport resources.

Risk Gap Views

`risk_gap`

A denormalized view of one row per risk gap (MeasureReport).

Common field	Notes
`id`	Risk gap identifier.
`patient_id`, `upid`	Patient identifiers.
`code_hcc`, `hcc_version`	HCC code and model version.
`gap_type`	Recapture, suspect, or net-new.
`gap_status`	Current/latest status.
`confidence_level`	1–5 (5 = highest confidence).
`period_start`	Start date for the calendar-year period.
`created_at`, `last_updated_at`	Creation and last update timestamps.

Typical use case	Description
Population listing	List all current-year gaps for a population.
Segmentation	Segment by gap type/status.
Trends	Trend monitoring by period.

`risk_gap_status_update`

One row per status update event per risk gap (full history).

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`created_at`, `created_by`	When and by whom the status was created.
`status`	Status code for this update.
`note` (optional)	Free-text note.
`substatus_one`, `substatus_two`, `substatus_three` (optional)	Additional categorization fields.

Typical use case	Description
Audit trail	Audit trail of review workflows.
Operational metrics	Measuring time-to-close or time-to-review.
Status evolution	Understanding how gaps evolve (e.g., open → expected-to-close → closed).

`risk_gap_hierarchy`

Represents superseding relationships between gaps based on HCC hierarchy.

Common field	Notes
`risk_gap_id`	The superseded gap.
`superseded_by_risk_gap_id`	The superseding gap.

Typical use case	Description
Top-level filtering	Filter to top-level gaps only.
Accurate counts	Avoid double-counting related HCCs in reporting.

`risk_gap_source`

Identifies which upstream sources contributed to each risk gap.

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`source`	Contributing source (e.g., rules-based, AI, payer, user).
`last_updated`	When the risk gap was last updated.

Typical use case	Description
Attribution	"Which systems are producing gaps?"
QA	QA and monitoring by source.

`risk_gap_diagnosis_code`

Normalized mapping of ICD-10 codes to risk gaps (one row per ICD-10 per gap).

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`code_icd_10`	ICD-10 diagnosis code.

Typical use case	Description
Drilldown	Drilldown from HCC gap → supporting ICD-10s.
Comparisons	Compare coding patterns across providers.

`risk_gap_evidence`

Normalized mapping from risk gaps to evidence resources.

Common field	Notes
`risk_gap_id`	Link to `risk_gap.id`.
`resource_type`, `resource_id`	The referenced FHIR resource.
`type`	`evaluated` or `related`.
`last_updated`	When the risk gap was last updated.
`last_encounter_diagnosis_recorded_date` (when applicable)	Most recent encounter diagnosis timestamp for the evaluated resource.

Typical use case	Description
Reviewer experiences	Build reviewer experiences (evidence panels).
Analytics	Analytics on evidence completeness/recency.

Linking back to FHIR

You can often construct a direct FHIR reference using:

.../fhir/{resource_type}/{resource_id}

(Your exact base URL will depend on your deployment/environment.)

RAF Score Views

`raf_score_v28` and `raf_score_v24`

One row per patient, builder, and calendar year with aggregated RAF metrics based on v28 and v24 CMS HCC models. These are estimates and not always the same scores that are in our raf_score table, which contains RAF Score MeasureReports data.

Common field	Notes
`upid`	Universal patient identifier.
`patient_id`	Patient identifier.
`potential_raf`	RAF score if all non-dismissed gaps were paid.
`potential_hcc_count`	Count of HCCs contributing to potential score.
`current_raf`	RAF score for closed gaps only.
`current_hcc_count`	Count of HCCs contributing to the current socore
`raf_gap`	Difference: potential_raf − actual_raf.
`hcc_gap`	Difference: potential_hcc_count − actual_hcc_count.

Typical use case	Description
Population overview	Aggregate RAF opportunity across a patient panel.
Gap prioritization	Identify patients with largest `raf_gap`.
Trend tracking	Monitor score changes over time.

`raf_score`

Table for analyzing RAF Score MeasureReport FHIR resources.

Common field	Notes
`id`	ID of the RAF Score MeasureReport Resource.
`upid`	Universal patient identifier.
`patient_id`	Patient identifier.
`period_start`	Start date for the calendar-year period.
`actual_raf_score`	Current RAF score of closed gaps.
`expected_raf_score`	RAF score for expected-to-close and closed gaps.
`potential_raf_score`	RAF score if all non-dismissed gaps were paid.
`measure`	The MeasureReport.measure value.
`last_updated`	When the MeasureReport resource was last updated.
`created_at`	When the MeasureReport resource was created.
`raf_score_model`	The model applied to RAF scoring.

Typical use case	Description
Risk Gap Measure Report attribution	Link RAF scores to specific data in the risk_gap data.
Trend Changes	Identify how risk gap RAF score changed over time.

Payer Risk Gap Views

`payer_risk_gap`

Table for analyzing Payer Risk Gap MeasureReport FHIR resources.

Common field	Notes
`id`	ID of the Risk Gap MeasureReport Resource.
`upid`	Universal patient identifier.
`patient_id`	Patient identifier.
`period_start`	Start date for the calendar-year period.
`code_hcc_version`	HCC CMS version (e.g. 'V28').
`code_hcc`	HCC code of the Risk Gap.
`code_icd_10`	ICD-10-CM code of the Risk Gap.
`last_claim_date`	The last date reported by the Payer Risk Gap file.
`last_updated`	When the MeasureReport resource was last updated.
`created_at`	When the MeasureReport resource was created.
`measure`	The MeasureReport.measure value. (e.g. http://zusapi.com/quality/measure/risk/CMSv28 )
`gap_source`	Where the MeasureReport was created (e.g. payer-risk-gap-csv-file).
`payer_reported_recapture_flag`	The recapture / not recaptured status according to the payer.
`payer_reported_status`	The status (open / closed) according to the payer file.
`reason`	The reason the payer gave for the current reported status and recapture status.

Typical use case	Description
Risk Gap Source Tracking	Identify payer gap data provided to create certain `risk_gap` entries.
Import tracking	Successfully imported Payer Risk Gap CSVs create Payer Risk Gaps which ultimately reach the `payer_risk_gap` data mart. This allows you to check if a CSV completed successfully.

Risk Gap Views

risk_gap

risk_gap_status_update

risk_gap_hierarchy

risk_gap_source

risk_gap_diagnosis_code

risk_gap_evidence