Reference Tables

Reference tables are normalized tables that store FHIR resource references in a structured format. They provide a consistent way to link resources across the Metriport data model. Each reference table is named {resource}_references (e.g., encounter_references). The parent ID column name varies by resource (e.g., encounter_id, diagnosticreport_id). Policy: All references for a resource (first-level and nested) are in the resource’s main reference table. Backbone tables hold their own reference columns. Resources without a *_references model in core: Binary, Medication, and Practitioner. Every other resource in the v100 table index has a *_references dbt model under packages/data-transformation/raw-to-core/models/core_pipeline/core/. Some models use an empty reference list in SQL today (reserved for future stage columns); the table still exists for pipeline consistency. Standard columns (parent ID column name varies by resource): Core schema validates reference_id against specific target tables when property and reference_type match the defined relationships below. Other rows are stored but not necessarily FK-validated.

​

Reference Tables by Resource Type

​

AllergyIntolerance References

Parent ID column: allergyintolerance_id. Parent table: allergyintolerance.

• patient: links to the patient
• encounter: links to the encounter
• recorder: links to the practitioner
• asserter: links to the practitioner

​

CarePlan References

Parent ID column: careplan_id. Parent table: careplan.

• subject: links to the patient
• author: links to practitioner or other per reference_type
• addresses: links to the resource (e.g., condition) that this care plan addresses (sourced from careplan_addresses stage table)

​

Communication References

Parent ID column: communication_id. Parent table: communication.

• subject: links to the patient

​

Composition References

Parent ID column: composition_id. Parent table: composition.

• subject: links to the patient

Note: attester.party, section.entry, and other composition references are not yet in the stage pipeline and are therefore absent from this table.

​

Condition References

Parent ID column: condition_id. Parent table: condition.

• subject: links to the patient
• encounter: links to the encounter
• recorder: links to the practitioner
• asserter: links to the practitioner

​

Consent References

Parent ID column: consent_id. Parent table: consent.

• patient: links to the patient
• performer: links to practitioner or organization per reference_type

​

Coverage References

Parent ID column: coverage_id. Parent table: coverage.

• beneficiary: links to the patient
• payor: links to organization or patient per reference_type (one row per payor, sourced from coverage_payor stage table)

​

Device References

Parent ID column: device_id. Parent table: device.

• patient: links to the patient
• definition: links to the device definition resource per reference_type
• location: links to the location
• owner: links to the organization
• parent: links to the parent device per reference_type

​

DiagnosticReport References

Parent ID column: diagnosticreport_id. Parent table: diagnosticreport.

• subject: links to the patient
• encounter: links to the encounter
• performer: links to practitioner or organization per reference_type
• result: links to observation when reference_type = 'Observation'

​

DocumentReference References

Parent ID column: documentreference_id. Parent table: documentreference.

• subject: links to the patient
• authenticator: links to practitioner or organization per reference_type
• custodian: links to the organization
• context_sourcepatientinfo: links to the patient per reference_type
• masteridentifier_assigner: links to the organization

​

Encounter References

Parent ID column: encounter_id. Parent table: encounter.

• subject: links to the patient
• partof: links to a parent encounter
• serviceprovider: links to the organization
• location.location: links to the location
• participant.individual: links to practitioner per reference_type
• diagnosis.condition: links to condition (sourced from encounter_diagnosis stage table); see also backbone encounter_diagnosis
• hospitalization.destination: links to the location
• hospitalization.origin: links to the location

​

FamilyMemberHistory References

Parent ID column: familymemberhistory_id. Parent table: familymemberhistory.

• patient: links to the patient

​

Goal References

Parent ID column: goal_id. Parent table: goal.

• subject: links to the patient

​

Immunization References

Parent ID column: immunization_id. Parent table: immunization.

• patient: links to the patient
• performer.actor: links to practitioner or organization per reference_type

​

Location References

Parent ID column: location_id. Parent table: location.

• managingorganization: links to the organization
• partof: links to a parent location

​

MedicationAdministration References

Parent ID column: medicationadministration_id. Parent table: medicationadministration.

• medication_reference: links to the medication
• subject: links to the patient
• performer.actor: links to practitioner or organization per reference_type
• reasonReference: links to condition or other clinical resource per reference_type

​

MedicationDispense References

Parent ID column: medicationdispense_id. Parent table: medicationdispense.

• medication_reference: links to the medication
• subject: links to the patient
• performer.actor: links to practitioner or organization per reference_type

​

MedicationRequest References

Parent ID column: medicationrequest_id. Parent table: medicationrequest.

• medication_reference: links to the medication
• subject: links to the patient
• requester: links to practitioner or organization per reference_type
• reasonReference: links to condition or other clinical resource per reference_type

​

MedicationStatement References

Parent ID column: medicationstatement_id. Parent table: medicationstatement.

• medication_reference: links to the medication
• subject: links to the patient

​

Observation References

Parent ID column: observation_id. Parent table: observation.

• subject: links to the patient
• encounter: links to the encounter
• performer: links to practitioner or organization per reference_type
• device: links to the device per reference_type
• specimen: links to the specimen resource per reference_type

​

Organization References

Parent ID column: organization_id. Parent table: organization.

• partof: links to a parent organization

​

Patient References

Parent ID column: patient_id. Parent table: patient.

• managingorganization: links to the organization

​

Procedure References

Parent ID column: procedure_id. Parent table: procedure.

• subject: links to the patient
• encounter: links to the encounter
• location: links to the location
• recorder: links to the practitioner
• asserter: links to the practitioner
• report: links to diagnosticreport when reference_type = 'DiagnosticReport' (sourced from procedure_report stage table)

​

RelatedPerson References

Parent ID column: relatedperson_id. Parent table: relatedperson.

• patient: links to the patient

​

ServiceRequest References

Parent ID column: servicerequest_id. Parent table: servicerequest.

• subject: links to the patient
• requester: links to practitioner or organization per reference_type