This page is part of the FHIR Specification (v1.6.0: STU 3 Ballot 4). The current version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions . For a full list of available versions, see the Directory of published versions . Page versions: . Page versions: R5 R4B R4 R3 R2

2.1.1 2.42.1 Search Search

FHIR Infrastructure FHIR Infrastructure Work Group Work Group

Maturity Level : N/A Maturity Level : N/A

Ballot Status : DSTU 2 Ballot Status : STU 3

Searching for resources is fundamental to the mechanics of FHIR. Search operations traverse through an existing set of resources filtering by parameters supplied to the search operation. The text below describes the FHIR search framework, starting with simple cases moving to the more complex. Implementers need only implement the amount of complexity that they require for their implementations.

2.1.1.1 2.42.1.1 Summary Table Summary Table

In addition, there is a special search parameter called _filter that allows for an alternative method of searching. that allows for an alternative method of searching.

Also, there is a single page that lists all the search parameters .

2.1.1.2 2.42.1.2 Introduction Introduction In the simplest case, a search is executed by performing a

In the simplest case, a search is executed by performing a GET operation in the RESTful framework: GET [base]/[resourcetype]?name=value&... For this RESTful search (see definition in RESTful API operation in the RESTful framework:

 GET [base]/[type]?name=value&...{&_format=[mime-type]}}

For this RESTful search (see definition in RESTful API ), the parameters are a series of name=[value] pairs encoded in the URL or as an application/x-www-form-urlencoded submission for a POST: ), the parameters are a series of name=[value] pairs encoded in the URL or as an application/x-www-form-urlencoded submission for a POST:

 POST  [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}
The
server
determines
which
of
the
set
of
resources
it
serves
meet
the
specific
criteria,
and
returns
the
results
in
the
HTTP
response
as
a

The server determines which of the set of resources it serves meet the specific criteria, and returns the results in the HTTP response as a bundle which includes the resources that are the results of the search. Search operations are executed in one of three defined contexts that control which set of resources are being searched: A specified resource type: GET [base]/[ResourceType]?parameter(s) which includes the resources that are the results of the search. Note that the _format parameter works for search like for other interactions .

Search operations are executed in one of three defined contexts that control which set of resources are being searched:

• A specified resource type: GET [base]/[type]?parameter(s) A specified
• A specified compartment , perhaps with a specified resource type in that compartment: GET [base]/Patient/[id]/[ResourceType]?parameter(s) , perhaps with a specified resource type in that compartment: GET [base]/Patient/[id]/[type]?parameter(s) All resource types: GET [base]/_search?parameter(s) (parameters common to all types only) Search operations can also be implemented in the messaging framework . The server determines which of their resources meet the criteria contained in the search parameters as described below. However the server has the prerogative to return additional search results if it believes them to be relevant. Note: There is a special search for the most relevant context in which the search set is indeterminate: Patient MPI Search . Search using
• All resource types: GET [base]/_search?parameter(s) (parameters common to all types only)

Search operations can also be implemented in the messaging framework .

The server determines which of their resources meet the criteria contained in the search parameters as described below. However the server has the prerogative to return additional search results if it believes them to be relevant. Note: There is a special search for the most relevant context in which the search set is indeterminate: Patient MPI Search .

Search using GET may include sensitive information in the search parameters. Therefore secure communications and endpoint management are recommended, see Security Communications may include sensitive information in the search parameters. Therefore secure communications and endpoint management are recommended, see Security Communications

2.1.1.3 Handling Errors 2.42.1.3 Handling Errors If a server is unable to execute a search request, it may return an error. A HTTP status code of

If a server is unable to execute a search request, it may return an error. A HTTP status code of 403 signifies that the server refused to perform the search, while other signifies that the server refused to perform the search, while other 4xx and and 5xx codes signify that some sort of error has occurred. When the search fails, a server SHOULD return an codes signify that some sort of error has occurred. When the search fails, a server SHOULD return an OperationOutcome detailing the cause of the failure. Note: An empty search result is not a failure. In some cases, parameters may cause an error. For instance: A parameter may refer to a non-existent resource e.g. GET [base]/Observation?subject=101 , where "101" does not exist A parameter may refer 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 A parameter may refer to a time that is out of scope e.g. GET [base]/Condition?onset=le1995 , where the system only has data going back to 2001 A parameter may use an illegal or unaaceptable modifier e.g. GET [base]/Condition?onset:text=1995 , where the modifier cannot be processed by the server A data time parameter may have incorrect format e.g. GET [base]/Condition?onset=23%20May%202009 detailing the cause of the failure. Note: An empty search result is not a failure.

In some cases, parameters may cause an error. For instance:

• A parameter may refer to a non-existent resource e.g. GET [base]/Observation?subject=101 , where "101" does not exist
• A parameter may refer 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
• A parameter may refer to a time that is out of scope e.g. GET [base]/Condition?onset=le1995 , where the system only has data going back to 2001
• A parameter may use an illegal or unacceptable modifier e.g. GET [base]/Condition?onset:text=1995 , where the modifier cannot be processed by the server
• A data time parameter may have incorrect format e.g. GET [base]/Condition?onset=23%20May%202009 Where the content of the parameter is syntactically correct, servers SHOULD return an error. However where the issue is a logical condition (e.g. unknown subject or code), the server SHOULD process the search, including processing the parameter - with the result of returning an empty search set, since the parameter cannot be satisfied. In such cases, the search process MAY include an
• A parameter may be unknown or unsupported (see below)

Where the content of the parameter is syntactically incorrect, servers SHOULD return an error. However where the issue is a logical condition (e.g. unknown subject or code), the server SHOULD process the search, including processing the parameter - with the result of returning an empty search set, since the parameter cannot be satisfied.

In such cases, the search process MAY include an OperationOutcome in the search set that contains additional hints and warnings about the search process. This is included in the search results as an entry with search mode = in the search set that contains additional hints and warnings about the search process. This is included in the search results as an entry with search mode = outcome . Clients can use this information to improve future searches. . Clients can use this information to improve future searches.

Unknown and unsupported parameters

Servers may receive parameters from the client that they do not recognise, or may receive parameters they recognise but do not support (either in general, or for a specific search). In general, servers SHOULD ignore 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
• The client can determine what parameters the server used by examing the self link in the return (see below )

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

Servers SHOULD honor the client's request, but are not required to do so.

2.1.1.4 Standard Parameters 2.42.1.4 Standard Parameters

2.1.1.4.1 Parameters for all resources 2.42.1.4.1 Parameters for all resources The following parameters apply to all resources :

The following parameters apply to all resources : _content , , _id , , _lastUpdated , , _profile , , _query , , _security , , _tag , _text . In addition, the search parameter . In addition, the search parameter _text and and _filter , (documented below) also applies to all resources (as do the search result parameters). The search parameter , (documented below) also applies to all resources (as do the search result parameters).

The search parameter _id refers to the logical id of the resource, and can be used when the search context specifies a resource type: refers to the logical id of the resource, and can be used when the search context specifies a resource type:

 GET [base]/Patient?_id=23
This
search
finds
the
patient
resource
with
the
given
id
(there
can
only
be
one
resource
for
a
given
id).
Functionally,
this
is
equivalent
to
a
simple
read
operation
:

This search finds the patient resource with the given id (there can only be one resource for a given id). Functionally, this is equivalent to a simple read operation :

 GET [base]/Patient/23
However,
the
search
with
parameter

However, the search with parameter _id returns a bundle with the requested resource, instead of just the resource itself. Additional parameters can be added which may provide additional functionality on top of this base read equivalence (e.g. returns a bundle with the requested resource, instead of just the resource itself. Additional parameters can be added which may provide additional functionality on top of this base read equivalence (e.g. _include ). The search parameter ). Note that although the _id parameter has a type of token, because servers SHALL use exact match with it, there is no system for the _id parameter.

The search parameter _lastUpdated can be used to select resources based on the last time they were changed: can be used to select resources based on the last time they were changed:

 GET [base]/Observation?_lastUpdated=>2010-10-01
This
search
finds
any
observations
changed
since
1-Oct
2010.
When
this
search
parameter
is
used,
applications
should
consider
synchronization
approaches
(

This search finds any observations changed since 1-Oct 2010. When this search parameter is used, applications should consider synchronization approaches ( RESTful history or the Subscription resource ). RESTful history or the Subscription resource The search parameters ).

