As a data standard designed around healthcare interoperability, FHIR is optimized for transactions on a single resource or bundle of resources. This makes FHIR great for sharing information about individual patients across systems in real-time, but less than ideal for analytical use cases. Work must be done to transform FHIR’s heavily nested JSON structure into a "flat" data format that analytics platforms can ingest.

Zus data marts do exactly that, extracting and transforming FHIR data into a relational format for SQL-based exploration and analysis.

Getting familiar with Zus data

For users accessing data marts via Snowflake, you can view all the tables in your data mart by clicking on "Data" in the left sidebar. You should see a database called {COMPANY_NAME}_EXPORT_ZUS. If you click on the database to expand its contents and then click on the schema {COMPANY_NAME}_RELATIONAL , and then finally click "Views", you should see about 200 tables available to you to query in your Zus data mart.

For more information about the data and schema, please see our:

• Data dictionary
• Schema diagrams

Supported FHIR resources

The following resource types are exported as data mart tables: AllergyIntolerance, Appointment, Consent, CarePlan, CareTeam, Condition, Coverage, Device, DeviceUseStatement, DiagnosticReport, DocumentReference, Encounter, FamilyMemberHistory, Goal, Immunization, Location, Medication, MedicationAdministration, MedicationDispense, MedicationRequest, MedicationStatement, Observation, Organization, Patient, Practitioner, Procedure, and RelatedPerson.

Table types

The Zus Aggregated Profile (or ZAP) is an up-to-date, comprehensive record of a given patient's health history, assembled and curated by Zus from various external data networks. The ZAP includes first-party data written and managed by your Builder organization, Zus summarized Lens data, and third-party data from EHR, pharmacy, ADT, and lab networks. Zus data marts make available all of this information in three types of tables.

Data sources

The DATA_SOURCE column is available as a column for every base FHIR resource table. When the DATA_SOURCE column is NULL, that reflects that the data is first-party written and managed by your organization. This also includes data that comes from Zus’ EHR integrations.

When the DATA_SOURCE column is not NULL, this reflects that the data is third-party and came from the Zus network. DATA_SOURCE values include:

• EHR networks: commonwell, carequality
• Pharmacy-sourced medications: surescripts
• ADT notifications: bamboohealth, collective-medical, manifest-medex, eden, florida-hie, etc.
• Lab notifications: quest

Universal patient identifier

Zus offers its own identity mapping service, the Universal Patient Index, to link disparate and duplicative patient records. The universal patient identifier is available as a column called UPID for every base FHIR resource and Lens table types, except for Location, Medication, Practitioner, and Organization.

Every row in the PATIENT table is a FHIR Patient resource that has a unique ID. Each Patient resource corresponds to a different copy of one human being's data that Zus has aggregated. For example, for one human, there could be one Patient resource from Surescripts, one for each responding organization that responded via the Carequality network, and one from Quest. If there are 10 Patient resources that all correspond to the same human, each Patient resource will have a unique ID but the same UPID.

📘

Your data mart will only include data for patients for whom your Builder organization has an active treatment relationship.

Exploring the data

To start exploring the data, click on + Create in the left sidebar of Snowflake and select SQL Worksheet.

Let's run a simple query to count the number of distinct patients included in the data mart and click the blue play button on the top right to execute.

select
    count(distinct upid)
from patient

🥳 Congratulations! You completed your first query on the Zus data mart!

For additional tutorials on analyzing Zus data, we recommend checking out our query library.

Additional details

Refreshing your data mart

Zus data marts automatically refresh daily with the latest available information for your patient population.

This means that the latest version of each FHIR resource should be available in your data mart within 24 hours of a change in the Zus platform for the following resource types:

• AllergyIntolerance, Appointment, CarePlan, CareTeam, Consent, Coverage, DeviceUseStatement, DiagnosticReport, FamilyMemberHistory, Goal, Immunization, Lens Encounter, Lens Condition, Lens MedicationStatement, Medication, MedicationAdministration, MedicationDispense, MedicationRequest, MedicationStatement, Observation, Procedure, and RelatedPerson

For the following tables, the target latency has been reduced from 24 hours to 3 hours:

• Condition, Device, DocumentReference, Encounter, EpisodeOfCare (presented as LENS_TRANSITION_OF_CARE), Location, Organization, Patient, and Practitioner

Note: this reduced target latency only applies to the parent FHIR resource tables, and not the related child tables (for example, the CONDITION table has a target latency of 3 hours, while CONDITION_CATEGORY and CONDITION_CATEGORY_CONDITION have a target latency of 24 hours).

Data mart tables do not update on a set schedule, but on a rolling basis through the day, which means that referential integrity is not preserved across Zus data marts.

For time-sensitive use cases or use cases where referential integrity is critical, we encourage customers to leverage Zus FHIR APIs or Zushooks, which reflect the latest data on the Zus platform as soon as a FHIR resource is updated.

Data marts versioning

Zus will update the relational schema to keep up with customer needs and data quality best practices, but will ensure that changes to an existing version of the schema are non-breaking.

If breaking changes are needed, they will be introduced in a new schema version. Each new generally available version will be supported for a minimum of 9 months, and customers will be given at least 60 days to transition to a new version once it is made generally available. Zus reserves the right to introduce a breaking change without notice if it impacts an unused feature of the data mart.

Stay tuned for updates and detailed release notes with each new version. We are committed to providing the best experience and ensuring seamless transitions.

❓

What is a breaking change?

A breaking change in a data mart schema disrupts existing functionality or requires users to alter how they interact with the data mart. These changes can impact data querying, processing, or interpretation, necessitating adjustments to reports, dashboards, or applications relying on the schema.

Examples of breaking changes include:

• Schema modifications:
  • Changing the name of an existing column or table
  • Removing an existing table or column
• Data type changes: Altering the data type of an existing column (e.g., from integer to string)
• Constraint changes:
  • Modifying or removing primary keys
  • Modifying or removing foreign key relationships
  • Adding or removing unique constraints
    
    

Note: Adding a column or table or reordering existing columns within a table does not constitute a breaking change.