If there were a popularity contest among all the available FHIR® interactions and operations, the clear winner would be a search interaction. Read more about 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.
POST versus GET
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.
Search parameters
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.
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).
Chained parameters
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.
Chained parameter search
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 be returned. Note that for Data on Demand, the maximum count is 1000.
Responses
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.
FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.