The search parameters _tag , , _profile and and _security parameters search on the equivalent elements in the parameters search on the equivalent elements in the meta element . For example, element . For example,

 GET [base]/Condition?_tag=http://acme.org/codes|needs-review
searches
for
all
Condition
resources
with
the
tag:

searches for all Condition resources with the tag:

{
  "system" : "http://acme.org/codes",
  "code" : "needs-review"
}
In
the
same
manner:

In the same manner:

 GET [base]/DiagnosticReport?_profile=http://hl7.org/fhir/StructureDefinition/lipid
 GET [base]/DiagnosticReport?_profile=Profile/lipid
restricts
the
search
to
only
DiagnosticReport
resources
that
are
tagged
as
conforming
to
a
particular
profile.
The
second
reference
is
relative,
and
refers
a
local
profile
on
the
same
server.

restricts the search to only DiagnosticReport resources that are tagged as conforming to a particular profile. The second reference is relative, and refers a local profile on the same server.

_tag , , _profile and and _security parameters are all token types (see parameters are all token types (see below ). ).

2.1.1.4.2 2.42.1.4.2 Parameters for each resource Parameters for each resource In addition to the

In addition to the _id parameter which exists for all resources, each FHIR resource type defines its own set of search parameters with their names, types, and meanings. These search parameters are on the same page as the resource definitions, and are also published as part of the standard conformance statement ( parameter which exists for all resources, each FHIR resource type defines its own set of search parameters with their names, types, and meanings. These search parameters are on the same page as the resource definitions, and are also published as part of the standard conformance statement ( XML or or JSON ). In general, the defined search parameters correspond to a single element in the resource, but this is not required, and some search parameters refer to the same type of element in multiple places, or refer to derived values. Some search parameters defined by resources are associated with more than one path in a resource. This means that the search parameter matches if any of the paths contain matching content. If a path matches, the whole resource is returned in the search results. The client may have to examine the resource to determine which path contains the match. Servers are not required to implement any of the standard search parameters (except for the ).

In general, the defined search parameters correspond to a single element in the resource, but this is not required, and some search parameters refer to the same type of element in multiple places, or refer to derived values.

Some search parameters defined by resources are associated with more than one path in a resource. This means that the search parameter matches if any of the paths contain matching content. If a path matches, the whole resource is returned in the search results. The client may have to examine the resource to determine which path contains the match.

Servers are not required to implement any of the standard search parameters (except for the _id parameter described above), and may define their own parameters. parameter described above), and may define their own parameters.

2.1.1.4.3 Search Parameter Types 2.42.1.4.3 Search Parameter Types Each search parameter is defined by a type that specifies how the search parameter behaves. These are the defined parameter types:

Each search parameter is defined by a type that specifies how the search parameter behaves. These are the defined parameter types:

The search parameters can also append "modifiers" that control their behavior. The kinds of modifiers that available is dependent on the type of parameter being modified.

2.1.1.4.4 Modifiers 2.42.1.4.4 Modifiers Parameters are defined per resource. Parameter names may specify a modifier as a suffix. The modifiers are separated from the parameter name by a colon. Modifiers are: For all parameters (except combination): :missing

Parameters are defined per resource. Parameter names may specify a modifier as a suffix. The modifiers are separated from the parameter name by a colon. Modifiers are:

• For all parameters (except combination): :missing ; e.g. gender:missing=true (or false). Searching for ; e.g. gender:missing=true (or false). Searching for gender:missing=true will return all the resources that don't have a value for the gender parameter (which usually equates to not having the relevant element in the resource). Searching for will return all the resources that don't have a value for the gender parameter (which usually equates to not having the relevant element in the resource). Searching for gender:missing=false will return all the resources that have a value for the will return all the resources that have a value for the gender parameter. For string: :exact (the match needs to be exact, no partial matches, case sensitive and accent-sensitive), or :contains (case insensitive and accent-insensitive, partial match at start or end), instead of the default behavior (case insensitive and accent-insensitive, partial matches at the end of the string). For token: :text (the match does a partial searches on the text portion of a CodeableConcept or the display portion of a Coding), instead of the default search which uses codes. Other defined modifiers are :in , :below , :above and :not-in which are described below. For reference: :[type] where [type] is the name of a type of resource For uri: :below , :above indicate that instead of an exact match, either the search term left matches the value, or vice-versa. Server SHALL reject any search request that contains is suffixed by a modifier that the server does parameter.
• For string: :exact (the match needs to be exact, no partial matches, case sensitive and accent-sensitive), or :contains (case insensitive and accent-insensitive, partial match at start or end), instead of the default behavior (case insensitive and accent-insensitive, partial matches at the end of the string).
• For token: :text (the match does a partial searches on the text portion of a CodeableConcept or the display portion of a Coding), instead of the default search which uses codes. Other defined modifiers are :in, :below, :above and :not-in which are described below.
• For reference: :[type] where [type] is the name of a type of resource
• For uri: :below , :above indicate that instead of an exact match, either the search term left matches the value, or vice-versa.

Server SHALL reject any search request that contains is suffixed by a modifier that the server does not support for that parameter. For example, if the server supports the support for that parameter. For example, if the server supports the name search param, but not the :exact modifier on the name, it should reject a search with the parameter search param, but not the :exact modifier on the name, it should reject a search with the parameter name:exact=Bill , using an HTTP , using an HTTP 400 error with an error with an OperationOutcome with a clear error message . with a clear error message .

2.1.1.4.5 Prefixes 2.42.1.4.5 Prefixes For the ordered parameter types of

For the ordered parameter types of number , , date , and , and quantity , a prefix to the parameter value may be used to control the nature of the matching. To avoid URL escaping and visual confusion, the following prefixes are used: , a prefix to the parameter value may be used to control the nature of the matching. To avoid URL escaping and visual confusion, the following prefixes are used:

If no prefix is present, the prefix eq is assumed. Note that the way search parameters operate is not the same as the way the operations on two numbers work in a mathematical sense. is assumed. Note that the way search parameters operate is not the same as the way the operations on two numbers work in a mathematical sense. sa ( ( starts-after ) and ) and eb ( ( ends-before ) are not used with integer values. For each prefix above, two interpretations are provided - the simple intent of the prefix and the interpretation of the parameter when applied to ranges. The range interpretation is provided for decimals and dates. Searches are always performed on values that are implicitly or explicitly a range. For instance, the number 2.0 has an implicit range of 1.95 to 2.05, and the date 2015-08-12 has an implicit range of the all the time during that day. If the target value is a ) are not used with integer values.

For each prefix above, two interpretations are provided - the simple intent of the prefix and the interpretation of the parameter when applied to ranges. The range interpretation is provided for decimals and dates. Searches are always performed on values that are implicitly or explicitly a range. For instance, the number 2.0 has an implicit range of 1.95 to 2.05, and the date 2015-08-12 has an implicit range of the all the time during that day. If the target value is a Range , a , a Period , or a , or a Timing , then the target is explicitly a range. Three ranges are identified: range of the value The limits implied by the precision of the value The number 2.0 has a range of 1.95 to 2.05 The date 2015-08-12 has a range from 00:00 to 00:00 exclusive range below the value Up to the specified value The range below 2.0 includes any value less or equal to <2.00000000000000000000 The range before 2015-08-12T05:23:45 includes any time up to 2015-08-12T05:23:45.000000000000000 range above the value The specified value and up The range above 2.0 includes any value greater or equal to <2.00000000000000000000 The range after 2015-08-12T05:23:45 includes any time after 2015-08-12T05:23:45.000000000000000 The proper use of these ranges is discussed further below. , then the target is explicitly a range. Three ranges are identified:

The proper use of these ranges is discussed further below.

2.1.1.4.6 number 2.42.1.4.6 number Sarching on a simple numerical value in a resource. Examples:

Sarching on a simple numerical value in a resource. Examples:

Note: Uncertainty does not factor in evaluations. The precision of the numbers is considered arbitrarily high. (The way search parameters operate in resources is not the same as whether two numbers are equal to each other in a mathematical sense).

Here are some example searches:

 GET [base]/Encounter?length=gt20

 GET [base]/ImmunizationRecommendation?deo-number=2

