Search

Search API for FHIR resources

Aidbox provides a Search API for all stored resources. Aidbox Search API is a superset of the FHIR Search API.

There are two versions of API, which differ by the resources format:

  • search by /[resourceType] returns results in Aidbox Format

  • search by /fhir/[resourceType] returns data in FHIR Format

All data is stored and searched in Aidbox Format and converted on the fly to FHIR on FHIR endpoints!

A base search request is composed of the list of pairs param = value:

GET [base]/fhir/[resourceType]?param=value&param=value&...

Where param can be one of:

Simple search by patient name:

GET /fhir/Patient?name=Max&_elements=id, birthDAte

Special Parameters

ParameterTypeDescription

FHIR

Full text search by resource content

FHIR+

Include or exclude specific resource elements

Get query execution plan

_filter

FHIR

Perform an advanced search

FHIR

Reverse chaining

FHIR

Search and sort by resource id

ILIKE search by resource content

FHIR

Include referenced resources into result

FHIR

Search and sort by resource last modification date

FHIR

Search resources included into specific List

FHIR

Search by resource profile

Change result format

FHIR

Include into result resources, which reference searched resources

_security

FHIR

FHIR

Sort search results

FHIR

Include only summary elements

_tag

FHIR

FHIR

Full text search by resource narrative

FHIR

Turn on/off total count

Aidbox

Include into result resources (compact way compared to _include and _revinclude)

Search Parameters

Search is defined in terms of "search parameters". SearchParameter is a meta-resource, which describes which part of the resource it is and how you can make it searchable.

Search parameter can be one of the following types:

TypeSupportDescription

Search parameter SHALL be a number (a whole number, or a decimal).

Search parameter is on a date/time. The date format is the standard XML format, though other formats may be supported.

Search parameter is a simple string, like a name part. Search is case-insensitive and accent-insensitive. May match just the start of a string. String parameters may contain spaces.

Search parameter on a coded element or identifier. May be used to search through the text, displayname, code and code/codesystem (for codes) and label, system and key (for identifier). Its value is either a string or a pair of namespace and value, separated by a "|", depending on the modifier used.

A reference to another resource.

A composite search parameter that combines a search on two values together.

A search parameter that searches on a quantity.

A search parameter that searches on a URI (RFC 3986).

Depending on the value type, different modifiers can be applied.

Supported modifiers

ModifierTypesDescription

missing

all

Tests whether the value in a resource is present (when the supplied parameter value is true) or absent (when the supplied parameter value is false)

text

string, token, reference, uri

Tests whether the textual value in a resource matches the supplied parameter value using basic string matching (begins with or is, case-insensitive)

below

uri

Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships)

contains

string

Case insensitive, partial match at start or end

ends, ew

string

Case insensitive, partial match at end

exact

string

No partial matches, case sensitive

starts, sw

string

Case insensitive, partial match at start

btw

date

Search between two dates

identifier

reference

Tests whether the Reference.identifier in a resource (rather than the Reference.reference) matches the supplied parameter value

not

reference, token, uri

Reverses the code matching: returns all resources that do not have a matching item.

i

token

Case insensitive, exact match of text associated with token or token itself

in

token

Tests whether the value in a resource is a member of the supplied parameter ValueSet

of-type

token (only Identifier)

Tests whether the Identifier value in a resource matches the supplied parameter value

iterate, reverse, logical

n/a

Search with modifiers examples

:missing

GET /fhir/Entity?description:missing=true
// For gender:missing=true,
// server will return all resources that
// don't have a value for the gender parameter. 

:text

// Search for any patient with johndoe@mail.com email
GET /fhir/Patient?email:text=JoHnDoE@mail.com

// Search for any patient with gmail or icloud email
GET /fhir/Patient?email:text=GMail.com,ICloud.com

// Search for any patient which have "fhir" in any of their contact info
GET /fhir/Patient?telecom:text=fhir

:exact

GET /fhir/Patient?name:exact=Alex

:not

//Search for any patient with a gender that does not have the code "male"
//Note that for :not, the search does not return any resources that have a gen
GET /fhir/Patient?gender:not=male

i

// Search for patient with email which is Foo@Bar.BAZ
GET /fhir/Patient?email:i=foo@bar.baz
// Note: this search won't find patient with emails like:
// ffoo@bar.baz
// foo@bar.bazz

in

//Search for any condition that is in the institutions list of cardiac conditions
//Note: you must have Concept with valueset defined

GET /fhir/Condition?code:in=/ValueSet/cardiac-conditions

Prefixes

For Numbers, Dates, and Quantities, we can use the following conditionals in a search:

  • eq - equal (default)

  • ne - non-equal

  • lt - less than

  • le - less or equal

  • gt - greater than

  • ge - greater or equal

For example, to search for patients, who were born before 1986-04-28:

GET /fhir/Patient?birthdate=lt1986-04-28

Want to know more about Aidbox, FHIR, and search? Join our community chat .

Aidbox returns links in response in search requests:

GET /fhir/Patient

resourceType: Bundle
type: searchset
meta:
  versionId: '0'
total: 0
link:
  - relation: first
    url: /fhir/Patient?page=1
  - relation: self
    url: /fhir/Patient?page=1
entry: []

There are two options that can modify url param content:

  • AIDBOX_COMPLIANCE environment variable

  • X-Original-Uri header

AIDBOX_COMPLIANCE env

IF AIDBOX_COMPLIANCE env is enabled then AIDBOX_BASE_URL environment variable will be used like this: <AIDBOX_BASE_URL>/fhir/Patient?page=1. For example we set AIDBOX_BASE_URL to "https://example.com":

GET /fhir/Patient

resourceType: Bundle
type: searchset
meta:
  versionId: '0'
total: 0
link:
  - relation: first
    url: https://example.com/fhir/Patient?page=1
  - relation: self
    url: https://example.com/fhir/Patient?page=1
entry: []

X-Original-Uri header

This header allows you completely overwrite content of url param. Aidbox will automatically add page param to your link, or replace if it exists. For example:

GET /fhir/Patient?name=example
x-original-uri: https://example.com/fhir/Patient?page=4

resourceType: Bundle
type: searchset
meta:
  versionId: '0'
total: 0
link:
  - relation: first
    url: https://example.com/fhir/Patient?page=1
  - relation: self
    url: https://example.com/fhir/Patient?page=4
entry: []

Last updated