Search Techniques: AND, OR, modifiers, prefixes
In this lesson we will explore FHIR’s advanced search capabilities including,
- Limiting results using
_count
- Counting results using
_total
- Combining search parameters using AND and OR logic
- Refining matching process with modifiers to make exact/partial matches
- Controlling numeric and date comparisons with greater-than and less-than prefixes
Determine result size with _total
and _count
Here are two handy FHIR search attributes, _total
and _count
.
_total
The bundle returned will contain a total
element with the number of matching resources in the server, not just the number of resources returned in the response.
The parameter _total
can have one of three values,
- none: Total count will not be populated
- estimate: Provides a rough estimate of the number of matching resources
- accurate: Provides an exact total of the number of matching resources
_count
This parameter allows you to control how many resources are returned in a single page of results. By default, many servers only return 20 resources even if hundreds of matches exist for the query. Setting this parameter will override that default.
Combine search parameters with AND/OR
To return only resources that meet multiple criteria, AND &
is used.
For example,
GET /Patient?name=John&name=Doe
This would return resources in which Name contains John AND Doe.
To return resources that meet any one condition, OR ,
is used.
For example,
GET /Patient?name=John,Doe
This would return resources that contain John OR Doe, e.g. John Doe, John Cena and Jane Doe.
Use modifiers for string searches
String searches in FHIR are by default case-insensitive and match substrings. Using :exact
returns results that match the entire parameter provided.
For example,
GET /Patient?name:exact=John
This would not include patients that have the name JOHN or john.
Use prefixes for numbers, dates and quantities
Searching in FHIR also supports prefixes to compare numbers, dates and quantities. Common prefixes include,
gt
: greater thanlt
: less thange
: greater than or equal tole
: less than or equal to
Below are some examples of how to use them.
To filter patients born after 1997,
GET /Patient?birthdate=gt1997-01-01
Combining different search techniques
When using these search techniques together, modifiers, prefixes and comparisons with multiple values, you can build powerful queries. Here is an example,
GET /Patient?name=John,Jane&family:exact=Doe&birthdate=gt1990-01-01
The above query will return Patient resources whose,
- given name is John or Jane
- family name is exactly Doe
- and born after 1990
In summary
Advanced search parameters makes FHIR queries flexible and powerful. In this lesson we learnt how to control result size, combine conditions, refine string searches, filter number and date searches and combine different techniques.