2.1.1.4.7 date 2.42.1.4.7 date A date parameter searches on a date/time or period. As is usual for date/time related functionality, while the concepts are relatively straight-forward, there are a number of subtleties involved in ensuring consistent behavior. The date parameter format is

A date parameter searches on a date/time or period. As is usual for date/time related functionality, while the concepts are relatively straight-forward, there are a number of subtleties involved in ensuring consistent behavior.

The date parameter format is yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm] (the standard XML format). Technically, this is any of the (the standard XML format).

Technically, this is any of the date , , dateTime , and , and instant data types; e.g. Any degree of precision can be provided, but it SHALL be populated from the left (e.g. can't specify a month without a year), except that the minutes SHALL be present if an hour is present, and you SHOULD provide a time zone if the time part is present. Note: Time can consist of hours and minutes with no seconds, unlike the XML Schema dateTime type. Some user agents may escape the : characters in the URL, and servers SHALL handle this correctly. Date parameters may be used with the following data types: data types; e.g. Any degree of precision can be provided, but it SHALL be populated from the left (e.g. can't specify a month without a year), except that the minutes SHALL be present if an hour is present, and you SHOULD provide a time zone if the time part is present. Note: Time can consist of hours and minutes with no seconds, unlike the XML Schema dateTime type. Some user agents may escape the : characters in the URL, and servers SHALL handle this correctly.

Date parameters may be used with the following data types:

Implicitly, a missing lower boundary is "less than" any actual date. A missing upper boundary is "greater than" any actual date. The use of the prefixes:

Other notes:

• When the date parameter is not fully specified, matches against it are based on the behavior of intervals, where:
  • Dates with only the year specified are equivalent to an interval that starts at the first instant of January 1st to the last instant of December 31st, e.g. 2000 is equivalent to an interval of [2000-01-01T00:00, 2000-12-31T23:59].
  • Dates with the year and month are equivalent to an interval that starts at the first instant of the first day of the month and ends on the last instant of the last day of the month, e.g. 2000-04 is equivalent to an interval of [2000-04-01T00:00, 2000-04-30T23:59].
• Where possible, the system should correct for timezones when performing queries. Dates do not have time zones, and time zones should not be considered. Where both search parameters and resource element date times do not have time zones, the servers local time zone should be assumed.

To search for all the procedures in a patient compartment that occurred over a 2 year period:

 GET [base]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31

2.1.1.4.8 string 2.42.1.4.8 string For a simple string search, a string parameter serves as the input for a case- and accent-insensitive search against sequences of characters. By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent. The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched. The :exact modifier returns results that match the entire supplied parameter, including casing and accents. Examples:

For a simple string search, a string parameter serves as the input for a case- and accent-insensitive search against sequences of characters. By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and accent. The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched. The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

Examples:

An additional modifier :text can be used to specify a search with advanced text handling (see below ) though only a few servers are expected to offer this facility. It is at the discretion of the server whether to pre-process names, addresses, and contact details to remove separator characters prior to matching in order to ensure more consistent behavior. For example, a server might remove all spaces and ) though only a few servers are expected to offer this facility.

When a string search parameter refers to the types HumanName and Address , the search covers the elements of type string, and does not cover elements such as use and period .

It is at the discretion of the server whether to pre-process names, addresses, and contact details to remove separator characters prior to matching in order to ensure more consistent behavior. For example, a server might remove all spaces and - characters from phone numbers. What is most appropriate varies depending on culture and context. characters from phone numbers. What is most appropriate varies depending on culture and context. A server may also use a free-text style searches on this property to achieve the best results When searching whole names and addresses (not parts), servers may also use flexible match or a free-text style searches on names to achieve the best results.

2.1.1.4.9 uri 2.42.1.4.9 uri The uri parameter refers to a URI (

The uri parameter refers to a URI ( RFC 3986 RFC 3986 ) element. Matches are precise (e.g. case, accent, and escape) sensitive, and the entire URI must match. The modifier :above or :below can be used to indicate that partial matching is used. For example: ) element. Matches are precise (e.g. case, accent, and escape) sensitive, and the entire URI must match. The modifier :above or :below can be used to indicate that partial matching is used. For example:

 GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123
 GET [base]/ValueSet?url:below=http://acme.org/fhir/
The
first
line
is
a
request
to
find
any
value
set
with
the
exact
url
"http://acme.org/fhir/ValueSet/123".
The
second
line
performs
a
search
that
will
return
any
value
sets
that
have
a
URL
that
starts
with
"http://acme.org/fhir/".
The
converse
-
the
search
for
any
value
set
above
a
given
specific
URL.
This
approach
may
be
useful
for
searching
name
systems,
but
it
is
generally
less
useful
than
the
:below
search.

 GET [base]/ValueSet?url=http://acme.org/fhir/
 GET [base]/ValueSet?url=urn:oid:1.2.3.4.5

The first line is a request to find any value set with the exact url "http://acme.org/fhir/ValueSet/123". The second line performs a search that will return any value sets that have a URL that starts with "http://acme.org/fhir/". The converse - the search for any value set above a given specific URL. This approach may be useful for searching name systems, but it is generally less useful than the :below search. The third line shows an example of searching by an OID. Note that the :above and :below modifiers only apply to URLs, and not URNS such as OIDs.

2.1.1.4.10 token 2.42.1.4.10 token A token type is a parameter that searches on a URI/value pair. It is used against a code or identifier data type where the value may have a URI that scopes its meaning. The search is performed against the pair from a Coding or an Identifier. The syntax for the value is one of the following:

A token type is a parameter that searches on a URI/value pair. It is used against a code or identifier data type where the value may have a URI that scopes its meaning. The search is performed against the pair from a Coding or an Identifier. Matches are literal (e.g. not based on subsumption or other code system features), but not case sensitive. To use subsumption based logic, use the modifiers below, or list all the codes in the heirarchy. The syntax for the value is one of the following:

• [parameter]=[code] : the value of : the value of [code] matches a Coding.code or Identifier.value irrespective of the value of the system property matches a Coding.code or Identifier.value irrespective of the value of the system property
• [parameter]=[system]|[code] : the value of : the value of [code] matches a Coding.code or Identifier.value, and the value of matches a Coding.code or Identifier.value, and the value of [system] matches the system property of the Identifier or Coding matches the system property of the Identifier or Coding
• [parameter]=|[code] : the value of : the value of [code] matches a Coding.code or Identifier.value, and the Coding/Identifier has no system property
• [parameter]=[system]| matches a Coding.code or Identifier.value, and the Coding/Identifier has no system property Note: The namespace URI and code both must be : any element where the value of [system] matches the system property of the Identifier or Coding

Note: The namespace URI and code both must be escaped . Matches are literal (e.g. not based on subsumption or other code system features), but not case sensitive. Token search parameters are used for the following data types: correctly.

Token search parameters are used for the following data types:

Note: The use of token search parameters for boolean fields: the boolean values "true" and "false" are also represented as formal codes in the Special Values code system, which is useful when boolean values need to be represented in a Coding data type. The namespace for these codes is http://hl7.org/fhir/special-values, though there is usually no reason to use this, as a simple true or false is sufficient. data type. The namespace for these codes is http://hl7.org/fhir/special-values, though there is usually no reason to use this, as a simple true or false is sufficient.

Modifiers:

Most servers will only process value sets that are already known/registered/supported internally. However, servers can elect to accept any valid reference to a value set. Servers may elect to consider concept mappings when testing for subsumption relationships.

Example searches:

 GET [base]/Patient?identifier=http://acme.org/patient|2345

 GET [base]/Patient?gender=male

 GET [base]/Patient?gender:not=male

 GET [base]/Patient?active=true

 GET [base]/Condition?code=http://acme.org/conditions/codes|ha125

 GET [base]/Condition?code=ha125

 GET [base]/Condition?code:text=headache

 GET [base]/Condition?code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F126851005

 GET [base]/Condition?code:below=126851005

 GET [base]/Condition?code:in=http://acme.org/fhir/ValueSet/cardiac-conditions

2.1.1.4.11 quantity 2.42.1.4.11 quantity A quantity parameter searches on the

A quantity parameter searches on the Quantity data type. The syntax for the value follows the form: data type. The syntax for the value follows the form:

