Skip to content

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.

Parameters can be encoded in the URL in case of a search by GET method:

GET [base]/[type]?name=value&...{&_format=[mime-type]}}
or as an application/x-www-form-urlencoded submission for a POST:

POST  [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}

The response to any search operation is always a list of resources in a Bundle or an Operation Outcome.

Supported global 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 unsupported
_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

Note that if units of measures are not specified for quanitity search parameter type in a search request, the search processor performs a search based on the canonical units. For example:

{{host}}/fhir/Observation?code-value-quantity=10000-10$ge5.4
turnts to
{{host}}/fhir/Observation?code-value-quantity=10000-10$ge5.4|http://unitsofmeasure.org|g

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 - - -

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:

  1. The name of the source resource from which the join comes
  2. The name of the search parameter which must be of type reference
  3. (Optional) A specific of type of target resource (for when the search parameter refers to multiple possible target types)

Search request examples

https://test.fhir.edenlab.tech/fhir/Observation?_include=Observation:patient:Patient
https://test.fhir.edenlab.tech/fhir/Patient?_id=123&_revinclude=Observation:patient

Requests for [_include|_revinclude]=* (asterisk) are supported by Kodjin. * will include or revinclude all possible references for requested resource.

Search request examples with *

https://test.fhir.edenlab.tech/fhir/Observation?_id=123&_include=*
https://test.fhir.edenlab.tech/fhir/Patient?_id=123&_revinclude=*

Pagination

Search in Kodjin supports two types of pagination:

  • offset pagination (with skip or page parameters)
  • cursor pagination

Example - Requests with different pagination types

curl --location --request GET 'https://test.fhir.edenlab.tech/fhir/Coverage' \
--header 'Prefer: pagination=offset-skip'
curl --location --request GET 'https://test.fhir.edenlab.tech/fhir/Coverage' \
--header 'Prefer: pagination=offset-page'
curl --location --request GET 'https://test.fhir.edenlab.tech/fhir/Coverage?_count=3' \
--header 'Prefer: pagination=cursor'

Cursor is the default pagination type.

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"
            }
        }
```