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 than
• lt: less than
• ge: greater than or equal to
• le: 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 make FHIR queries flexible and powerful. In this lesson we learned how to control result size, combine conditions, refine string searches, filter number and date searches, and combine different techniques.