FHIR Search Operations
A search operation allows to fetch resources, filtering them by supplied parameters. The parameters are a series of name=[value] pairs. The syntax for Read and Search is described here.
Search parameters can be encoded in the URL in case of a search by GET method:
or as an application/x-www-form-urlencoded submission for a POST:The response to any search operation is always a list of resources in a Bundle or an Operation Outcome.
The order of search parameters in Kodjin search matters. It's recommended to use more specific search parameters first. For example, searching for patients by gender may return a large amount of data, while searching by identifier will return fewer results. Therefore, when using multiple search parameters in one request, it's better to place the more specific identifier before gender. Searching in reverse order will result in a longer search operation for Kodjin.
Search by several search parameters
Supported global FHIR search parameters
The following parameters apply to all resources:
| Parameters for all resources | Status |
|---|---|
| _id | supported |
| _lastUpdated | supported |
| _tag | supported |
| _profile | supported |
| _security | supported |
| _source | supported |
| _text | unsupported |
| _content | unsupported |
| _list | unsupported |
| _has | supported |
| _type | unsupported |
Supported search parameter types
Each search parameter is defined by a type that specifies how the search parameter behaves. These are the defined parameter types:
| Search Parameter Type | Status |
|---|---|
| number | supported |
| date | supported |
| string | supported |
| token | supported |
| reference | supported |
| composite | supported |
| quantity | supported |
| uri | supported |
Support of special search parameter types
| Search Parameter Type | Status |
|---|---|
| _filter | unsupported |
| near on Location | supported |
Support of modifiers/prefixes for number/date search parameter type
| Search Parameter Type/Modifier or Prefix | missing | gt | lt | ge | le | sa | eb | ne |
|---|---|---|---|---|---|---|---|---|
| number | + | + | + | + | + | + | + | + |
| date | + | + | + | + | + | + | + | + |
| dateTime | + | + | + | + | + | + | + | + |
| instant | + | + | + | + | + | + | + | + |
| Period | + | + | + | + | + | + | + | + |
| Timing | - | - | - | - | - | - | - | - |
Support of modifiers/prefixes for string search parameter type
| Search Parameter Type/Modifier or Prefix | missing | exact | contains |
|---|---|---|---|
| string | + | + | + |
| string.Address | - | - | - |
| string.HumanName | + | + | + |
Support of modifiers/prefixes for token search parameter type
| Search Parameter Type/Modifier or Prefix | missing | text | not | above | below | in | not-in | of-type |
|---|---|---|---|---|---|---|---|---|
| token | + | + | + | - | - | - | - | + |
Support of modifiers/prefixes for reference search parameter type
| Search Parameter Type/Modifier or Prefix | missing | type | identifier | above | below |
|---|---|---|---|---|---|
| reference | + | + | + | - | - |
Support of modifiers/prefixes for uri search parameter type
| Search Parameter Type/Modifier or Prefix | missing | above | below |
|---|---|---|---|
| uri | + | - | - |
Dynamic search
Search in the Kodjin FHIR Server is dynamic. In order to enable search on some new parameter, the SearchParameter resource must be added via API. The Elasticsearch index should also be configured.
Including other resources in result
To include additional resources to searchset response _include and _revinclude parameters could be used.
The parameter _include should be used to add referenced resources by requested resource. For example, managingOrganization should be added to searchset response for a Patient.
The parameter _revinclude should be used to add resources that has as a reference requested resource. For example, Encounter should be added while searching a Patient.
Parameter values for both _include and _revinclude have three parts, separated by a : character:
- The name of the source resource from which the join comes
- The name of the search parameter which must be of type reference
- (Optional) A specific of type of target resource (for when the search parameter refers to multiple possible target types)
Search request examples
Try search with _include with our Kodjin FHIR Server Postman Collection
Requests for [_include|_revinclude]=* (asterisk) are supported by Kodjin. * will include or revinclude all possible references for requested resource.
Search request examples with *
Try search with _include with our our Kodjin FHIR Server Postman Collection
Both _include and _revinclude could be iterated:
Search Condition by Patient's name
Chained parameters
To perform search on the referenced resource, chained parameters should be used. Search on chained parameters are done with the help of .. For Example:
In case there are several base resources in SerachParameter, resource type could be specified in search request:
Search with chained parameters
All chained parameters in request are applied independently. For example,
Search with chained parameters
This request will return patient with id 1234 and all patients with name Brendon
Reverse Chaining
Reverse Chaining is an opposite operation to chaining - it perform search on resources that referenced the search resource. For example:
Search with reverese chaining
This search request will retrieve all Patients that have Conditions with code 15931261000119105
The _has parameter can be chained:
Search with reverese chaining
Pagination
Search in Kodjin supports two types of pagination:
- offset pagination (with skip or page parameters)
- cursor pagination
Example - Requests with different pagination types
Cursor is the default pagination type.
There are some special custom SearchParameters that are used for pagination. They are returned by Kodjin in the link element of the searchset Bundle.
| Name | Description |
|---|---|
_skip |
is used for offset-skip pagination and shows the number of resources that should be skipped to see the next page |
_page |
is used for offset-page pagination and shows the number of pages that should be skipped to see the next one |
Sorting
Kodjin performs sorting by only one SearchParameter per one search request. Sorting can be done by any standard or custom SearchParameter. Composed type has thier own custom sorting order:
| Name | sorting order |
|---|---|
| Token | system, code |
| Reference | type, id, url, system, code |
| String | string |
| URI | url, version |
| Date/DateTime | date, period |
Handling errors
Kodjin will not return an error if a parameter refers to a non-existent resource, e.g. GET [base]/Observation?subject=101, where "101" does not exist, or to an unknown code, e.g. GET [base]/Observation?code=loinc|1234-1, where the LOINC code "1234-1" is not known to the server. The response will be an empty search bundle.
Kodjin will return an error if it receives parameters from the client that it does not recognize, or parameters it recognizes but does not support (either in general, or for a specific search).
By default, the Kodjin FHIR Server ignores unknown or unsupported parameters for the following reasons: various HTTP stacks and proxies may add parameters that aren't under the control of the client.
Clients can specify how the server should behave by using the prefer header: -Prefer: handling=strict: Client requests that the server return an error for any unknown or unsupported parameter -Prefer: handling=lenient: Client requests that the server ignore any unknown or unsupported parameter.
Example - OperationOutcome
```
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "not-found",
"details": {
"text": "Unknown query param: test"
}
}
]
}
```
Note that search on strings greater than 8000 symbols is not supported. If you post a resource containing such a string, you will get a warning, as demonstrated below.
```
{
"severity": "warning",
"code": "value",
"expression": [
"Patient.name[0].text"
],
"details": {
"text": "Search on strings greater than 8000 symbols is not supported"
}
}
```