If there were a popularity contest among all 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 confidential data, like PHI, in the request’s URL.
When you initiate a FHIR® query, you can narrow down possible results with search parameters. This helps you find the specific data you’re looking for.
Some search parameters 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 might be more resource-specific. However, Redox passes any search parameters you include for any FHIR® query.
One way to hone your search is to use relevant prefixes or modifiers on your search parameters.
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 might 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 might want to search for an Appointment resource that doesn’t have a pending 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, 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 might or might 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. |
You can also combine parameters to use chained or composite parameters.
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 | Includes any resources that are referenced in the resource identified by the search. Including referenced resources in the response bundle means you don’t have to repeatedly retrieve related resources. |
_revinclude | Includes any resources that reference the resource identified by the search. This is the reverse of _include. |
_count | Specifies the maximum number of results to return. Note that for data on demand, the maximum count is 1000. |
When the search parameter(s) match a path found in one or more resources, those resources are returned in a bundle. The search criteria defined in the query parameters might 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 might need to examine the resource to determine which path contains the match.
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 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 contains 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.
You can see how FHIR® pagination links resolve to Redox-centric links in log inspector. Learn about FHIR® pagination resolvers.