FHIR Search
Last updated
Was this helpful?
Last updated
Was this helpful?
Aidbox supports .
The FHIR Search API is the primary mechanism for finding FHIR resources by conditions.
A base search request is composed of a list of pairs <parameter>=<value>
:
For example, to search for a Patient resource with the name "John" and a birthdate of "1900-01-01", the request would look like this:
FHIR Search API supports various search features to help retrieve exactly the data you need. Here are some of the most commonly used capabilities.
Field Filtering
GET /fhir/Patient?name=John
Search for patients with name starting with "John"
Multiple Criteria
GET /fhir/Patient?name=John&gender=male
Search for male patients with name starting with "John" and "male" gender
OR Logic
GET /fhir/Patient?name=John,Jane
Search for patients with name starting with either "John" OR "Jane"
Sorting & Paging
GET /fhir/Patient?_sort=name&_page=2
Sort patients by name and get the second page of results
Include related resources
GET /fhir/Patient?_include=Patient:organization
Get patients and include their referenced organization resources
Reverse include
GET /fhir/Organization?_revinclude=Patient:organization
Get organizations and include all patients that reference them
Field selection
GET /fhir/Patient?_elements=name,birthDate
Return only name and birthDate fields for matching patients
Chaining
GET /fhir/Patient?organization.name=Mayo
Search for patients in organizations with name containing "Mayo"
Reverse Chaining
GET /fhir/Organization?_has:Patient:organization:name=John
Search for organizations that have patients with name containing "John"
Modifiers
GET /fhir/Patient?name:exact=John
Search for patients with name exactly matching "John"
Advanced filtering
GET /fhir/Patient?_filter=name eq 'John' or birthdate eq '1990-01-01'
Search for patients with name equal to "John" or birthdate equal to "1990-01-01". There's no other way to express this multiple search parameters OR logic in FHIR Search.
A total count of matching resources
The matched resources as entries
Links for pagination (first, previous, next, last pages)
Additional included/revincluded resources (if requested)
Example response:
Note: using the X-Original-Uri
header allows for complete overwrite of the content of the URL parameter. Aidbox will automatically add a page param to your link, or replace it if it exists. x-original-uri: https://example.com/fhir/Patient?page=4
will produce:
See also:
A SearchParameter is a FHIR resource that defines how to search for data within other FHIR resources. SearchParameter can be:
Resource-specific parameters (e.g. Patient.name
)
Common underscored parameters across all resources (_id
, _sort
, _count
, _page
, _elements
, etc.)
See also:
Each SearchParameter has a defined type, which determines how it behaves and what kind of values it accepts.
String
Plain text matching
name=smith
Token
Coded or identifier values
status=active
, code=123
Reference
Links to other resources
patient=Patient/123
Date
Date/time values and ranges
birthdate=2020
, date=ge2019-01
Number
Numeric values and ranges
age=55
, length=gt100
Quantity
Values with units
weight=100
Uri
URIs
url=http://example.com
Composite
Combines multiple values
component-code-value-quantity=code$value
Special
Implementation specific
_filter
, _text
, _content
It is important to understand the type of SearchParameter because there are differences in how they are processed. For example, different modifiers are supported, some types support prefixes, some don't, etc.
Modifiers change the behavior of a search parameter to support more specific queries. For example, searching for patients with the name exactly "Smith", rather than the default partial matching:
List of supported modifiers:
:missing
all
Tests whether the value in a resource is present (when the supplied parameter value is true) or absent (when the supplied parameter value is false)
gender:missing=true
:text
all
Tests whether the textual value in a resource matches the supplied parameter value using basic string matching (begins with or is, case-insensitive)
email:text=gmail.com
:exact
string
Exact string match
name:exact=Alex
:contains
string
Search for string containing value
name:contains=lex
:starts
string
Search for string starting with value
name:starts=Ale
:ends
string
Search for string ending with value
name:ends=lex
:in
token
Search within a ValueSet
code:in=/ValueSet/cardiac-conditions
:not
token
Negates the search value
gender:not=male
:of-type
token
Search for resource identifier
identifier:of-type=system
:i
token
Case-insensitive search
email:i=foo@bar.baz
:below
uri
Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships)
url:below=http://acme.org/fhir/
:not
uri, reference, token
Negates the search value
url:not=http://acme.org/fhir/
:identifier
reference
Search by identifier of referenced resource
subject:identifier=urn:oid:1.2.3.4
:btw
date
Search for dates between two values. Defined by Aidbox, not FHIR.
birthdate:btw=1980,1981
:iterate, :recurse
-
_include:iterate=Observation:has-member:Observation
When searching for resources, you can include referenced resources in the search results using the _include
parameter. This reduces the number of API calls needed to fetch related data.
For example, to search for patients and include their referenced practitioners:
The _revinclude
parameter does the opposite of _include
. It returns resources that reference the ones you're querying.
For example, to search for practitioners and include all patients who reference them:
See also:
Chaining allows you to search across references between resources. It’s useful when you need to filter by attributes of related resources.
There are two types of chaining:
Forward chaining: GET /fhir/Patient?general-practitioner:Practitioner.name=Oz
(get patients who have a general practitioner with the name "Oz")
Reverse chaining: GET /fhir/Practitioner?_has:Patient:general-practitioner.gender=male
(get practitioners that are referenced by patients with gender "male")
See also:
Sometimes FHIR Search API is not enough. For example, there's no way to search using a case-insensitive match without starts-with string type logic (combining token and string types), which is useful to search, say, for domains of emails.
Aidbox has custom APIs to search for resources, which can be used instead of FHIR Search API in corner cases:
It is also possible to use GraphQL to search for resources.
See also:
Search results are returned as a of type "searchset". The Bundle contains:
See also .
See
- use SQL to define where
and order-by
parts of SQL statements. Combines with other SearchParameters.
- use DSL to define search criteria. Does not combine with other SearchParameters.
- an easy way to search without using SearchParameters at all.