Resource $graph
The $graph operation fetches all resources related to a given resource as defined by a GraphDefinition. This allows you to retrieve a complete graph of related resources in a single request.
Use Cases
- Patient Summary with Related Resources: Fetch a patient along with their conditions, medications, and allergies in a single request
- Care Team Retrieval: Load a care team with all practitioners, organizations, and the patient
- Profile Validation Setup: Load all profiles needed to validate a resource
- UI Data Loading: Efficiently load complex data relationships for clinical dashboards
Invocation
GET [base]/[ResourceType]/[id]/$graph?graph=[GraphDefinition name]
Input Parameters
| Parameter | Cardinality | Type | Description |
|---|---|---|---|
graph | 1..1 | string | The name of the GraphDefinition to apply |
Output
Returns a Bundle of type collection containing all resources found by traversing the graph.
GraphDefinition Structure
A GraphDefinition defines how to traverse from a starting resource to related resources. It consists of:
- start: The resource type where the graph begins
- link: An array of links defining how to find related resources
Link Types
Links can be defined using two methods:
1. FHIRPath Links
Use a FHIRPath expression to evaluate references on the current resource:
{
"path": "subject",
"target": [
{
"type": "Patient",
"link": []
}
]
}
2. Search Links
Use search parameters to find resources that reference the current resource:
{
"target": [
{
"type": "Observation",
"params": "subject={ref}"
}
]
}
The {ref} placeholder is replaced with the current resource reference.
Example
GraphDefinition
{
"resourceType": "GraphDefinition",
"name": "patient-with-observations",
"status": "active",
"start": "Patient",
"link": [
{
"target": [
{
"type": "Observation",
"params": "subject={ref}",
"link": [
{
"path": "performer",
"target": [
{
"type": "Practitioner"
}
]
}
]
}
]
},
{
"path": "generalPractitioner",
"target": [
{
"type": "Practitioner"
}
]
}
]
}
Request
GET /fhir/R4/Patient/patient123/$graph?graph=patient-with-observations
Response
{
"resourceType": "Bundle",
"type": "collection",
"entry": [
{
"resource": {
"resourceType": "Patient",
"id": "patient123",
"generalPractitioner": [
{
"reference": "Practitioner/dr-smith"
}
]
}
},
{
"resource": {
"resourceType": "Observation",
"id": "obs1",
"subject": {
"reference": "Patient/patient123"
},
"performer": [
{
"reference": "Practitioner/dr-jones"
}
]
}
},
{
"resource": {
"resourceType": "Practitioner",
"id": "dr-smith"
}
},
{
"resource": {
"resourceType": "Practitioner",
"id": "dr-jones"
}
}
]
}
Behavior
- Starting Resource: Reads the resource specified in the URL
- Link Traversal: Recursively follows all links defined in the GraphDefinition
- Deduplication: Removes duplicate resources from the result
- Caching: Caches resources during traversal to avoid redundant reads
- Canonical Resolution: Supports resolving canonical URLs to resources
Safety Limits
- Maximum Resources: 1000 resources per request
- Maximum Depth: 5 levels of nested links
- Search Cardinality: Respects the
maxfield in links (defaults to 20, max 5000)
Link Path Expressions
FHIRPath expressions can target:
- Reference fields:
subject,performer,author - Canonical fields:
instantiatesCanonical,profile
For canonical fields, the operation searches for resources with matching url values.
Search Parameter Links
Search links must include {ref} in the params string:
{
"type": "Observation",
"params": "subject={ref}&status=final"
}
Multiple search parameters can be combined with &.
Error Responses
| Status Code | Description |
|---|---|
400 Bad Request | Missing graph parameter |
400 Bad Request | Missing or incorrect start type in GraphDefinition |
400 Bad Request | Invalid link configuration |
400 Bad Request | Link target params missing {ref} |
404 Not Found | GraphDefinition not found |
404 Not Found | Starting resource not found |
Example GraphDefinitions
Patient Summary with Related Resources
{
"name": "patient-summary",
"start": "Patient",
"link": [
{
"target": [
{ "type": "Condition", "params": "subject={ref}" },
{ "type": "MedicationRequest", "params": "subject={ref}" },
{ "type": "AllergyIntolerance", "params": "patient={ref}" }
]
}
]
}
Care Team
{
"name": "care-team-graph",
"start": "CareTeam",
"link": [
{
"path": "participant.member",
"target": [
{ "type": "Practitioner" },
{ "type": "Organization" }
]
},
{
"path": "subject",
"target": [
{ "type": "Patient" }
]
}
]
}