API Queries
The Fast Healthcare Interoperability Resources (FHIR) specification describes an API used to query resources in a FHIR server database. Throughout this documentation set, Opala will demonstrate FHIR search syntax in example API calls with the [baseurl] placeholder used to represent the FHIR server URL.
Queries can be made against a specific resource type, a specified compartment 
, or all resources in the FHIR server database. The simplest way to execute a search in FHIR is to use a GET request to retrieve data from the FHIR database. At this time, Opala only allows GET requests to be run against its databases.
For example, if you want to retrieve all Patient resources in the database, you could use this request:
GET https://[baseurl]/Patient
If the query is successful, you'll receive a FHIR Bundle resource containing the resource instance(s) returned from the search. If the query fails, you'll find the error details in an OperationOutcome response like the following:
Note: For full details about the search interaction, see the FHIR Release 4 specification, section 3.2.1 Search
Query Process
Using queries to find and retrieve data is the core functionality of an API. Opala uses FHIR® search queries as specified in CARIN for Blue Button®. The search functionality in FHIR uses a simple RESTful syntax that enables you to construct both simple and complex queries to locate and retrieve data easily and consistently.
The mechanics of a FHIR search query are simple:
- The client requests data using the following HTTP syntax:
GET [baseUrl]/[resourceType]?[optional parameters]
- The server then returns a FHIR Bundle resource, which is a container resource enclosing the matching search results.
Use the search interaction to retrieve resources from the resource repository. The following summarizes the default support for search interactions.
The Opala FHIR server has the following limitations:
- Searching across multiple resource types is not supported.
For example GET [baseurl]?_id=[id] is not supported.
- You cannot perform a search on all resource types within a compartment.
For example, you cannot search for [baseurl]/Patient/10000001/?_id=008.
- Searches within the context of a compartment must specify a resource type in that compartment.
For example, you can use [baseurl]/Patient/100000001/Observation to return all Observations in the specific patient’s compartment or [baseurl]/Patient/100000001/Observation?status=final to search for a subset of Observations within the compartment.
- To return all patients in the system, use
[baseurl]/Patient/? or [baseurl]/Patient/?everything.
- To return everything about a specific Patient resource, use
[baseurl]/Patient/[patientid]/? or [baseurl]/Patient/[patientid]?everything.
FHIR searches are based on defined search parameters. For a list of defined resource types, check the FHIR specification: at the bottom of every ResourceType page there is a list of search parameters defined for that ResourceType. You can also look here for a complete list of all defined search parameters.
Note: Because FHIR's RESTful interface uses standard HTTP requests, you can make GET requests by pasting a URL like https://hapi.fhir.org/baseR4/Patient/592486 into your browser's address bar. Omit the GET when using your browser, since loading web pages uses GET by default.
Resources and Searches
Each FHIR resource contains data as a set of elements. Search parameters work to query these elements and if a positive match is found between the request's search parameters and the corresponding resource instance's element data, the FHIR server returns a bundle containing the resource instance(s) whose elements satisfied the search criteria.
See Resource Bundle (2.36) for more information about bundles.
Search Parameters
The following parameters apply to all resources:
_content |
_filter |
_has |
_id |
_in |
_language |
_lastUpdated |
_list |
_profile |
_query |
_security |
_source |
_tag |
_text |
_type |
You can also see the current support for search parameters in Opala's Capability Statement with the following request:
GET https://[baseurl]/metadata
Composite Search Parameters
Composite search parameters enable joining multiple elements into distinct single values with a $. This is not the same as doing a simple intersection. The intersection rules apply at the resource level; for example, an Observation with multiple component repetitions may match because one repetition has a desired code and a different repetition matches a value filter. The composite parameter approach works in this context because it allows searches based on a tuples of values. For example:
GET [baseurl]/Observation?code-value-quantity=code$loinc|12907-2,value$ge150|http://unitsofmeasure.org|mmol/L
This query returns Observation records with a LOINC code of "12907-2" (Sodium [Moles/volume] in Red Blood Cells) AND a value greater than "150 mmol/L".
Modifiers
Modifiers enable you to qualify search parameters with additional conditions. Modifiers can be used to change the meaning of a search parameter while leaving the element mappings intact.
Use search modifiers in search requests by appending the modifier as a suffix to the search parameter name, using the syntax: [name]:[modifier], such as birthdate:missing. Note that only a single modifier is allowed on a single search parameter.
Support for modifiers is applied per search parameter; however, modifiers are generally defined according to search parameter type. For example, the :exact modifier has meaning when applied to string-type search parameters, but has no meaning and cannot be used with token-type search parameters.
The following parameters are available:
:above (reference, token, uri ) Tests whether the value in a resource is or subsumes the supplied parameter value (is-a, or hierarchical relationships).
:below (reference, token, uri ) Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships).
:code-text TU (reference, token ) Tests whether the textual display value in a resource (e.g., CodeableConcept.text, Coding.display, or Reference.display) matches the supplied parameter value.
:contains (string, uri ) Tests whether the value in a resource includes the supplied parameter value anywhere within the field being searched.
:exact (string ) Tests whether the value in a resource exactly matches the supplied parameter value (the entire string, including casing and accents).
:identifier (reference ) Tests whether the Reference.identifier in a resource (rather than the Reference.reference) matches the supplied parameter value.
:in (token ) Tests whether the value in a resource is a member of the supplied parameter ValueSet.
:iterate n/a (not allowed anywhere by default ) The search parameter indicates an inclusion directive (_include, _revinclude) that is applied to an included resource instead of the matching resource.
:missing (date, number, quantity, reference, string, token, uri ) 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).
:not (token ) Tests whether the value in a resource does not match the specified parameter value. This includes resources that have no value for the parameter.
:not-in (reference TU, token ) Tests whether the value in a resource is not a member of the supplied parameter ValueSet.
:of-type (token [only Identifier]) Tests whether the Identifier value in a resource matches the supplied parameter value.
:text (reference TU, token ) Tests whether the textual value in a resource (e.g., CodeableConcept.text, Coding.display, Identifier.type.text, or Reference.display) matches the supplied parameter value using basic string matching (begins with or is, case-insensitive).
:text (string ) The search parameter value should be processed as input to a search with advanced text handling.
:text-advanced TU (reference, token ) Tests whether the value in a resource matches the supplied parameter value using advanced text handling that searches text associated with the code/value - e.g., CodeableConcept.text, Coding.display, or Identifier.type.text.
[type] (reference ) Tests whether the value in a resource points to a resource of the supplied parameter type. Usage: A concrete ResourceType is specified as the modifier (e.g., not the literal :[type], but a value such as :Patient).
Prefix Codes
For search parameters that have a specific order (numbers, dates, and quantities), you can use a prefix before the parameter value to refine the search criteria. FOr example, Patient?_lastUpdated=gt2022-08-01 where the prefix .gt means "greater than".
Below is a list of prefix codes.
eq |
ne |
gt |
lt |
ge |
le |
sa |
eb |
ap |
Note: For full details about the prefix codes, see Prefixes
Search Result Parameters
FHIR specifies a set of search result parameters to help manage the information returned from a search. Below is a list of FHIR search result parameters.
_elements |
_count |
_include |
_revinclude |
_summary |
_total |
_sort |
_contained |
_containedType |
_score |
By default, _sort arranges records in ascending order; however, you can use the prefix - to sort in descending order. The FHIR service only enables you to sort by a single field at any one time.
Note: For full details about search result parameters, see Search Responses
Chained and Reverse Chained Searches
A chained search enables you to perform targeted queries for resources. These queries contain a reference to another resource in the query. For example, if you want to find the orders for medications for Jane Gold, use:
GET [baseurl]/MedicationRequest?subject:Patient.name=Jane Gold
The . in the request above points the path of the chained search to the target parameter name.
Similarly, you can do a reverse chained search with the _has parameter. This search enables you to retrieve resource instances by specifying criteria on different resources that reference the resource instances of interest. For example, if you want to find all Patient resources that are referenced by an Observation with a specific code:
GET [baseurl]/Patient?_has:Observation:patient:code=819495
Additional Resources
