If there were a popularity contest among all the available FHIR® interactions and operations, the clear winner would be a search interaction. Learn the difference between interactions and operations.
In other words, search is the most widely supported and versatile type of interaction, meaning that you can search for most resources.
Redox supports the POST method for searching. We use POST because it allows for encoded search parameters in the request body instead of the search URL (like a GET method uses).
HL7 recommends the POST method because it mitigates the risk of leaking sensitive information, like PHI, in the request’s URL.
To perform a search, you can populate a request with relevant parameters, using prefixes or modifiers to hone your search. You can also combine parameters to use chained or composite parameters.
When the search parameter matches a path found in one or more resources, those resources are returned as a bundle in a response. Parameters can match one element or many elements in multiple places, as well as derived values. Whenever there’s matching content in any path, the whole resource is returned. You may need to examine the resource to determine which path contains the match.
HL7 docs and search requirements
Read what HL7 says about FHIR® search. Below, we dive into what Redox supports for search interactions.
Keep in mind that we list what Redox supports, but not necessarily what your connection requires. You should expect variation between sites as to what they require for FHIR® searches. Work with your connection to find out which search parameters they require for a successful search.
Some search parameters apply to all resources. Redox supports these parameters for all resources:
Search parameter | Notes |
|---|
_id | The logical id of the resource, which can be used when specifying the resource type. |
The rest are resource-specific parameters.
You can use these to specify your search parameters further:
Prefixes
Modifiers
Chained parameters
Composite parameters
Result parameters
Error codes
If you try to use unsupported modifiers or prefixes, Redox returns an HTTP 4XX code for an invalid request. The text in the response explains that there’s an unknown parameter in the request.
Redox supports some prefixes for ordered search parameters. You can use these to locate resources with (or without) values containing specific numbers, dates, or quantities. For example, you may want to search for an Appointment resource with a date range between January 1 and February 1.
Search parameter | Notes |
|---|
_gt | Greater than the provided value. |
_ge | Greater than or equal to the provided value. |
_lt | Less than the provided value. |
_le | Less than or equal to the provided value. |
_ne | Not equal to the provided value. |
Redox supports some modifiers for tokens (i.e., strings, coding, codeableConcept, identifier, uri), which are suffixes for the parameters. You can use these to locate resources with (or without) specific values. For example, you may want to search for an Appointment resource with a confirmed status.
Search parameter | Notes |
|---|
not | Returns all resources that don’t have a matching item. If you search for a resource with the example above (confirmed appointments), you'd use status:not=pending as a modifier. You receive back any resources with unmatching or unpopulated status fields. |
missing | Set this to true or false to return resources that may or may not have this parameter. If true, you want a resource that doesn’t have the parameter; if false, you want a resource with this parameter populated. |
Redox supports some chained parameters, which are multiple reference parameters appended with a period and the name of the next parameter. For example, you could use patient.identifier together instead of patient and identifier separately.
Chained parameters allow you to search for a specific resource type with a parameter used in a referenced resource (e.g., subject.name for searching for a Diagnostic Report resource, which typically includes a reference to the patient resource for the name).
Not all parameters support chaining. The identifier parameter can usually be chained while others may be chainable on a case-by-case basis. Check our reference docs to see what chained parameters are supported for a given resource type.
Redox supports a limited set of composite search parameters, which are specially-defined parameters that allow you to combine multiple values together. They’re mostly used with parameter chaining to locate multiple values within a resource.
Let's say you want to search for Appointment resources. An Appointment resource may have one or more reference to participants.
Appointment resources to search So, you may try searching with these chained parameters: participant.name=WesternHealth and participant.physical-type=si (remember that si stands for site). You'd get back multiple matches, because a search with chained parameters can return results that match either parameter.
But this kind of search could return false positives if one of those parameters matches a location. So, how do you avoid this problem? When available, you can use these composite parameters to make sure that both the name and physical type reference the same chained location: participant.name-physical-type=WesternHealth$si. With this composite parameter search, matches would be anything where both of those are true.
Composite parameter search To control how matching results are returned, you can use the following parameters:
Search parameter | Notes |
|---|
_sort | Sorts results by the specified parameter. For example, you can sort results by date or status. |
_elements | Specifies which elements of a given resource to return to hone in on particular data. This is a comma-separated list, e.g., Patient_elements=identifier,active,link. |
_include | When a search identifies a given resource, that resource likely has references contained within it. Using _include returns the referenced resources as well. You can use this so that you don’t have to repeatedly retrieve related resources. |
_revinclude | When a search identifies a given resource, that resource has likely been referenced by other resources. Using _revinclude returns the resources that contain references to the resource that the search identified. |
_count | Specifies the maximum number of results to return. Note that for data on demand, the maximum count is 1000. |
The response to your search contains a bundle of resources.
An empty result (i.e., a bundle with zero entries) means that there weren’t any resources that matched the search criteria.
If there’s an error of any kind, you receive an HTTP status code (4XX or 5XX). Then the response body is an OperationOutcome resource with an error description.
Some FHIR® searches may find more results than should reasonably be returned at one time. To avoid lengthy responses, FHIR® relies on pagination, which groups search results into pages. Learn more about FHIR® pagination.
The query response will contain a link array with links to pages that can be fetched using a GET or POST request against that URL. You can't use additional parameters with a pagination query.
Expiration date for pagination links
Pagination links expire after 30 minutes. If you attempt to use a pagination link after 30 minutes, it will return a 404. If this happens, you'll need to perform a new search.
You can see how FHIR® pagination links resolve to Redox-centric links in log inspector. Learn about FHIR® pagination resolvers.
