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.
Supported search parameters for different sites
Read what HL7 says about FHIR® search. In this article, we dive into common parameters for search interactions.
However, 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 or support for a successful search.
You may see search parameters that can be easily applied to all FHIR® resources, like this one:
Search parameter | Notes |
|---|
_id | The logical ID of the resource, which can be used when specifying the resource type. |
Other search parameters may be more resource-specific. However, Redox passes any search parameters you include for any FHIR® query. Below, we break down the different types of common search parameters and how to use them:
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. |
Error codes
Since Redox passes any search parameters included in your query, any errors you receive about search parameters are from the destination system. Work with your connection to understand which search parameters they support or expect.
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.