• [parameter]=[prefix][number]|[system]|[code] matches a quantity with the given unit The prefix is optional, and is as described matches a quantity with the given unit

The prefix is optional, and is as described above , both regarding how precision and comparator/range operators are interpreted. Example searches: , both regarding how precision and comparator/range operators are interpreted. Example searches:

 GET [base]/Observation?value=5.4|http://unitsofmeasure.org|mg

 GET [base]/Observation?value=5.4||mg

 GET [base]/Observation?value=le5.4|http://unitsofmeasure.org|mg

 GET [base]/Observation?value=ap5.4|http://unitsofmeasure.org|mg

The search processor may choose to perform a search based on canonical units (e.g. any value where the units can be converted to a value in mg in the case above).

2.1.1.4.12 reference 2.42.1.4.12 reference A reference parameter refers to references between resources . For example, find all Conditions where the subject reference is a particular patient, where the patient is selected by name or identifier. The interpretation of a

A reference parameter refers to references between resources . For example, find all Conditions where the subject reference is a particular patient, where the patient is selected by name or identifier. The interpretation of a reference parameter is either: parameter is either:

• [parameter]=[id] the logical [id] of a resource using a local reference (i.e. a relative reference) the logical [id] of a resource using a local reference (i.e. a relative reference)
• [parameter]=[type]/[id] the logical [id] of a resource of a specified type using a local reference (i.e. a relative reference), for when the reference can point to different types of resources (e.g. the logical [id] of a resource of a specified type using a local reference (i.e. a relative reference), for when the reference can point to different types of resources (e.g. Observation.subject )
• [parameter]=[url] where the [url] is an absolute URL - a reference to a resource by its absolute location Note: A relative reference resolveing to the same value as a specified absolute URL, or vice versa, qualifies as a match. For example, if the search parameter value is Patient/123, then this will find references like this: where the [url] is an absolute URL - a reference to a resource by its absolute location

Note: A relative reference resolveing to the same value as a specified absolute URL, or vice versa, qualifies as a match. For example, if the search parameter value is Patient/123, then this will find references like this:

 <patient>
   <reference value="Patient/123"/>
 </patient>
If
the
server
base
address
is
http://example.org/fhir,
then
the
full
URL
for
that
reference
is
http://example.org/fhir/Patient/123,
which
means
that
the
search
term
also
matches
patient
references
like
this:

If the server base address is http://example.org/fhir, then the full URL for that reference is http://example.org/fhir/Patient/123, which means that the search term also matches patient references like this:

 <patient>
   <reference value="http://example.org/fhir/Patient/123"/>
 </patient>
In
addition,
searching
for

In addition, searching for reference=http://example.org/fhir/Patient/123 will also match both references.

Some references are allowed to point to more than one type of resource; e.g. subject : Reference(Patient|Group|Device|..). In these cases, multiple resources may have the same logical identifier. Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types. In order to allow the client to perform a search in these situations the type is specified explicitly:

 GET [base]/Observation?subject=Patient/23

This searches for any conditions where the subject refers to the patient resource with the logical identifier "23". A modifier is also defined to to allow the client to be explicit about the intended type:

 GET [base]/Observation?subject:Patient=23

This has the same effect as the previous search. The modifier becomes useful when used with chaining as explained in the next section. Note: The [type] modifier can't be used with a reference to a resource found on another server, since the server would not usually know what type that resource has. However, since these are absolute references, there can be no ambiguity about the type.

In some cases, search parameters are defined with an implicitly limited scope. For example, Observation will also match both references. Some references are allowed to point to more than one type of resource; e.g. has an element subject : Reference(Patient|Group|Device|..). In these cases, multiple resources may have the same logical identifier. Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types. In order to allow the client to perform a search in these situations the type is specified explicitly: GET [base]/Condition?subject=Patient/23 This searches for any conditions where the , which is a reference to one of a number of types. This has a matching search parameter subject refers to the , which refers to any of the possible types. In addition to this, there is another search parameter patient resource with the logical identifier "23". A modifier is also defined to to allow the client to be explicit about the intended type: GET [base]/Condition?subject:Patient=23 This has the same effect as the previous search. The modifier becomes useful when used with chaining as explained in the next section. Note: The , which also refers to Observation.subject , but is limited to only include references of type [type] Patient modifier can't be used with a reference to a resource found on another server, since the server would not usually know what type that resource has. However, since these are absolute references, there can be no ambiguity about the type. . When using the patient search parameter, there is no need to specify ":Patient" as a modifier, or "Patient/" in the search value, as this must always be true.

2.1.1.4.13 2.42.1.4.13 Chained parameters Chained parameters In order to save a client from performing a series of search operations, reference parameters may be "chained" by appending them with a period (

In order to save a client from performing a series of search operations, reference parameters may be "chained" by appending them with a period ( . ) followed by the name of a search parameter defined for the target resource. This can be done recursively, following a logical path through a graph of related resources, separated by . . For instance, given that the resource ) followed by the name of a search parameter defined for the target resource. This can be done recursively, following a logical path through a graph of related resources, separated by . . For instance, given that the resource DiagnosticReport has a search parameter named has a search parameter named subject , which is usually a reference to a Patient resource, and the , which is usually a reference to a Patient resource includes a parameter resource, and the Patient resource includes a parameter name which searches on patient name, then the search which searches on patient name, then the search

 GET [base]/DiagnosticReport?subject.name=peter
is
a
request
to
return
all
the
lab
reports
that
have
a
subject
whose
name
includes
"peter".
Because
the
Diagnostic
Report
subject
can
be
one
of
a
set
of
different
resources,
it's
necessary
to
limit
the
search
to
a
particular
type:

is a request to return all the lab reports that have a subject whose name includes "peter". Because the Diagnostic Report subject can be one of a set of different resources, it's necessary to limit the search to a particular type:

 GET [base]/DiagnosticReport?subject:Patient.name=peter
This
request
returns
all
the
lab
reports
that
have
a
subject
which
is
a
patient,
whose
name
includes
"peter".
Advanced
Search
Note:
Where
a
chained
parameter
searches
a
resource
reference
that
may
have
more
than
one
type
of
resource
as
its
target,
the
parameter
chain
may
end
up
referring
to
search
parameters
with
the
same
name
on
more
than
one
kind
of
resource
at
once.
Servers
SHOULD
reject
a
search
where
the
logical
id
refers
to
more
than
one
matching
resource
across
different
types.
For
example,
the
client
has
to
specify
the
type
explicitly
using
the
syntax
in
the
second
example
above.

This request returns all the lab reports that have a subject which is a patient, whose name includes "peter".

Advanced Search Note: Where a chained parameter searches a resource reference that may have more than one type of resource as its target, the parameter chain may end up referring to search parameters with the same name on more than one kind of resource at once. Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types. For example, the client has to specify the type explicitly using the syntax in the second example above.

2.1.1.4.14 Composite Search Parameters 2.42.1.4.14 Reverse Chaining Composite search parameters supports joining single values with a

The _has parameter provides limited support for reverse chaining - that is, selecting resources based on the properties of resources that refer to them (instead of chaining, above, where resources can be selected based on the properties of resources that they refer to). Here is an example of gthe _has parameter:

GET [base]/Patient?_has:Observation:patient:code=1234-5

This requests the server to return Patient resources, where the patient resource is referred to by at least one Observation where the observation has a code of 1234, and where the Observation refers to the patient resource in the patient search parameter.

Note the following limitations on the use of the _has parameter:

• There is no support for reverse chaining to more than one level
• Modifiers are not supported (e.g. GET [base]/Patient?_has:Observation:subject:code:in=http://loinc.org)
• Chaining is not supported (e.g. GET [base]/Patient?_has:Observation:subject:device.identifier=foo)

"Or" searches are allowed (e.g. GET [base]/Patient?_has:Observation:subject:code=123,456), and multiple _has parameters are allowed (e.g. GET [base]/Patient?_has:Observation:subject:code=123&_has:Observation:subject:code=456). Note that each _has parameter is processed independently of other _has parameters.

STU Note: the _has search parameter is a new addition that has generated significant discussion. if adopted, it may replace the _list parameter. Or not.

Feedback is welcome here .

2.42.1.4.15 Composite Search Parameters

Composite search parameters supports joining single values with a $ . For example, the result of the search operation is the intersection of the resources that match the criteria specified by each individual search parameter. If a parameter repeats, such as . For example, the result of the search operation is the intersection of the resources that match the criteria specified by each individual search parameter. If a parameter repeats, such as /Patient?language=FR&language=NL , then this matches a patient who speaks both languages. This is known as an AND search parameter, since the server is expected to respond only with results which match both values. If, instead, the search is to find patients that speak either language, then this is a single parameter with multiple values, separated by a , . For example, , then this matches a patient who speaks both languages. This is known as an AND search parameter, since the server is expected to respond only with results which match both values.

If, instead, the search is to find patients that speak either language, then this is a single parameter with multiple values, separated by a , . For example, /Patient?language=FR,NL . This is known as an OR search parameter, since the server is expected to respond with results which match either value. AND parameters and OR parameters may also be combined, for example: . This is known as an OR search parameter, since the server is expected to respond with results which match either value.

AND parameters and OR parameters may also be combined, for example: /Patient?language=FR,NL&language=EN would refer to any patient who speaks English, as well as either French or Dutch. This approach allows for simple combinations of and/or values, but doesn't allow a search based on a pair of values, such as all observations with a sodium value >150 mmol/L (particularly as the end criteria of a chained search), or searching on Group.characteristic where you need find a combination of key/value, not an intersection of separate matches on key and value. Another example is spatial coordinates when doing geographical searches. To allow these searches, a resource may also specify would refer to any patient who speaks English, as well as either French or Dutch.

This approach allows for simple combinations of and/or values, but doesn't allow a search based on a pair of values, such as all observations with a sodium value >150 mmol/L (particularly as the end criteria of a chained search), or searching on Group.characteristic where you need find a combination of key/value, not an intersection of separate matches on key and value. Another example is spatial coordinates when doing geographical searches.

To allow these searches, a resource may also specify composite parameters that take sequences of single values that match other defined parameters as an argument. The matching parameter of each component in such a sequence is documented in the definition of the parameter. These sequences are formed by joining the single values with a parameters that take sequences of single values that match other defined parameters as an argument. The matching parameter of each component in such a sequence is documented in the definition of the parameter. These sequences are formed by joining the single values with a $ . Note: This sequence is a single value and itself can be composed into a set of values, so that, for example, multiple matching state-on-date parameters can be specified as . Note: This sequence is a single value and itself can be composed into a set of values, so that, for example, multiple matching state-on-date parameters can be specified as state-on-date=new$2013-05-04,active$2013-05-05 . Note: Modifiers are not used on composite parameters. Examples of using composite parameters: .

Note: Modifiers are not used on composite parameters.

Examples of using composite parameters:

 GET [base]/DiagnosticReport?result.code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L

 GET [base]/Observation?component-code-value-quantity=http://loinc.org|8480-6$lt60

 GET [base]/Group?characteristic-value=gender$mixed

2.1.1.4.15 Escaping Search Parameters 2.42.1.4.16 Escaping Search Parameters In the rules described above, special rules are defined for the characters

In the rules described above, special rules are defined for the characters $ , , , and , , , and | . As a consequence, if these characters appear in an actual parameter value, they must be differentiated from their use as separator characters. When any of these characters appear in an actual parameter value, they must be prepended by the character . As a consequence, if these characters appear in an actual parameter value, they must be differentiated from their use as separator characters. When any of these characters appear in an actual parameter value, they must be prepended by the character \ , which also must be used to prepend itself. Therefore, , which also must be used to prepend itself. Therefore, param=xxx$xxx indicates that it is a composite parameter, while indicates that it is a composite parameter, while param=xx\$xx indicates that the parameter has the literal value indicates that the parameter has the literal value xx$xx . The parameter value . The parameter value xx\xx is illegal, and the parameter value is illegal, and the parameter value param=xx\\xx indicates a literal value of indicates a literal value of xx\xx . This specification defines this additional form of escape for a reason. The classic .

This specification defines this additional form of escape for a reason. The classic %xx escaping which is part of normal HTTP URLs ensures thatthe character appears at the FHIR server correctly, while the , versus escaping which is part of normal HTTP URLs ensures that the character appears at the FHIR server correctly, while the , versus \ becomes important once it has reached the server and the query is parsed. Therefore: becomes important once it has reached the server and the query is parsed. Therefore:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124%2CValueSet/125
uses
url
escaping
to
make
sure
the
FHIR
server
received:

uses url escaping to make sure the FHIR server received:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124,125
This
request
will
compare
the
URL
against
three
values:
the
last
one
being
a
relative
and
incorrect
url,
which
is
likely
not
the
actual
intent.
However:

This request will compare the URL against three values: the last one being a relative and incorrect url, which is likely not the actual intent. However:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,125
is
equivalent
to:

is equivalent to:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\%2C125
which
would
mean:
url
=

which would mean: url = http://.....123 OR OR http://....124,125 . .

2.1.1.4.16 Text Search Parameters 2.42.1.4.17 Text Search Parameters The special text search parameters,

The special text search parameters, _text and and _content , search on the narrative of the resource, and the entire content of the resource respectively. These parameters SHOULD support a sophisticated search functionality of the type offered by typical text indexing services. The value of the parameter is a text based search, which may involve searching multiple words with thesaurus and proximity considerations, and logical operations such as AND, OR etc. For example: , search on the narrative of the resource, and the entire content of the resource respectively. These parameters SHOULD support a sophisticated search functionality of the type offered by typical text indexing services. The value of the parameter is a text based search, which may involve searching multiple words with thesaurus and proximity considerations, and logical operations such as AND, OR etc. For example:

 GET [base]/Condition?_text=(bone OR liver) and metastases
This
request
returns
all
Condition
resources
with
the
word
"metastases"
and
either
"bone"
or
"liver"
in
the
narrative.
The
server
MAY
choose
to
search
for
related
words
as
well.
DSTU
Note:
The
issues
around
standardizing
text
search
are
not
fully
resolved.
During
the
trial
use
period
for
this
specification,
we
recommend
that
systems
use
the
rules
specified
by
the
OData
specification
for
the
$

This request returns all Condition resources with the word "metastases" and either "bone" or "liver" in the narrative. The server MAY choose to search for related words as well.

DSTU Note: The issues around standardizing text search are not fully resolved. During the trial use period for this specification, we recommend that systems use the rules specified by the OData specification for the $ search parameter parameter . Typical implementations would use Lucene, an sql-based full text search, or some indexing service. Feedback is welcome here . Typical implementations would use Lucene, an sql-based full text search, or some indexing service.

Feedback is welcome here . .

2.1.1.4.17 Searching by list 2.42.1.4.18 Searching by list The

The _list parameter allows for the retrieval of resources that are referenced by a parameter allows for the retrieval of resources that are referenced by a List resource. resource.

 GET [base]/Patient?_list=42
This
request
returns
all
Patient
resources
that
are
referenced
from
the
list
found
at

This request returns all Patient resources that are referenced from the list found at [base]/List/42 ) in List.entry.item. While it is possible to retrieve the list, and then iterate the entries in the list fetching each patient, using a list as a search criteria allows for additional search criteria to be specified. For instance: ) in List.entry.item. While it is possible to retrieve the list, and then iterate the entries in the list fetching each patient, using a list as a search criteria allows for additional search criteria to be specified. For instance:

 GET [base]/Patient?_list=42&gender=female
