Search

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 Aidbox & FHIR formats:

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

javascript

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

Where param can be one of:

Search started with underscore, like_sort
Name of SearchParameter
Chained parameter expression
Dotted expression started with.

Simple search by patient name:

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

javascript

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

Special Parameters

Parameter Type Description
_content FHIR Full text search by resource content
_elements FHIR+ Include or exclude specific resource elements
_explain Get query execution plan
_filter FHIR Perform an advanced search
_has FHIR Reverse chaining
_id FHIR Search and sort by resource id
_ilike ILIKE search by resource content
_include FHIR Include referenced resources into result
_lastUpdated FHIR Search and sort by resource last modification date
_list FHIR Search resources included into specific List
_profile FHIR Search by resource profile
_result Change result format
_revinclude FHIR Include into result resources, which reference searched resources
_security FHIR
_sort FHIR Sort search results
_summary FHIR Include only summary elements
_tag FHIR
_text FHIR Full text search by resource narrative
_total FHIR Turn on/off total count
_with Aidbox Include into result resources (compact way compared to include and revinclude)

Parameter	Type	Description
_content	FHIR	Full text search by resource content
_elements	FHIR+	Include or exclude specific resource elements
_explain		Get query execution plan
_filter	FHIR	Perform an advanced search
_has	FHIR	Reverse chaining
_id	FHIR	Search and sort by resource id
_ilike		`ILIKE` search by resource content
_include	FHIR	Include referenced resources into result
_lastUpdated	FHIR	Search and sort by resource last modification date
_list	FHIR	Search resources included into specific List
_profile	FHIR	Search by resource profile
_result		Change result format
_revinclude	FHIR	Include into result resources, which reference searched resources
_security	FHIR
_sort	FHIR	Sort search results
_summary	FHIR	Include only summary elements
_tag	FHIR
_text	FHIR	Full text search by resource narrative
_total	FHIR	Turn on/off total count
_with	Aidbox	Include into result resources (compact way compared to include and revinclude)

Search Parameters

Search is defined in terms of "SearchParameter". 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 Support 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).

Type	Support	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.

Supported modifiers

Modifier Types Description
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 See _include

Modifier	Types	Description
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	See _include

Search with modifiers examples

`:missing`

javascript

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.

javascript

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

`:text`

javascript

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

javascript

// Search for any patient with johndoe@mail.com email
GET /Patient?email:text=JoHnDoE@mail.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

`:exact`

javascript

GET /fhir/Patient?name:exact=Alex

javascript

GET /Patient?name:exact=Alex

`:not`

javascript

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

javascript

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

`i`

javascript

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

javascript

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

`in`

javascript

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

javascript

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

Prefixes

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

eqequal (default)
nenonequal
ltless than
leless or equal
gtgreater than
gegreater or equal

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

javascript

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

javascript

GET /Patient?birthdate=lt1986-04-28

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

Page links

Aidbox returns links in response in search requests:

yaml

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

AIDBOX\_COMPLIANCE env

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

yaml

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:

yaml

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: []