> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metriport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/medical-api/handling-data/schema-v100) 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):

| Column          | Data Type | Description                                                                         |
| --------------- | --------- | ----------------------------------------------------------------------------------- |
| `{parent_id}`   | varchar   | The ID of the parent resource (e.g., `encounter_id`, `diagnosticreport_id`)         |
| property        | varchar   | The FHIR property name (e.g., `subject`, `performer`, `participant.individual`)     |
| reference\_id   | varchar   | The extracted reference ID from the FHIR reference string                           |
| reference\_type | varchar   | The resource type being referenced (e.g., `Patient`, `Practitioner`, `Observation`) |

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](/medical-api/handling-data/schema-v100/allergyintolerance/base).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **encounter**: links to the [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **recorder**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)
* **asserter**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)

### CarePlan References

Parent ID column: `careplan_id`. Parent table: [careplan](/medical-api/handling-data/schema-v100/careplan/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **author**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or other per `reference_type`
* **addresses**: links to the resource (e.g., [condition](/medical-api/handling-data/schema-v100/condition)) that this care plan addresses (sourced from `careplan_addresses` stage table)

### Communication References

Parent ID column: `communication_id`. Parent table: [communication](/medical-api/handling-data/schema-v100/communication).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

### Composition References

Parent ID column: `composition_id`. Parent table: [composition](/medical-api/handling-data/schema-v100/composition/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

**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](/medical-api/handling-data/schema-v100/condition).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **encounter**: links to the [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **recorder**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)
* **asserter**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)

### Consent References

Parent ID column: `consent_id`. Parent table: [consent](/medical-api/handling-data/schema-v100/consent).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **performer**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`

### Coverage References

Parent ID column: `coverage_id`. Parent table: [coverage](/medical-api/handling-data/schema-v100/coverage).

* **beneficiary**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **payor**: links to [organization](/medical-api/handling-data/schema-v100/organization/base) or [patient](/medical-api/handling-data/schema-v100/patient/base) per `reference_type` (one row per payor, sourced from `coverage_payor` stage table)

### Device References

Parent ID column: `device_id`. Parent table: [device](/medical-api/handling-data/schema-v100/device).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **definition**: links to the device definition resource per `reference_type`
* **location**: links to the [location](/medical-api/handling-data/schema-v100/location/base)
* **owner**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)
* **parent**: links to the parent [device](/medical-api/handling-data/schema-v100/device) per `reference_type`

### DiagnosticReport References

Parent ID column: `diagnosticreport_id`. Parent table: [diagnosticreport](/medical-api/handling-data/schema-v100/diagnosticreport/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **encounter**: links to the [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **performer**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`
* **result**: links to [observation](/medical-api/handling-data/schema-v100/observation/base) when `reference_type = 'Observation'`

### DocumentReference References

Parent ID column: `documentreference_id`. Parent table: [documentreference](/medical-api/handling-data/schema-v100/documentreference/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **authenticator**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`
* **custodian**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)
* **context\_sourcepatientinfo**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base) per `reference_type`
* **masteridentifier\_assigner**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)

### Encounter References

Parent ID column: `encounter_id`. Parent table: [encounter](/medical-api/handling-data/schema-v100/encounter/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **partof**: links to a parent [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **serviceprovider**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)
* **location.location**: links to the [location](/medical-api/handling-data/schema-v100/location/base)
* **participant.individual**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) per `reference_type`
* **diagnosis.condition**: links to [condition](/medical-api/handling-data/schema-v100/condition) (sourced from `encounter_diagnosis` stage table); see also backbone [encounter\_diagnosis](/medical-api/handling-data/schema-v100/encounter/diagnosis)
* **hospitalization.destination**: links to the [location](/medical-api/handling-data/schema-v100/location/base)
* **hospitalization.origin**: links to the [location](/medical-api/handling-data/schema-v100/location/base)

### FamilyMemberHistory References

Parent ID column: `familymemberhistory_id`. Parent table: [familymemberhistory](/medical-api/handling-data/schema-v100/familymemberhistory/base).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

### Goal References

Parent ID column: `goal_id`. Parent table: [goal](/medical-api/handling-data/schema-v100/goal/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

### Immunization References

Parent ID column: `immunization_id`. Parent table: [immunization](/medical-api/handling-data/schema-v100/immunization).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **performer.actor**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`

### Location References

Parent ID column: `location_id`. Parent table: [location](/medical-api/handling-data/schema-v100/location/base).

* **managingorganization**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)
* **partof**: links to a parent [location](/medical-api/handling-data/schema-v100/location/base)