This
request
will
return
all
female
patients
in
the
list.
The
server
can
return
the
list
referred
to
in
the
search
parameter
as
an
included
resource,
but
is
not
required
to
do
so.
In
addition,
a
system
can
support
searching
by
lists
by
their
logical
function.
For
example:

This request will return all female patients in the list. The server can return the list referred to in the search parameter as an included resource, but is not required to do so. In addition, a system can support searching by lists by their logical function. For example:

 GET [base]/AllergyIntolerance?patient=42&_list=$current-allergies
This
request
will
return
all
allergies
in
patient
42's
"Currrent
Allergy
List".
The
server
returns
all
relevant
AllergyIntolerance
resources,
and
can
also
choose
to
return
the
list.
For
further
information,
refer
to
the
definition
of
"$current-allergies"
,
and
the
List
Operation
"Find"
.
Note:
Servers
are
not
required
to
make
these
lists
available
to
the
clients
as
list
resources,
but
may
choose
to
do
so.

This request will return all allergies in patient 42's "Current Allergy List". The server returns all relevant AllergyIntolerance resources, and can also choose to return the list. For further information, refer to the definition of "$current-allergies" , and the List Operation "Find" . Note: Servers are not required to make these lists available to the clients as list resources, but may choose to do so.

STU Note: the _has search parameter documented above is a new addition that has generated significant discussion. if adopted, it may replace the _list parameter. Or not.

