Write and run queries

1.1 How to write a query

The FHIR Viewer accepts relative FHIR REST search queries. You enter the query path directly into the query bar, starting with a forward slash (/).

Basic example

/Patient?_count=10

This query asks the connected FHIR server to return up to 10 Patient resources.

General query structure

/{ResourceType}?{parameter1}={value1}&{parameter2}={value2}...

• ResourceType: The type of FHIR resource you are querying (for example, Patient, Specimen, Condition, Observation, DocumentReference). • ? (question mark): Separates the resource path from the search parameters. • Search parameters: Key–value pairs that filter, limit, or modify the search results. Multiple parameters are separated using &.

What are FHIR search parameters? Search parameters are server‑defined fields that allow you to filter and control which resources are returned. They correspond to elements defined in the FHIR specification or supported by a specific server’s configuration. Common parameter categories include:

Basic example

/Patient?_count=10

This query asks the connected FHIR server to return up to 10 Patient resources.

General query structure

/{ResourceType}?{parameter1}={value1}&{parameter2}={value2}...

• ResourceType: The type of FHIR resource you are querying (for example, Patient, Specimen, Condition, Observation, DocumentReference). • ? (question mark): Separates the resource path from the search parameters. • Search parameters: Key–value pairs that filter, limit, or modify the search results. Multiple parameters are separated using &.

What are FHIR search parameters? Search parameters are server‑defined fields that allow you to filter and control which resources are returned. They correspond to elements defined in the FHIR specification or supported by a specific server’s configuration. Common parameter categories include:

Suggested queries

Suggested queries are templates to help you get started. Selecting one fills the query bar; you can edit it before running.

• /Patient?_count=25 • /Patient?_count=25&_revinclude=Observation:subject • /Observation?_count=25&status=final&_sort=-_lastUpdated • /Condition?_count=25&code=MONDO:0008608 • /Specimen?_count=25&subject=Patient/pt-0001k4k1
• /DocumentReference?_count=25

1.2 Simple queries: common starting points

Enter a relative FHIR query path (starting with /). Examples: • /Patient?_count=10 • /ResearchStudy?_count=25 • /ResearchSubject?_count=25 • /Specimen?_count=25 • /DocumentReference?_count=25

Tip: Common query knobs • _count controls page size (server may cap it). • _sort may be supported (e.g., _sort=-_lastUpdated). • Use code=, subject=, patient=, or _tag= when supported by the server.

Filtering patterns you will use often

Patient-anchored queries

• Condition for a patient: /Condition?subject=Patient/<PATIENT_ID>&_count=25 • Specimens for a patient: /Specimen?subject=Patient/<PATIENT_ID>&_count=25 • DocumentReferences for a patient: /DocumentReference?subject=Patient/<PATIENT_ID>&_count=25

Study-tagged queries

• ResearchSubjects for a study: /ResearchSubject?_tag=<STUDY_TAG>&_count=25 • Patients in a study (server-dependent): /Patient?_tag=<STUDY_TAG>&_count=25 • Files in a study (server-dependent): /DocumentReference?_tag=<STUDY_TAG>&_count=25

1.3 Advanced queries: _include and _revinclude

FHIR supports bringing related resources into the same response using _include and _revinclude. Support varies by server and resource. Start small and expand carefully. _include examples • / DocumentReference?_count=10&_include=DocumentReference:patient • /Specimen?_count=10&_include=Specimen:subject

_revinclude examples • /Patient?_count=10&_revinclude=Observation:subject • /Patient?_count=10&_revinclude=Condition:subject

Tip: Performance note for include/revinclude • These can return large payloads. Start with low _count. • If the response is slow, narrow the base query first (e.g., by tag or specific id). • _revinclude queries often return much larger result sets than _include, and many servers impose limits that may truncate or restrict responses.

1.4 Errors and OperationOutcome

Not all FHIR servers support the same search parameters or behaviors. A query that works on one server may fail or return different results on another. Invalid or unsupported parameters typically result in a server‑returned error (for example, an OperationOutcome), which is displayed directly in the viewer.