### MedicationAdministration References

Parent ID column: `medicationadministration_id`. Parent table: [medicationadministration](/medical-api/handling-data/schema-v100/medicationadministration/base).

* **medication\_reference**: links to the [medication](/medical-api/handling-data/schema-v100/medication)
* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **performer.actor**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`
* **reasonReference**: links to [condition](/medical-api/handling-data/schema-v100/condition) or other clinical resource per `reference_type`

### MedicationDispense References

Parent ID column: `medicationdispense_id`. Parent table: [medicationdispense](/medical-api/handling-data/schema-v100/medicationdispense/base).

* **medication\_reference**: links to the [medication](/medical-api/handling-data/schema-v100/medication)
* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **performer.actor**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`

### MedicationRequest References

Parent ID column: `medicationrequest_id`. Parent table: [medicationrequest](/medical-api/handling-data/schema-v100/medicationrequest/base).

* **medication\_reference**: links to the [medication](/medical-api/handling-data/schema-v100/medication)
* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **requester**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`
* **reasonReference**: links to [condition](/medical-api/handling-data/schema-v100/condition) or other clinical resource per `reference_type`

### MedicationStatement References

Parent ID column: `medicationstatement_id`. Parent table: [medicationstatement](/medical-api/handling-data/schema-v100/medicationstatement/base).

* **medication\_reference**: links to the [medication](/medical-api/handling-data/schema-v100/medication)
* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

### Observation References

Parent ID column: `observation_id`. Parent table: [observation](/medical-api/handling-data/schema-v100/observation/base).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **encounter**: links to the [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **performer**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`
* **device**: links to the [device](/medical-api/handling-data/schema-v100/device) per `reference_type`
* **specimen**: links to the specimen resource per `reference_type`

### Organization References

Parent ID column: `organization_id`. Parent table: [organization](/medical-api/handling-data/schema-v100/organization/base).

* **partof**: links to a parent [organization](/medical-api/handling-data/schema-v100/organization/base)

### Patient References

Parent ID column: `patient_id`. Parent table: [patient](/medical-api/handling-data/schema-v100/patient/base).

* **managingorganization**: links to the [organization](/medical-api/handling-data/schema-v100/organization/base)

### Procedure References

Parent ID column: `procedure_id`. Parent table: [procedure](/medical-api/handling-data/schema-v100/procedure).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **encounter**: links to the [encounter](/medical-api/handling-data/schema-v100/encounter/base)
* **location**: links to the [location](/medical-api/handling-data/schema-v100/location/base)
* **recorder**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)
* **asserter**: links to the [practitioner](/medical-api/handling-data/schema-v100/practitioner/base)
* **report**: links to [diagnosticreport](/medical-api/handling-data/schema-v100/diagnosticreport/base) when `reference_type = 'DiagnosticReport'` (sourced from `procedure_report` stage table)

### RelatedPerson References

Parent ID column: `relatedperson_id`. Parent table: [relatedperson](/medical-api/handling-data/schema-v100/relatedperson/base).

* **patient**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)

### ServiceRequest References

Parent ID column: `servicerequest_id`. Parent table: [servicerequest](/medical-api/handling-data/schema-v100/servicerequest).

* **subject**: links to the [patient](/medical-api/handling-data/schema-v100/patient/base)
* **requester**: links to [practitioner](/medical-api/handling-data/schema-v100/practitioner/base) or [organization](/medical-api/handling-data/schema-v100/organization/base) per `reference_type`