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:

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

Where param can be one of:

Simple search by patient name:

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

Special Parameters

Parameter

Type

Description

_id

FHIR

Search and sort by resource id

_lastUpdated

FHIR

Search and sort by resource last modification date

_text

FHIR

Full text search by resource narrative

_content

FHIR

Full text search by resource content

_ilike

ILIKE search by resource content

_elements

FHIR+

Include or exclude specific resource elements

_summary

FHIR

Include only summary elements

_list

FHIR

Search resources included into specific List

_sort

FHIR

Sort search results

_total

FHIR

Turn on/off total count

_include

FHIR

Include referenced resources into result

_revinclude

FHIR

Include into result resources, which reference searched resources

_explain

See query execution plan

_result

Change result format

Search Parameters

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

Type

Description

number

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

date

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

string

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.

token

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.

reference

A reference to another resource.

composite

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

quantity

A search parameter that searches on a quantity.

uri

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

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

Common

  • :missing

  • :text — case insensitive, partial match of text & data associated with search parameter.

FHIR format
Aidbox format
FHIR format
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.
Aidbox format
GET /Entity?description:missing=true
// For gender:missing=true,
// server will return all resources that
// don't have a value for the gender parameter.
FHIR format
Aidbox format
FHIR format
// Search for any patient with [email protected] email
GET /fhir/Patient?email:text=[email protected].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
Aidbox format
// Search for any patient with [email protected] email
GET /Patient?email:text=[email protected].com
// Search for any patient with gmail or icloud email
GET /Patient?email:text=GMail.com,ICloud.com
// Search for any patient which have "fhir" in any of their contact info
GET /Patient?telecom:text=fhir

Strings

  • :exact — no partial matches, case sensitive;

  • :contains — case insensitive, partial match at start or end.

Default behavior is case insensitive, partial match at start.

FHIR format
Aidbox format
FHIR format
GET /fhir/Patient?name:exact=Alex
Aidbox format
GET /Patient?name:exact=Alex

Token

  • :not — reverses the code matching: returns all resources that do not have a matching item.

  • :i — case insensitive, exact match of text associated with token or token itself.

  • :in — the search parameter is a URI (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is in the specified value set.

FHIR format
Aidbox format
FHIR format
//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
Aidbox format
//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 /Patient?gender:not=male
FHIR format
Aidbox format
FHIR format
// Search for patient with email which is [email protected]
GET /fhir/Patient?email:i=[email protected].baz
// Note: this search won't find patient with emails like:
Aidbox format
// Search for patient with email which is [email protected]
GET /Patient?email:i=[email protected].baz
// Note: this search won't find patient with emails like:
FHIR format
Aidbox format
FHIR format
//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
Aidbox format
//Search for any condition that is in the institutions list of cardiac conditions
//Note: you must have Concept with valueset defined
GET /Condition?code:in=/ValueSet/cardiac-conditions

Reference

Reference describes the relationship between resources. Following options are available for filtering by reference:

Сoded element or identifier

FHIR format
Aidbox format
FHIR format
GET /fhir/Patient?gender=female
Aidbox format
GET /Patient?gender=female
[parameter]=[id]
[parameter]=[type]/[id]

For example, let's find all encounters related to a specified patient:

FHIR format
Aidbox format
FHIR format
GET /fhir/Encounter?subject=patientid
Aidbox format
GET /Encounter?subject=patientid
FHIR format
Aidbox format
FHIR format
GET /fhir/Encounter?subject=Patient/patientid
Aidbox format
GET /Encounter?subject=Patient/patientid

Prefixes

For Numbers, Dates, and Quantities (will be supported), 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

FHIR format
Aidbox format
FHIR format
GET /fhir/Patient?birthdate=gt1986-04-28
Aidbox format
GET /Patient?birthdate=gt1986-04-28

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