Track 1 — FHIR Fundamentals

Search

FHIR Search is how you retrieve multiple resources from a server. You construct a query using URL parameters. The server returns a Bundle of type searchset containing every matching resource.

How search works

A FHIR search is a GET request to a resource type endpoint with query parameters. Every resource type exposes a defined set of search parameters — Patient supports name, birthdate, gender, identifier. Observation supports patient, code, date, category.

The server's CapabilityStatement lists which search parameters it supports. Search parameters not listed in the CapabilityStatement are not guaranteed to work.

Search examples

# All patients named Horváth

GET /fhir/Patient?name=Horváth

# Female patients born after 1980

GET /fhir/Patient?gender=female&birthdate=ge1980

# Patient by national identifier

GET /fhir/Patient?identifier=http://example.sk/pid|7903121234

# Blood glucose results for one patient

GET /fhir/Observation?patient=patient-001&code=http://loinc.org|2339-0

# All vital signs for one patient, newest first

GET /fhir/Observation?patient=patient-001&category=vital-signs&_sort=-date

# Active conditions for one patient

GET /fhir/Condition?patient=patient-001&clinical-status=active

Parameter types

Each search parameter has a type that determines how it is matched. The type is defined in the CapabilityStatement.

stringname=Horváth

Partial match by default: matches at the beginning of any name part. name=Jan matches 'Jana', 'Ján', 'Jánošík'. Add :exact for exact match, :contains for substring.

tokencode=http://loinc.org|2339-0

Exact match on code value, optionally scoped to a system. Format: system|code. If system is omitted, any system is accepted. Used for coded values: gender, status, code, category, identifier.

datebirthdate=ge1979-01-01

Date comparison with optional prefix: eq (equal), ne (not equal), lt (less than), gt (greater than), le (less than or equal), ge (greater than or equal). Can match year, year-month, or full date.

referencepatient=Patient/patient-001

Search by resource reference. Can be a relative reference (Patient/123), absolute URL, or just the id (123). Used in Observation, Condition, Encounter to link back to a Patient.

quantityvalue-quantity=7.8||mmol/L

Numeric value with optional comparator and unit. Format: prefix|value|system|code. Used for Observation value-quantity search.

Common control parameters

_count_count=20

Maximum results per page. Server may return fewer.

_sort_sort=-date

Sort by field. Prefix - for descending.

_include_include=Observation:patient

Include referenced resources in the result. Returns matching Observations AND the referenced Patients.

_summary_summary=true

Return only summary elements — reduces payload for list views.

_total_total=accurate

Ask the server to include total count in the searchset Bundle.

The searchset Bundle

A search response is always a Bundle of type searchset. It contains the matching resources in entry[] and metadata in the Bundle header.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "link": [
    { "relation": "self", "url": "http://localhost:8080/fhir/Patient?name=Horváth" }
  ],
  "entry": [
    {
      "fullUrl": "http://localhost:8080/fhir/Patient/1005",
      "resource": {
        "resourceType": "Patient",
        "id": "1005",
        ...
      },
      "search": { "mode": "match" }
    }
  ]
}

search.mode can be match (matched the query), include (included via _include), or outcome (OperationOutcome for a warning).