Feedback is welcome here .

2.1.1.4.18 Advanced filtering 2.42.1.4.19 Advanced filtering The search mechanism described above is flexible, and easy to implement for simple cases, but is limited in its ability to express combination queries. To complement this mechanism, a the "_filter" search expression parameter can be used. For example, "Find all the observations for patient with a name including

The search mechanism described above is flexible, and easy to implement for simple cases, but is limited in its ability to express combination queries. To complement this mechanism, a the "_filter" search expression parameter can be used.

For example, "Find all the observations for patient with a name including peter that have a LOINC code that have a LOINC code 1234-5 ": ":

GET [base]/Observation?name=http://loinc.org|1234-5&subject.name=peter
Using
the

Using the _filter parameter, the search would be expressed like this: parameter, the search would be expressed like this:

GET [base]/Observation?_filter=name eq http://loinc.org|1234-5 and subject.name co "peter"
The

The _filter parameter is described in detail on the "_Filter Parameter" page . parameter is described in detail on the "_Filter Parameter" page .

2.42.1.4.20 Specifying the type of Resource

Normally, a search is initiated against a known type of resource, e.g.

GET [base]/Observation?params...

However in some circumstances, a search is executed where there is no fixed type of resource:

• Using search across all resource types (GET [base]?params...)
• Using search with messaging
• Some search specifications inside other services e.g. decision support usage

In these circumstances, the search criteria may need to specify one or more resource types that the search applies to. This can be done by using the _type parameter:

GET [base]/Observation?_type=Observation,Condition&other params...

Note that the only search parameters that be can be used in global search like this are the base parameters that apply to all resources. In other contexts, searches on multiple types may allow resource specific search parameters, but implementation experience will be required to determine the correct behaviour in these cases.

2.1.1.5 Managing Returned Resources 2.42.1.5 Managing Returned Resources

2.1.1.5.1 Sorting 2.42.1.5.1 Sorting The client can indicate which order to return the results by using the parameter _sort , which can have a value of one of the search parameters. The _sort parameter can repeat to indicate sort order, with the repeats indicating a lower sort priority sequentially. The

The client can indicate which order to return the results by using the parameter _sort parameter takes one of two qualifiers, :asc and :desc , which specify ascending and descending sort order respectively. The default value is :asc . Note: When sorting, the actual sort value used is not returned explicitly by the server for each resource, just the resource contents. To sort by relevance, use _sort:asc=_score , which can contains a comma-separated list of sort rules in priority order:

GET [base]/Observation?_sort=status,-date,category

Each item in the comma separated list is a search parameter, optionally with a '-' prefix. The prefix indicates decreasing order; in it's absence, the parameter is applied in increasing order.

Notes:

