FHIR Search Parameter

Search parameters are categorized by data type, which dictates the comparison logic and expected input format:

• string: Partial, case-insensitive matching (e.g., name=john)
• token: Exact match on a code system and code pair (e.g., gender=male)
• date: Range queries on temporal values (e.g., birthdate=gt2020-01-01)
• quantity: Numeric comparisons with units (e.g., value-quantity=le5.4|mg)
• reference: Follows links between resources (e.g., subject=Patient/123)
• composite: Combines two parameters into a single logical pair

Clients refine search behavior using modifiers appended to the parameter name and prefixes on values:

• Modifiers: :exact forces case-sensitive string matching; :contains performs substring search; :text searches on the narrative display
• Prefixes: eq (equal), ne (not equal), gt (greater than), lt (less than), ge (greater or equal), le (less or equal), sa (starts after), eb (ends before)
• Chaining: The . notation traverses references, e.g., subject:Patient.name=Smith

Standard parameters control pagination and response formatting across all resource types:

• _count: Limits the number of results returned per page (e.g., _count=50)
• _include: Requests that referenced resources be returned inline (e.g., _include=Patient:organization)
• _revinclude: Reverse include, fetching resources that reference the matched set
• _sort: Orders results by a specified search parameter (e.g., _sort=-date for descending)
• _elements: Restricts the fields returned to a subset, reducing payload size
• _summary: Returns a pre-defined subset of data (true, text, data, count, false)

A compartment is a logical grouping of resources related to a specific context, enabling scoped queries:

• Patient compartment: Retrieves all resources linked to a specific patient (e.g., GET /Patient/123/Observation)
• Encounter compartment: Fetches resources associated with a single encounter
• Practitioner compartment: Returns resources tied to a specific provider
• Compartments simplify access control and reduce the need for complex chained queries

A SearchParameter resource formally defines a parameter's behavior:

• url: The canonical identifier for the parameter
• base: The resource types this parameter applies to (e.g., Patient, Observation)
• expression: A FHIRPath expression pointing to the element being indexed
• type: The parameter's data type (string, token, reference, etc.)
• target: For reference parameters, the allowed resource types that can be referenced
• xpath: Legacy XPath expression for backward compatibility with DSTU2

Advanced search patterns handle multi-value dependencies:

• Composite parameters: Combine two values that must be evaluated together, such as code-value-quantity for Observations where the code and value are logically paired
• _filter: A powerful alternative syntax using a formal grammar for complex boolean logic (e.g., name co "Smith" and birthdate gt 1990)
• _has: Reverse chaining that tests if a referencing resource matches criteria (e.g., _has:Observation:patient:code=1234-5)
• _list: Searches for resources that are members of a specific List resource