Skip to main content

​
Overview

Care Gaps automatically identifies missing or incomplete care for patients based on HEDIS quality measures. The system analyzes patient data to determine whether recommended screenings, preventive care, and treatments have been completed according to evidence-based guidelines. Care gaps are represented as MeasureReport resources that capture the results of quality measure calculations, including population membership (initial population, denominator, numerator) and supporting evidence used in the calculation. Care Gaps runs at scheduled intervals and analyzes your patient population to identify opportunities for improving care quality and closing gaps in care delivery.

​
Available Measures

The following HEDIS measures are currently supported:
MeasureCode
Breast Cancer ScreeningBCSE
Colorectal Cancer ScreeningCOLE

​
Getting Started

Care Gaps runs at scheduled intervals and analyzes your patient data to identify gaps in care. Once care gaps is enabled for your account, results will be available through the API and data warehouse.

​
Accessing via API

You can retrieve care gap records using the /medical/v1/care-gap endpoint. Care gaps are returned as FHIR MeasureReport resources with embedded supporting evidence.

​
Accessing via Data Warehouse

Care gap records are stored in dedicated tables in the data warehouse. The schema includes both the MeasureReport resources and their associated Measure definitions.

​
Table Schemas

For detailed schema information about the MEASURE_REPORT table, see the MeasureReport schema documentation.

​
Identifying Care Gaps

A care gap exists when a patient:
  1. Is in the initial population (count = 1)
  2. Is in the denominator (count = 1)
  3. Is NOT in the denominator exclusion (count = 0)
  4. Is NOT in the numerator (count = 0)

​
Example Queries

​
Find all open care gaps for a patient

Since population data is in the GROUP column as a JSON array, we need to flatten it: 
WITH population_counts AS (
  SELECT
    mr.MEASURE_REPORT_ID,
    mr.PATIENT_ID,
    m.NAME,
    m.TITLE,
    grp.value:code.coding[0].code::STRING as group_code,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'initial-population' LIMIT 1) as initial_population,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'denominator' LIMIT 1) as denominator,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'denominator-exclusion' LIMIT 1) as denominator_exclusion,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'numerator' LIMIT 1) as numerator,
    mr.PERIOD_END
  FROM MEASURE_REPORT mr
  JOIN MEASURE m ON mr.MEASURE = m.URL,
    LATERAL FLATTEN(input => mr.GROUP) as grp
)
SELECT
  MEASURE_REPORT_ID,
  PATIENT_ID,
  NAME,
  TITLE,
  group_code,
  initial_population,
  denominator,
  denominator_exclusion,
  numerator,
  PERIOD_END
FROM population_counts
WHERE PATIENT_ID = 'patient-123'
  AND initial_population = 1
  AND denominator = 1
  AND denominator_exclusion = 0
  AND numerator = 0  -- Gap: in denominator but not numerator
ORDER BY PERIOD_END DESC;

​
Count compliant patients by measure

WITH population_data AS (
  SELECT
    mr.MEASURE_REPORT_ID,
    mr.PATIENT_ID,
    m.URL,
    m.TITLE,
    grp.value as group_data,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'initial-population' LIMIT 1) as initial_population,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'denominator' LIMIT 1) as denominator,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'denominator-exclusion' LIMIT 1) as denominator_exclusion,
    (SELECT pop.value:count::INTEGER FROM LATERAL FLATTEN(input => grp.value:population) pop WHERE pop.value:code.coding[0].code::STRING = 'numerator' LIMIT 1) as numerator
  FROM MEASURE_REPORT mr
  JOIN MEASURE m ON mr.MEASURE = m.URL,
    LATERAL FLATTEN(input => mr.GROUP) as grp
  WHERE YEAR(mr.PERIOD_END) = 2025
)
SELECT
  TITLE,
  COUNT(DISTINCT CASE
    WHEN denominator = 1 AND numerator = 1
    THEN PATIENT_ID
  END) as compliant_count,
  COUNT(DISTINCT CASE
    WHEN denominator = 1
    THEN PATIENT_ID
  END) as denominator_count
FROM population_data
WHERE initial_population = 1
  AND denominator_exclusion = 0
GROUP BY TITLE
ORDER BY compliant_count DESC;

​
The Care Gap Model

When a care gap is identified, the API returns a FHIR MeasureReport resource with the following structure: 
{
  "resourceType": "MeasureReport",
  "id": "mr-123",
  "meta": {
    "extension": [
      {
        "url": "http://metriport.com/fhir/StructureDefinition/supporting-evidence",
        "valueReference": {
          "reference": "#parameters-123"
        }
      }
    ]
  },
  "contained": [
    {
      "resourceType": "Parameters",
      "id": "parameters-123",
      "parameter": [
        {
          "name": "Age at end of measurement period",
          "valueInteger": 42
        },
        {
          "name": "Initial population",
          "valueBoolean": true
        },
        {
          "name": "Denominator",
          "valueBoolean": true
        },
        {
          "name": "Numerator",
          "valueBoolean": false
        },
        {
          "name": "Mammography screening period",
          "valuePeriod": {
            "start": "2023-10-01",
            "end": "2025-12-31"
          }
        }
      ]
    }
  ],
  "status": "complete",
  "type": "individual",
  "measure": "http://ncqa.org/fhir/Measure/BCSE-Details",
  "subject": {
    "reference": "Patient/patient-123"
  },
  "date": "2025-12-05T14:30:15Z",
  "period": {
    "start": "2025-01-01",
    "end": "2025-12-31"
  },
  "group": [
    {
      "id": "BreastCancerScreening",
      "code": {
        "coding": [
          {
            "system": "https://ncqa.org/fhir/CodeSystem/measure-group",
            "code": "BreastCancerScreening"
          }
        ]
      },
      "population": [
        {
          "code": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/CodeSystem/measure-population",
                "code": "initial-population"
              }
            ]
          },
          "count": 1
        },
        {
          "code": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/CodeSystem/measure-population",
                "code": "denominator-exclusion"
              }
            ]
          },
          "count": 0
        },
        {
          "code": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/CodeSystem/measure-population",
                "code": "denominator"
              }
            ]
          },
          "count": 1
        },
        {
          "code": {
            "coding": [
              {
                "system": "http://hl7.org/fhir/CodeSystem/measure-population",
                "code": "numerator"
              }
            ]
          },
          "count": 0
        }
      ]
    }
  ]
}

​
Additional Information

For more information about working with patient data, see the data analytics documentation.