• When sorting, the actual sort value used is not returned explicitly by the server for each resource, just the resource contents.
• To sort by relevance, use _score . The server returns the sort it performs as part of the returned search parameters (see
• The server returns the sort it performs as part of the returned search parameters (see below ). A search parameter can refer to an element that repeats, and therefore there can be multiple values for a given search parameter for a single resource. In this case, the sort is based on the item in the set of multiple parameters that comes earliest in the specified sort order when ordering the returned resources. When sorting on string search parameters, sorting SHOULD be performed on a case-insensitive basis. Accents may either be ignored or sorted as per realm convention. Note: Consistency of sorting across servers isn't as essential as consistency of filtering (even that is variable). The purpose of sorting is to provide data in a "reasonable" order for end-users. "Reasonable" may vary by realm, particularly for accented characters.
• A search parameter can refer to an element that repeats, and therefore there can be multiple values for a given search parameter for a single resource. In this case, the sort is based on the item in the set of multiple parameters that comes earliest in the specified sort order when ordering the returned resources.
• When sorting on string search parameters, sorting SHOULD be performed on a case-insensitive basis. Accents may either be ignored or sorted as per realm convention. Note: Consistency of sorting across servers isn't as essential as consistency of filtering (even that is variable). The purpose of sorting is to provide data in a "reasonable" order for end-users. "Reasonable" may vary by realm, particularly for accented characters.

2.1.1.5.2 Page Count 2.42.1.5.2 Page Count In order to keep the load on clients, servers and the network minimized, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links . Typically, a server will provide its own parameters in the links that it uses to manage the state of the search as pages are retrieved. These parameters do not need to be understood or processed by the client. The parameter

In order to keep the load on clients, servers and the network minimized, the server may choose to return the results in a series of pages. The search result set contains the URLs that the client uses to request additional pages from the search set. For a simple RESTful search, the page links are contained in the returned bundle as links .

Typically, a server will provide its own parameters in the links that it uses to manage the state of the search as pages are retrieved. These parameters do not need to be understood or processed by the client.

The parameter _count is defined as a hint to the server regarding how many resources should be returned in a single page. Servers SHALL NOT return more resources than requested, even if they don't support paging, but are allowed to return less than the client requested. The server should repeat the original is defined as a hint to the server regarding how many resources should be returned in a single page. Servers SHALL NOT return more resources than requested, even if they don't support paging, but are allowed to return less than the client requested. The server should repeat the original _count parameter in its returned page links so that subsequent paging requests honor the original parameter in its returned page links so that subsequent paging requests honor the original _count . Note: It is at the discretion of the search engine as to how to handle ongoing updates to the resources while the search is proceeding. Note: The combination of . Note: It is at the discretion of the search engine as to how to handle ongoing updates to the resources while the search is proceeding.

Note: The combination of _sort and and _count can be used to return only the latest resource that meets a particular criteria - set the critera, and then sort by date in descending order, with can be used to return only the latest resource that meets a particular criteria - set the criteria, and then sort by date in descending order, with _count=1 . This way, the last matching resource will be returned. . This way, the last matching resource will be returned.

if _count has the value 0, this shall be treated the same as _summary=count : the server resturns a bundle that reports the total number of resources that match in Bundle.total, but with no entries, and no prev/next/last links. Note that the Bundle.total only include the total number of matching resources. It does not count extra resources such as OperationOutcome or included resources that may also be returned.

2.1.1.5.3 Including other resources in result ( 2.42.1.5.3 Including other resources in result ( _include and and _revinclude ) ) Clients may request that the engine return resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources. This is useful when the client is searching on a clinical resource, but for every such resource returned, the client will also need the subject (patient) resource that the clinical resource refers to. The client can use the

Clients may request that the engine return resources related to the search results, in order to reduce the overall network delay of repeated retrievals of related resources. This is useful when the client is searching on a clinical resource, but for every such resource returned, the client will also need the subject (patient) resource that the clinical resource refers to. The client can use the _include parameter to indicate that the subject resources be included in the results. An alternative scenario is where the client wishes to fetch a particular resource, and any resources that refer to it. For example, the client may wish to fetch a MedicationOrder, and any provenance resources that refer to the prescription. This is known as a reverse include, and is specified by providing a parameter to indicate that the subject resources be included in the results. An alternative scenario is where the client wishes to fetch a particular resource, and any resources that refer to it. For example, the client may wish to fetch a MedicationOrder, and any provenance resources that refer to the prescription. This is known as a reverse include, and is specified by providing a _revinclude parameter. Both parameter.

Both _include and and _revinclude are based on search parameters, rather than paths in the resource, since joins, such as are based on search parameters, rather than paths in the resource, since joins, such as chaining , are already done by search parameter. Each , are already done by search parameter.

Each _include parameter specifies a search parameter to join on: parameter specifies a search parameter to join on:

 GET [base]/MedicationOrder?_include=MedicationOrder:patient&criteria...
 GET [base]/MedicationOrder?_revinclude=Provenance:target&criteria...
The
first
search
requests
all
matching
MedicationOrders,
to
include
any
patient
that
the
medication
prescriptions
in
the
result
set
refer
to.
The
second
search
requests
all
matching
prescriptions,
return
all
the
provenance
resources
that
refer
to
them.
Parameter
values
for
both

The first search requests all matching MedicationOrders, to include any patient that the medication prescriptions in the result set refer to. The second search requests all matching prescriptions, return all the provenance resources that refer to them.

Parameter values for both _include and 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 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 (Optional) A specific of type of target resource (for when the search parameter refers to multiple possible target types)
3. (Optional) A specific of type of target resource (for when the search parameter refers to multiple possible target types)

_include and _reverseInclude parameters do not include multiple values. Instead, the parameters are repeated for each different include criteria. For each returned resource, the server identifies the resources that meet the criteria expressed in the join, and adds to the results, with the and _revInclude parameters do not include multiple values. Instead, the parameters are repeated for each different include criteria.

For each returned resource, the server identifies the resources that meet the criteria expressed in the join, and adds to the results, with the entry.status set to "include" (in some searches, it is not obvious which resources are matches, and which are includes). The inclusion process can be recursive, if the modifier :recurse is included. For example, this search returns all Medication Prescription resources and their prescribing Practitioner Resources for the matching Medication Dispense resources: set to "include" (in some searches, it is not obvious which resources are matches, and which are includes).

The inclusion process can be recursive, if the modifier :recurse is included. For example, this search returns all Medication Prescription resources and their prescribing Practitioner Resources for the matching Medication Dispense resources:

GET [base]/MedicationDispense?_include=MedicationDispense:authorizingPrescription
    &_include:recurse=MedicationOrder.prescriber&criteria...
This
technique
applies
to
circular
relationships
as
well.
For
example,
the
first
of
these
two
searches
includes
any
related
observations
to
the
target
relationships,
but
only
those
directly
related.
The
second
search
asks
for
the

    &_include:recurse=MedicationOrder:prescriber&criteria...

This technique applies to circular relationships as well. For example, the first of these two searches includes any related observations to the target relationships, but only those directly related. The second search asks for the _include based on related parameter to be executed recursively, so it will retrieve observations that are directly related, and also any based on related observations to any other included observation. parameter to be executed recursively, so it will retrieve observations that are directly related, and also any related observations to any other included observation.

GET [base]/Observation?_include=Observation:related-target&criteria...
GET [base]/Observation?_include:recurse=Observation.related-target&criteria...
Both

GET [base]/Observation?_include:recurse=Observation:related-target&criteria...

Both _include and _reverseInclude use the wild card "*" for the search parameter name, indicating that any search parameter of type=reference be included. Though though both clients and servers need to take care not to request or return too many resources when doing this. Most notably, using recursive inclusions might lead to the retrieval of the full patient's record, or even more: resources are organized into an interlinked network and broad and _revInclude use the wild card "*" for the search parameter name, indicating that any search parameter of type=reference be included. Though though both clients and servers need to take care not to request or return too many resources when doing this. Most notably, using recursive inclusions might lead to the retrieval of the full patient's record, or even more: resources are organized into an interlinked network and broad _include paths may eventually traverse all possible paths on the server. For servers, these recursive and wildcard paths may eventually traverse all possible paths on the server. For servers, these recursive and wildcard _include s are demanding and may slow the search response time significantly. It is at the server's discretion how deep to recursively evaluate the inclusions. Servers are expected to limit the number of iterations done to an appropriate level and are not obliged to honor requests to include additional resources in the search results. When search results are paged, each page of search results should include the matching includes for the resources in each page, so that each page stands alone as a coherent package. s are demanding and may slow the search response time significantly.

It is at the server's discretion how deep to recursively evaluate the inclusions. Servers are expected to limit the number of iterations done to an appropriate level and are not obliged to honor requests to include additional resources in the search results.

When search results are paged, each page of search results should include the matching includes for the resources in each page, so that each page stands alone as a coherent package.

2.1.1.5.4 Contained Resources 2.42.1.5.4 Contained Resources By default, search results only include resources that are not contained in other resources. A chained condition will be evaluated inside contained resources. To illustrate this, consider a MedicationOrder resource that has a contained Medication resource specifying a custom formulation that has ingredient that has a value Substance/x23 . In this case, a search: GET MedicationOrder?medication.ingredient=Substance/x23 will include the MedicationOrder resource in the results. However, this search: GET Medication?ingredient=Substance/x23 will not include the contained Medication resource in the results, since either the wrong type of resource would be returned, or the contained resource would be returned without its container resource, which provides context to the contained resource. Clients are able to modify this behavior using the

By default, search results only include resources that are not contained in other resources. A chained condition will be evaluated inside contained resources. To illustrate this, consider a MedicationOrder resource that has a contained Medication resource specifying a custom formulation that has ingredient with a itemCodeableConcept "abc" in "htp://acme.com./medications". In this case, a search:

GET MedicationOrder?medication.ingredient-code=abc

will include the MedicationOrder resource in the results. However, this search:

GET Medication?ingredient-code=abc

will not include the contained Medication resource in the results, since either the wrong type of resource would be returned, or the contained resource would be returned without its container resource, which provides context to the contained resource.

Clients are able to modify this behavior using the _contained parameter, which can have one of the following values: false (default): Do not return contained resources true: return only contained resources both: return both contained and non-contained (normal) resources When contained resources are being returned, the server should return either the container resource, or the contained resource alone. The client can specify which by using the parameter, which can have one of the following values:

• false (default): Do not return contained resources
• true: return only contained resources
• both: return both contained and non-contained (normal) resources

When contained resources are being returned, the server should return either the container resource, or the contained resource alone. The client can specify which by using the _containedType parameter, which can have one of the following values: container (default): Return the container resources contained: return only the contained resource When returning a container resource, the server simply puts this in the search results: parameter, which can have one of the following values:

• container (default): Return the container resources
• contained: return only the contained resource

When returning a container resource, the server simply puts this in the search results:

<Bundle>
  ...
  <entry>
    <resource>
      <MedicationOrder>
        <id value="23">
        ....
        <contained>
          <Medication>
            <id value="m1">
            ...
          </Medication>
        <contained>

      </MedicationOrder>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>
In
the
case
of
returning
container
resources,
the
server
SHALL
populate
the
entry.search.mode
element
so
that
the
client
can
pick
apart
matches
and
includes
(the
usual
approach
of
doing
it
by
type
may
not
work).
If
the
return
type
is
the
contained
resource,
this
must
be
done
slightly
differently:

In the case of returning container resources, the server SHALL populate the entry.search.mode element, as shown, so that the client can pick apart matches and includes (since the usual approach of doing it by type may not work).

If the return type is the contained resource, this must be done slightly differently:

<Bundle>
  ...
  <entry>
    <fullUrl value="http://example.com/fhir/MedicationOrder/23#"/>

    <fullUrl value="http://example.com/fhir/MedicationOrder/23#m1"/>

    <resource>
      <Medication>
        <id value="m1">
        ...
      </Medication>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>
In
this
case,
the
fullUrl
informs
the
client
that
this
is
a
contained
resource,
and
the
identity
of
the
containing
resource.

In this case, the fullUrl informs the client that this is a contained resource, along with indicating the identity of the containing resource.

2.1.1.5.5 External References 2.42.1.5.5 External References If the

If the _include path selects a reference that refers to a resource on another server, the server can elect to include that resource in the search results for the convenience of the client. If the path selects a reference that refers to a resource on another server, the server can elect to include that resource in the search results for the convenience of the client.

If the _include path selects a reference that refers to an entity that is not a Resource, such as an image attachment, the server may also elect to include this in the returned results as a path selects a reference that refers to an entity that is not a Resource, such as an image attachment, the server may also elect to include this in the returned results as a Binary resource. For example, the include path may point to an attachment which is by reference, like this: resource. For example, the include path may point to an attachment which is by reference, like this:

 <content>
   <contentType>image/jpeg</contentType>
   <url>http://example.org/images/2343434/234234.jpg</url>
 </content>
The
server
can
retrieve
the
target
of
this
reference,
and
add
it
to
the
results
for
the
convenience
of
the
client.
DSTU
Note:
Should
additional
rules
about
how

The server can retrieve the target of this reference, and add it to the results for the convenience of the client.

DSTU Note: Should additional rules about how _include works be made? Feedback based on implementation experience is sought here works be made?

Feedback based on implementation experience is sought here . .

2.1.1.5.6 2.42.1.5.6 Paging Paging When returning paged results for a search with

When returning paged results for a search with _include resources, all resources, all _include resources that are related to the primary resources returned for the page SHOULD also be returned as part of that same page, even if some of those resource instances have previously been returned on previous pages. This approach allows both sender and receiver to avoid caching results of other pages. resources that are related to the primary resources returned for the page SHOULD also be returned as part of that same page, even if some of those resource instances have previously been returned on previous pages. This approach allows both sender and receiver to avoid caching results of other pages.

2.1.1.5.7 Summary 2.42.1.5.7 Summary The client can request the server to return a portion of the resources by using the parameter

The client can request the server to return a portion of the resources by using the parameter _summary : :

   GET [base]/ValueSet?_summary=true
The

The _summary parameter requests the server to return a subset of the resource. It can contain one of the following values: parameter requests the server to return a subset of the resource. It can contain one of the following values:

The intent of the _summary parameter is to reduce the total processing load on server, client, and resources between them such as the network. It is most useful for resources that are large, particularly ones that include images or elements that may repeat many times. The purpose of the summary form is to allow a client to quickly retrieve a large set of resources, and let a user pick the appropriate one. The summary for an element is defined to allow a user to quickly sort and filter the resources, and typically omit important content on the basis that the entire resource will be retrieved when the user selects a resource. Servers are not obliged to return just a summary as requested. There are only a limited number of summary forms defined for resources in order to allow servers to store the summarized form(s) in advance. Servers SHOULD mark the resources with the tag parameter is to reduce the total processing load on server, client, and resources between them such as the network. It is most useful for resources that are large, particularly ones that include images or elements that may repeat many times. The purpose of the summary form is to allow a client to quickly retrieve a large set of resources, and let a user pick the appropriate one. The summary for an element is defined to allow a user to quickly sort and filter the resources, and typically omit important content on the basis that the entire resource will be retrieved when the user selects a resource.

Servers are not obliged to return just a summary as requested. There are only a limited number of summary forms defined for resources in order to allow servers to store the summarized form(s) in advance. Servers SHOULD mark the resources with the tag SUBSETTED to ensure that the incomplete resource is not acidentally used to overwrite a complete resource. to ensure that the incomplete resource is not acidentally used to overwrite a complete resource.

Note that the _include and _revinclude parameters cannot be mixed with _summary=text .

2.1.1.5.8 Elements 2.42.1.5.8 Elements If one of the summary views defined above is not appropriate, a client can request a specific set of elements be returned as part of a resource using the

If one of the summary views defined above is not appropriate, a client can request a specific set of elements be returned as part of a resource using the _elements parameter: parameter:

   GET [base]/Patient?_elements=identifier,active,link
The

The _elements parameter consists of a comma separated list of base element names such as, elements defined at the root level in the resource. Only elements that are listed are to be returned. Clients SHOULD list all mandatory elements in a resource as part of the list of elements. The list of elements does not apply to included resources . Servers are not obliged to return just the requested elements. Servers SHOULD always return mandatory elements whether they are requested or not. Servers SHOULD mark the resources with the tag parameter consists of a comma separated list of base element names such as, elements defined at the root level in the resource. Only elements that are listed are to be returned. Clients SHOULD list all mandatory and modifier elements in a resource as part of the list of elements. The list of elements does not apply to included resources .

Servers are not obliged to return just the requested elements. Servers SHOULD always return mandatory elements whether they are requested or not. Servers SHOULD mark the resources with the tag SUBSETTED to ensure that the incomplete resource is not actually used to overwrite a complete resource. to ensure that the incomplete resource is not actually used to overwrite a complete resource.

2.1.1.5.9 Relevance 2.42.1.5.9 Relevance Where a search specifies a non-deterministic sort, the search algorithm may generate some kind of ranking score to indicate which resources meet the specified criteria better than others. The server can return this score in

Where a search specifies a non-deterministic sort, the search algorithm may generate some kind of ranking score to indicate which resources meet the specified criteria better than others. The server can return this score in entry.score : :

  <entry>
    <score value=".45"/>
    <Patient>
      ... patient data ...
    </Patient>
  </entry>
The
score
is
a
decimal
number
with
a
value
between
(and
including)
0
and
1,
where
1
is
best
match,
and
0
is
least
match.

The score is a decimal number with a value between (and including) 0 and 1, where 1 is best match, and 0 is least match.

2.1.1.6 Server Conformance 2.42.1.6 Server Conformance In order to allow the client to be confident about what search parameters were used as criteria by the server, the server SHALL return the parameters that were actually used to process the search. Applications processing search results SHALL check these returned values where necessary. For example, if the server did not support some of the filters specified in the search, a client might manually apply those filters to the retrieved result set, display a warning message to the user or take some other action. In the case of a RESTful search, these parameters are encoded in the self link in the bundle that is returned:

In order to allow the client to be confident about what search parameters were used as criteria by the server, the server SHALL return the parameters that were actually used to process the search. Applications processing search results SHALL check these returned values where necessary. For example, if the server did not support some of the filters specified in the search, a client might manually apply those filters to the retrieved result set, display a warning message to the user or take some other action.

In the case of a RESTful search, these parameters are encoded in the self link in the bundle that is returned:

  <link>
    <relation value="self"/>
    <url value="http://example.org/Patient?name=peter"/>
  </link>
In
other
respects,
servers
have
considerable
discretion
with
regards
to
supporting
search:
Servers
can
choose
which
parameters
to
support
(other
than

In other respects, servers have considerable discretion with regards to supporting search:

• Servers can choose which parameters to support (other than _id above). Servers can choose when and where to implement parameter chaining, and when and where they support the above).
• Servers can choose when and where to implement parameter chaining, and when and where they support the _include parameter. Servers are able to declare additional parameters in the profiles referenced from their conformance statements. Servers should define search parameters starting with a "-" character to ensure that the names they choose do not clash with future parameters defined by this specification. Servers are not required to enforce case sensitivity on parameter names, though the names are case sensitive (and URLs are generally case-sensitive). Servers may choose how many results to return, though the client can use parameter.
• Servers are able to declare additional parameters in the profiles referenced from their conformance statements. Servers should define search parameters starting with a "-" character to ensure that the names they choose do not clash with future parameters defined by this specification.
• Servers are not required to enforce case sensitivity on parameter names, though the names are case sensitive (and URLs are generally case-sensitive).
• Servers may choose how many results to return, though the client can use _count as above Servers can choose how to sort the return results, though they SHOULD honor the as above
• Servers can choose how to sort the return results, though they SHOULD honor the _sort parameter. parameter.

2.1.1.7 Advanced Search 2.42.1.7 Advanced Search The search framework described above is a useful framework for providing a simple search based on indexed criteria, but more sophisticated query capability is needed to handle precise queries, complex decision support based requests, and direct queries that have human resolution. More advanced search operations are specified by the

The search framework described above is a useful framework for providing a simple search based on indexed criteria, but more sophisticated query capability is needed to handle precise queries, complex decision support based requests, and direct queries that have human resolution.

More advanced search operations are specified by the _query parameter: parameter:

   GET [base]/Patient?_query=name&parameters...
The

The _query parameter names a custom search profile that describes a specific query operation. The named query may define additional named parameters that are used with that particular named query. Servers can define their own additional named queries to meet their own uses using an parameter names a custom search profile that describes a specific query operation. The named query may define additional named parameters that are used with that particular named query. Servers can define their own additional named queries to meet their own uses using an OperationDefinition . There can only ever be one .

There can only ever be one _query parameter in a set of search parameters. Servers processing search requests SHALL refuse to process a search request if they do not recognize the parameter in a set of search parameters. Servers processing search requests SHALL refuse to process a search request if they do not recognize the _query parameter value. parameter value.

2.1.1.8 Search Result Currency 2.42.1.8 Search Result Currency The results of a search operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results. This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding. Note: Performing a search operation does not change the set of resources on the server, with the exception of the creation of Audit Event resources auditing the search itself.

The results of a search operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.

This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding.

Note: Performing a search operation does not change the set of resources on the server, with the exception of the creation of Audit Event resources auditing the search itself.

2.1.1.9 Summary Tables 2.42.1.9 Summary Tables

Cross-map between search parameter types and Data types: