This page is part of the FHIR Specification (v5.0.0: R5 (v4.0.1: R4 - Mixed Normative and STU ). This is the ) in it's permanent home (it will always be available at this URL). The current published version. version which supercedes this version is 5.0.0 . For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

3.2.1 3.1.1 Search

FHIR Infrastructure Work Group

Maturity Level : Normative

Standards Status : Normative

This page has been approved as part of an ANSI standard. See the Infrastructure Package for further details.

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. Servers SHALL declare what features of search they require through their CapabilityStatement search declarations , and clients are encouraged to do this too.

3.2.1.1 3.1.1.1 Contents Summary Table

In addition, there is a typical RESTful interface, collections of instances are returned as arrays of a type. In order to include related information (e.g., number of total results), support extended functionality (e.g., paging), and allow multiple resource types in results (e.g., returning Patient and Encounter resources), FHIR Search instead returns a Bundle resource, with a type of searchset . Resources included in the results appear as individual entries in such a bundle. Note that the special search parameters _format _query parameter works for search like for other interactions . More information about returned contents and elements can be found in Managing Returned Resources There are safety issues associated with the implementation of searching that implementers should always keep in mind. Implementers SHOULD review the safety checklist . 3.2.1.2.1 Search Overview and _filter Though search operations are typically performed via REST, search is defined to be useful independently of HTTP. Note that while different formats of search requests are functionally equivalent, there MAY be differences inherent to searching via a particular protocol. Details can be found on the Search section allow for an alternative method of searching, and the HTTP page. 3.2.1.2.2 Search Inputs Input to search operations are referred to as Search Parameters . A search parameter can be: a filter across all resources (e.g., parameters _id , which is present on every resource), a filter on a specific resource (e.g., _format and Patient.birthDate , which applies to the Patient resource,) a textual search across a resource, or a parameter that affects search results _pretty defined for all interactions .

There Also, there is a single page that lists all the search parameters published with this specification. . Note that search parameter names are case sensitive, though this specification never defines different parameters with names that differ only in case. Clients SHOULD use correct case, and servers SHALL NOT not define additional parameters with different meanings with names that only differ in case.

Order of operations is not driven by order in the URL - There are several safety issues associated with the exception implementation of sort. First all filters are applied, then searching that implementers should always keep in mind.

3.1.1.2 Introduction

In the result set is sorted, then paging simplest case, a search is applied, and then included resources ( _include , executed by performing a _revinclude GET ) 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 added a series of name=[value] pairs encoded in the URL or as an application/x-www-form-urlencoded submission for each page. a POST:

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

The server determines which of their the set of resources it serves meet the criteria contained specific criteria, and returns the results in the search parameters HTTP response 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 bundle which includes the search set is indeterminate: Patient MPI Search . In resources that are the absence of any search filters, e.g. GET [base] , GET [base]/Patient , or POST [base]/_search or POST [base]/Patient/_search with no body, a server SHOULD return all records in scope results of the search context. Servers MAY reject a search as overly-broad, and SHOULD return an appropriate error in search. Note that situation (e.g., too-costly ). For more information about how the _format parameter works for search inputs are tested against resources, please see Search Parameters 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 compartment , perhaps with a specified resource type in that compartment: GET [base]/Patient/[id]/[type]?parameter(s)
• All resource types: Note that if the _type GET [base]?parameter(s) (parameters common to all types). If the _type parameter is included, all other search parameters SHALL be common to all provided types, and if types. If _type is not included, all parameters SHALL be common to all resource types. Show as: HTTP GET | HTTP POST GET [base]?parameter(s) POST [base]/_search Content-Type: application/x-www-form-urlencoded parameter(s) A specified resource type: Show as: HTTP GET | HTTP POST GET [base]/[type]?parameter(s) POST [base]/[type]/_search Content-Type: application/x-www-form-urlencoded parameter(s) A specified compartment , perhaps with a specified resource type in that compartment. Note that the literal * (asterisk) is valid as the [type] in a GET-based compartment search. This syntax is for disambiguation between an instance read and a compartment search, which would otherwise share the same URL. Show as: HTTP GET | HTTP POST GET [base]/[compartment]/[id]/[type]?parameter(s) POST [base]/[compartment]/[id]/[type]/_search Content-Type: application/x-www-form-urlencoded parameter(s)

Search responses are always returned as a Bundle . Search result bundles convey a lot of metadata in addition to any possible results, using the various elements available operations can also be implemented in the bundle resource. messaging framework .

The response to any search operation is always a list server determines which of their resources in a Bundle. An alternative approach is to use GraphQL . 3.2.1.3.1 Bundle Type Search result bundles will always have the Bundle.type of searchset . This element and value designate that meet the bundle is a search response and MAY be used criteria contained in processing to indicate 3.2.1.3.2 Self Link - Understanding a Performed Search In order to allow the client to be confident about what search parameters were used as criteria by a server, servers SHALL return described below. However, the parameters that were actually used server has the prerogative to process a search. Applications processing return additional search results SHALL check these returned values where necessary. For example, if a 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. These parameters are encoded in the self link of the returned bundle - a bundle.link with the relation set it believes them to self : Show as: FHIR+JSON | FHIR+XML { "resourceType": "Bundle", "type": "searchset", ... "link": { "relation": "self", "url": "http://example.org/Patient?name=peter" } ... } <Bundle> <type value="searchset"/> ... <link> <relation value="self"/> <url value="http://example.org/Patient?name=peter"/> </link> ... </Bundle> Self links SHALL be expressed as an HTTP GET-based search with the relevant parameters included as query parameters, because of the semantics around the link types TU . This means that the same self link relevant. Note: There is a valid response for any equivalent search, regardless of how a search is performed (e.g., HTTP GET, HTTP POST, Messaging, etc.). Self links MAY be returned as absolute URIs or URIs relative to the base URL of a server, and MAY or MAY NOT be resolvable TU . A server that does not support search via GET will return links in the same style as a server that does not support search via POST. Note that this makes the self link special in the context of bundle links, as all other links are intended to be resolvable by a client. Clients SHALL review the returned parameters in the self link to ensure proper processing of results. Generally, ignored parameters will result in clients receiving more results than intended. In those situations, clients SHOULD filter received records to account search for additional data TU . 3.2.1.3.3 Other Links - Paging In addition to the self link, many bundles MAY contain links most relevant to paging. These are identified via the relation value context in which the links. Common links include: first , last , next , and prev . search set is indeterminate: Patient MPI Search .

As with the self link, all relevant paging links SHALL be expressed as Search using GET requests TU . Servers SHOULD NOT may include content that is considered sensitive information in the URLs TU . 3.2.1.3.4 Matches, Inclusions, search parameters. Therefore, secure communications and Outcomes - Bundle Entries Within the results bundle, there endpoint management are three types of entries that MAY be present, identified by the search mode recommended, see Security Communications of the entry: match , include , or outcome .

Note that entries are unique (not allowed The response to repeat) and there is only one mode per entry. In some corner cases, a resource may be included because it is both a match and an include . In these circumstances, match takes precedence. 3.2.1.3.4.1 Match Entries marked with match in any search results indicate that a record operation is being returned because it meets the parameters specified in the search request (e.g., always a record the client requested). 3.2.1.3.4.2 Include Entries marked with include list of resources in search results indicate that a record is being returned either because it is referred to from a record in the result set or that the server believes Bundle. An alternative approach is useful or necessary for the client to process other results. 3.2.1.3.4.3 Outcome Entries marked with outcome in search results are OperationOutcome resources with information related to the processing of a search. For example, a server MAY use an outcome record to report to a client that a search was unacceptable TU . GraphQL .

3.2.1.3.5 3.1.1.3 Handling Errors

If a server is unable to execute a search request, it MAY either return an error for the request or may return success with an outcome containing details of the error TU . error. A HTTP status code of 403 signifies that the server refused to perform the search, while other 4xx and 5xx 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 that an Note: An empty search result is not an error. a failure.

In some cases, parameters may cause an error, or might not be able to match anything. For instance:

• A parameter may refer to a non-existent resource, such as if no Observation with an id of "101" exists resource e.g. GET [base]/Observation?_id=101 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _id=101 [base]/Observation?subject=101 , where "101" does not exist
• A parameter may reference refer to a non-existent resource, such as if resource e.g. GET [base]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456 , where there is no Patient with patient for MRN "1234" exists GET [base]/Observation?patient.identifier=http://example.com/fhir/mrn|1234 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded patient.identifier=http://example.com/fhir/mrn|1234 123456
• A parameter may refer to an unknown code, such as if code e.g. GET [base]/Observation?code=loinc|1234-1 , where the LOINC code "1234-1" is not known to the server GET [base]/Observation?code=loinc|1234-1 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=loinc|1234-1
• A parameter may refer to a time that is out of scope, such as if scope e.g. GET [base]/Condition?onset=le1995 , where the system only has data going back to 2001 GET [base]/Condition?onset=le1995 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded onset=le1995
• A parameter may use an illegal or unacceptable modifier, such as if modifier e.g. GET [base]/Condition?onset:text=1995 , where the modifier cannot be processed by the server GET [base]/Condition?onset:text=1995 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded onset:text=1995
• A data time parameter may have incorrect format, such as if the modifier cannot be processed by the server format e.g. GET [base]/Condition?onset=23%20May%202009 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded onset=23%20May%202009
• A parameter may be unknown or unsupported (more details (see below) GET [base]/Condition?myInvalidParameter=true POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded myInvalidParameter=true

Note: Empty parameters are not an error - they are just ignored by the server.

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 a search mode of = outcome . Clients can use this information to improve future searches. If, for example, a client performed the following search: Show as: HTTP GET | HTTP POST GET [base]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded patient.identifier=http://example.com/fhir/identifier/mrn|123456

GET [base]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456

and there is no patient for MRN 123456, the server may would return a bundle with no results and a warning outcome, such as this .

Unknown and unsupported parameters

Servers may receive parameters from the client that they do not recognize, or may receive parameters they recognize 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 examining the self link in the return (see below )

Clients can specify how the server should behave, by using the prefer header: header

• Prefer: handling=strict : handling=strict: Client requests that the server return an error for any unknown or unsupported parameter
• Prefer: handling=lenient : 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. For more information, see HTTP Headers on the HTTP Page.

3.2.1.4 3.1.1.4 Transport Protocols Standard Parameters

3.2.1.4.1 3.1.1.4.1 Multi-datastore Considerations Parameters for all resources

Some servers expose a FHIR endpoint that actually represents multiple data stores. For example, a system might expose a single Observation endpoint, even though internally there are distinct systems for labs, vitals, clinical assessments, and symptoms. Alternatively, a system might expose a single Patient endpoint even though it is backed by multiple distinct Patient repositories. The following parameters apply to all resources : _content , _id , _lastUpdated , _profile , _query , _security , _source , _tag . In these "single endpoint/multiple back-end" scenarios, it is possible that addition, the internal repositories have different capabilities when it comes search parameter _text and _filter , (documented below) also applies to search. all resources (as do the search result parameters).

At present, there is no standard way The search parameter _id refers to declare such limitations as part of the CapabilityStatement , other than through custom extensions. A future release logical id of FHIR could provide the resource, and can be used when the search context specifies a more standard way of performing such declarations. resource type:

 GET [base]/Patient?_id=23

In any event, systems can handle such limitations in at least four ways: By requiring that some searches include certain mandatory criteria. For example, Observation searches might require that This search finds the category parameter be present (and patient resource with the given id (there can only have be one value) or Patient searches might require that resource for a given id). Functionally, this is equivalent to a simple read operation :

 GET [base]/Patient/23

However, the search with parameter organization _id parameter be present. These permitted combinations returns a bundle with the requested resource, instead of just the resource itself. Additional parameters can be conveyed by extensions added which may provide additional functionality on the top of this base read equivalence (e.g. CapabilityStatement . Clients _include ). Note that fail to satisfy the 'combination' rules will not be able to search successfully. By having although the intermediary _id parameter has a type of token, because servers SHALL use exact match with it, there is no system that handles for the dispatch to different back ends perform supplementary filtering such _id parameter. Note that any matches on _id are always case sensitive.

The search parameters that cannot parameter _lastUpdated can be enforced by the back-end system are instead applied at the intermediary layer, and thus from a 'client' perspective used to select resources based on the last time they were changed:

 GET [base]/Observation?_lastUpdated=gt2010-10-01

This search was executed as desired. By returning a warning message in 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 ).

The search OperationOutcome parameters _tag , _profile (see also: Handling Errors and _security ) indicating that not all filters were applied parameters search on the equivalent elements in the meta element . For example,

 GET [base]/Condition?_tag=http://acme.org/codes|needs-review

searches for all resources. This SHOULD Condition resources with the tag:

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

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 occur in situations where it is known DiagnosticReport resources that some filters haven't been applied TU . By exposing distinct FHIR endpoints for each data source are tagged as conforming to a particular profile. The second reference is relative and refers a local profile on the different capabilities in an endpoint-specific manner. same server.

_tag , and _security parameters are token types (see below ), and _profile is a reference search parameter.

3.2.1.4.2 3.1.1.4.2 Batching Search Requests Parameters for each resource

Servers MAY support batching multiple requests TU . In the context of search, this allows several searches addition to be performed serially via a single request. Note that each operation of a the batch _id is independent, so it is not possible to use the results parameter which exists for all resources, each FHIR resource type defines its own set of one request as input to another in search parameters with their names, types, and meanings. These search parameters are on the same batch. page as the resource definitions, and are also published as part of the standard Capability statement ( XML or JSON ).

When submitting multiple requests via In general, the defined search parameters correspond to a batch or transaction, single element in the returned bundle resource, but this is for not required, and some search parameters refer to the batch same type of element in multiple places, or transaction as an operation. Therefore, two refer to derived values.

Some search requests parameters defined by resources are associated with more than one path in a batch would return a bundle resource. This means that contains at least two entries, each of which is the result of a search request (e.g., parameter matches if any of the batch result bundle will paths contain entries that are matching content. If a path matches, the whole resource is returned in the search result bundles). When bundling requests via batch or transaction , HTTP verbs and results. The client may have to examine the URLs for RESTful interfaces are used. When requesting searches in a bundle, systems SHOULD accept searches via GET, even if they do not typically accept GET-based searches TU . There is no standard way resource to convey POST-based searches within a Bundle and determine which path contains the architectural differences when searching via GET or POST match.

Servers are not relevant within a Bundle. Servers receiving searches within a Bundle SHOULD NOT impose required to implement any GET-specific limitations on search (i.e. restrictions not imposed on POST-based searches) that they would impose if of the GET-based standard search had been received outside a Bundle TU . 3.2.1.4.3 Search via Messaging Servers MAY support FHIR Messaging . The mapping of seach requests into messages is described in more detail in parameters (except for the section Invoking Search via Messages . _id parameter described above). Servers may also define their own parameters.

3.2.1.5 3.1.1.4.3 Search Parameters Parameter Types

While search parameters are typically transmitted as URL-Encoded strings (e.g., HTTP Parameters or x-www-form-urlencoded body content), FHIR is modeled with a rich set of primitive and complex data types to describe the data encountered in healthcare. To provide consistent mapping between the two formats, each Each search parameter is defined by a type that specifies how the search parameter behaves. These are the defined search parameter types:

Individual The search parameters MAY can also allow append "modifiers" that control their behavior. The kinds of modifiers that available depend is dependent on the type of the search parameter. More details can be found in the Modifiers section of the search page. Some search parameter types allow "prefixes" (or "comparators") which can be used to request different match-testing functionality (e.g., greater-than instead of equality). The kinds of comparators allowed depends on the type of the search parameter. More details can be found in the Prefixes section of the search page. being modified.

3.2.1.5.1 3.1.1.4.4 Search Test Basics Modifiers

Generally, an single search test can be broken down into a few parts: a search input value to test with, the type of test being used, and zero or more values from a resource to test against. For example, a search against the Patient resource for given=value is a request to a server to compare values in the given name of a patient against "value", using the default string test (see string for details). Each of these 'parts' of a search test have a lot of flexibility. Search input values Parameters are parsed according to the search parameter type, as defined in the relevant SearchParameter per resource. The rules for parsing a search input value into the equivalent FHIR type can be found on the search page (e.g., converting a token input into a Coding ). The type of test used to compare values are controlled by the search parameter type and a search modifier OR a search prefix, if present. For example, the number search parameter type describes the default search test as an equality test (i.e., {element value} equals {input value} ). A Search Modifier , such as not changes the test - in this case negating the default behavior (i.e., not({element value} equals {input value}) ). Finally, a Search Prefix , allowed on the number search type, can be used to change the test to something like a 'greater than' (i.e., {element value} is greater than {input value} ). Note that a single test cannot contain both Parameter names may specify a modifier and a prefix. 3.2.1.5.2 Matching and Cardinality Many elements in FHIR are defined as arrays (or collections) of values (e.g., a patient can have more than one name or address). When performing a search test against elements that have a cardinality of more than one, the test is considered a 'contains' type test against the collection of values. For example, if a patient has two name elements with values, a test is considered a match if at least one of the values is a match. 3.2.1.5.3 Matching and Sub-Elements When a search parameter points to a complex or backbone element (an element that contains sub-elements), by default the search is interpreted as a search against one or more values in sub-elements with an appropriate type, as selected by the implementation. A search parameter MAY instead explicitly choose elements by using an expression that instead points directly to the sub-elements TU . 3.2.1.5.4 Searching Multiple Values (joining with AND or OR) Search combination logic is defined by an equivalent set logic on the results of individual tests, performed at the resource level. "OR" joined parameters are "unions of sets" and "AND" joined parameters are "intersections of sets". Note that the joins are considered at the resource level and search parameters are unordered. This means that complex combinations of "AND" and "OR" are not possible using the basic search syntax. Uses requiring advanced combination logic should consider the use of the _filter parameter or Named Queries . When multiple search parameters passed to a single search, they are used to create an intersection of the results - in other words, multiple parameters suffix. The modifiers are joined via "AND". For example, a search for a patient that includes a given name and a family name will only return records that match BOTH: Show as: HTTP GET | HTTP POST GET [base]/Patient?given=valueGiven&family=valueFamily POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given=valueGiven&family=valueFamily will return only Patient records with a family name of "valueFamily" and a given name of "valueGiven". It is also possible to use an "AND" join repeated on the same element. When doing so, the join behavior is the same as when using different elements. For example, a search that asks for having two specific given names: Show as: HTTP GET | HTTP POST GET [base]/Patient?given=valueGivenA&given=valueGivenB POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given=valueGivenA&given=valueGivenB will return records that have BOTH a match for the given name of "valueGivenA" AND a match for the given name of "valueGivenB". Note that this will match both patient records that have a single name containing multiple given elements as well as records that have a multiple name elements that, in total , contain the values: Show as: FHIR+JSON | FHIR+XML "Patient": { "name": [{ "given": [ "valueA", "valueB" ] }] } "Patient": { "name": [{ "given": [ "valueA" ] }, { "given": [ "valueB" ] }] } <Patient> <name> <given value="valueA"/> <given value="valueB"/> </name> </Patient> <Patient> <name> <given value="valueA"/> </name> <name> <given value="valueB"/> </name> </Patient> In order to search for unions of results (values joined by "OR"), values can be separated by a comma (",") character. For example, a search for a patient with EITHER of two given names: Show as: HTTP GET | HTTP POST GET [base]/Patient?given=valueGivenA,valueGivenB POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given=valueGivenA,valueGivenB will return Patient records with EITHER a given name of "valueGivenA" OR "valueGivenB". This includes patient record that have BOTH "valueGivenA" and "valueGivenB" (e.g., inclusive or). Each value of an "OR" query MAY contain a prefix if allowed by the search type. For example, a search for a heart rate value ( LOINC 8867-4 ) outside of the 'normal resting range of adults': Show as: HTTP GET | HTTP POST GET [base]/Observation?code=http://loinc.org|8867-4&value-quantity=lt60,gt100 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=http://loinc.org|8867-4&value-quantity=lt60,gt100 will match against Observations that have the LOINC code for a Heart Rate and have a value that is EITHER less than 60 OR greater than 100. If a modifier is used on a search parameter, it applies to each value of an "OR" query. For example, searching for either of two exact given names: Show as: HTTP GET | HTTP POST GET [base]/Patient?given:exact=GivenA,GivenB POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given:exact=GivenA,GivenB will match against Patients that contain a given name of exactly "GivenA", Patients that contain a given name of exactly "GivenB", and Patients that contain both values. It is possible to combine both "AND" and "OR" type queries together in a single request. For example, a search that includes a family name and either of two given names: Show as: HTTP GET | HTTP POST GET [base]/Patient?given=valueGivenA,valueGivenB&family=valueFamily POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given=valueGivenA,valueGivenB&family=valueFamily will return records that match a family name of "valueFamily" AND a given name of either "valueGivenA" OR "valueGivenB". Note that there is not a syntax to request unions on different elements (OR joins). For example, a client that wants records with either a given OR family name of "valueName". However, it is possible to define search parameters that operate on multiple elements. For example, from the described use case of searching for a patient by any part of their name has a search parameter on Patient called name , which matches any part of a name (e.g., name=valueName ). It is also possible to define composite search parameters , which allows servers to provide this functionality. If a client wants results based on OR-joins of unrelated elements, or if there is not a combined search parameter defined or supported on a server, the results can be retrieved by issuing multiple queries, either serially or in a batch. colon. Modifiers are:

• Scalar refers to elements that have a maximum cardinality of one. Array refers to elements that have a maximum cardinality greater than one. Simple refers to elements that do not contain additional elements (e.g., Primitive Types ). Complex refers to elements that contain additional elements (e.g., HumanName , etc.) Show as: HTTP GET | HTTP POST Context Short Example AND , Scalar , Simple Intersection of records that match each of the search criteria GET [base]/Patient?death-date=ge2022-01-01&death-date=lt2023-01-01 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded death-date=ge2022-01-01&death-date=lt2023-01-01 The search is asking for patients with a death-date on or after January 1, 2022 and a death-date before January 1, 2023. The results are the intersection of patients with a deceasedDateTime on or after January 1, 2022 and patients with a deceasedDateTime before January 1, 2023. Each match will contain a single value in the requested range. OR , Scalar , Simple Union of records that match each of the search criteria GET [base]/Patient?death-date=ge2030-01-01,lt1980-01-01 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded death-date=ge2030-01-01,lt1900-01-01 The search is asking for patients with a death-date on or after January 1, 2030 or a death-date before January 1, 1900. The results are the union of patients with a deceasedDateTime on or after January 1, 2030 and patients with a deceasedDateTime before January 1, 1900. Each match will contain a single value in the requested range (e.g., checking for dates outside the allowed range). AND , Array , Simple Intersection of records that contain at least one match for each search criteria GET [base]/AllergyIntolerance?category=medication&category=biologic POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded category=medication&category=biologic The search is asking for allergies or intolerances with a category of medication and a category of biologic . The results are the intersection of AllergyIntolerance records records with each of the requested category values. Each matching record will contain at least one of each of the requested category values. OR , Array , Simple Union of records that contain at least one match for each search criteria GET [base]/AllergyIntolerance?category=medication,biologic POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded category=medication,biologic The search is asking for allergies or intolerances with a category of either medication or biologic . The results are the union of AllergyIntolerance records records with any of the requested category values. Each matching record will contain at least one of either of the requested category values, and can contain both. AND , Array , Complex Intersection of records that contain at least one match for each search criteria GET [base]/Patient?name=valueA&name=valueB POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded name=valueA&name=valueB The search is asking for patients with a name of 'valueA' a name of 'valueB'. The results are the intersection of patients that have each of the requested values in any component of their name. Each match will contain each of the requested values in some form. E.g., a patient with the given names of both 'valueA' and 'valueB' will match, as well as a patient with a given name of 'valueA' and a family name of 'valueB', etc.. OR , Array , Complex Union of records that contain at least one match for any search criteria GET [base]/Patient?name=valueA,valueB POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded name=valueA,valueB The search is asking for patients with a name of either 'valueA' or 'valueB'. The results are the union of patients with 'valueA' anywhere in their name and patients with 'valueB' anywhere in their name. Each matching record will contain at least one of the search criteria. 3.2.1.5.5 Modifiers Generally, search parameters are used as filters to refine search results based on one or more resource elements. For example, a query might find patients born in a certain year by using the birthdate search parameter, which maps to the Patient.birthDate element. Sometimes it is necessary or desirable to use a search parameter with a different behavior, for example, searching for patients that do not have a birth date in their records. Instead of requiring many search parameters on an element to cover each type of use, this specification defines modifiers that can be used to change the meaning of a search parameter while leaving element mappings intact. Search parameter modifiers are defined by the search-modifier-code code system. Search parameter definitions MAY include a list of allowed modifiers in the SearchParameter.code element, which is bound to the search-modifier-code value set. Servers SHALL support any modifiers present in search all parameters the server advertises support for. Servers MAY choose to support additional modifiers. Note that servers MAY support modifiers on types not defined in this specification. In search requests, search modifiers are used by appending the modifier as a suffix to the search parameter name, with the syntax of: [name]:[modifier] , such as birthdate:missing . Note that only a single modifier is allowed on a single search parameter. If multiple layers of modification are necessary, a new search parameter can be defined with the appropriate behavior. If the desired behavior is not possible to define in a search parameter without multiple stacked modifiers, an operation can be defined. Since modifiers change the meaning of a search parameter, a server SHALL reject any search request that contains a search parameter with an unsupported modifier. For example, if the server supports the name search parameter, but not the :exact modifier on the name, it would reject a search with the parameter name:exact=Bill , using an HTTP 400 (except combination): :missing error with an OperationOutcome with a clear error message . While support for modifiers is applied per search parameter, modifiers are generally defined according to search parameter type. For example, the ":exact" modifier has meaning when applied to string-type search parameters but has no meaning and cannot be used with token-type search parameters. The exception is the search parameters type special . The definition ; e.g. gender:missing=true (or false). Searching for any search parameter of type "special" SHALL explicitly list any allowed modifiers; this list MAY include any value from the search-modifier-code code system. The modifiers defined by this specification are: above reference , token , uri Tests whether the value in a resource is or subsumes the supplied parameter value (is-a, or hierarchical relationships). below reference , token , uri Tests whether the value in a resource is or is subsumed by the supplied parameter value (is-a, or hierarchical relationships). code-text TU reference , token Tests whether the textual display value in a resource (e.g., CodeableConcept.text , Coding.display , or Reference.display ) matches the supplied parameter value. contains string , uri Tests whether the value in a resource includes the supplied parameter value anywhere within the field being searched. exact string Tests whether the value in a resource exactly matches the supplied parameter value (the whole string, including casing and accents). identifier reference Tests whether the Reference.identifier in a resource (rather than the Reference.reference ) matches the supplied parameter value. in token Tests whether the value in a resource is a member of the supplied parameter ValueSet. iterate n/a (not allowed anywhere by default) The search parameter indicates an inclusion directive (_include, _revinclude) that is applied to an included resource instead of the matching resource. missing date , number , quantity , reference , string , token , uri 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 ). not gender:missing=true token Tests whether the value in a resource does not match will return all the specified parameter value. Note that this includes resources that don't have no value for the parameter. not-in reference TU , token Tests whether the value in a resource is not 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. text reference TU , token Tests whether the textual value in a resource (e.g., CodeableConcept.text , Coding.display , Identifier.type.text , or Reference.display ) matches the supplied parameter value using basic string matching (begins with or is, case-insensitive). text string The search parameter value should be processed as input to a search with advanced text handling. text-advanced TU reference , token Tests whether the value in a resource matches for the supplied gender parameter value using advanced text handling that searches text associated with the code/value - e.g., CodeableConcept.text , Coding.display , or Identifier.type.text . [type] reference Tests whether the value in a resource points (which usually equates to a resource of the supplied parameter type. Note: a concrete ResourceType is specified as the modifier (e.g., not having the literal :[type] , but a value such as :Patient ). Note that modifiers are allowed in searches that combine multiple terms. When using a modifier in "or" joined search parameter values, the modifier applies to ALL values present. For example, in given:exact=valueA,valueB , the exact modifier is used for both "valueA" and "valueB". Additional details can be found in the Searching Multiple Values section of the Search page. 3.2.1.5.5.1 above The above modifier allows clients to search hierarchies of data based on relationships. The above modifier is only allowed on search parameters of type reference , token , and uri . The exact semantics for use vary depending on the type of search parameter: 3.2.1.5.5.1.1 above with reference type search parameters When the above modifier is used with a reference type search parameter, the search is interpreted as a hierarchical search on linked resources of the same type, including exact matches and all children of those matches. The above modifier is only valid for circular references - that is, references that point to another instance of the same type of resource where those references establish a hierarchy. For example, the Location resource can define a hierarchy using the partOf relevant element to track locations that are inside each other (e.g., Location/A101 , a room, is partOf Location/A , a floor). Meanwhile, the Patient resource could refer to other patient resources via the link element, but no hierarchical meaning is intended. Further discussion about the requirements and uses for this type of search can be found in the section resource). Searching Hierarchies . When using the above modifier on a reference, all typically-valid search parameter reference inputs are allowed. Note that the actual Resources that establish hierarchical references and the search parameters used are listed in the Circular Resource References section of the References page. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Procedure?location:above=A101 POST [base]/Procedure/_search Content-Type: application/x-www-form-urlencoded location:above=A101 would match any Procedure resources with locations: A101 , Location/A101 , https://example.org/Location/A101 - this location by ID A100 , Location/A100 , https://example.org/Location/A100 - parent of A101, representing the first floor (A101 - A199) BuildingA , Location/BuildingA , https://example.org/Location/BuildingA - parent of A100, representing the building 'A' 3.2.1.5.5.1.2 above with canonical references When the above modifier is used with a reference against a canonical reference, the search is interpreted as a version search against the canonical resource. The format of the parameter is either [url] or [url]|[version] . This search is only allowed if the version scheme for the resource is known (e.g., a known version-scheme extension or element). Version-related search criteria against resources with unknown versioning schemes SHALL be either ignored or rejected TU . The above modifier comparison is performed as a 'greater than' against the version-scheme defined by the resource. When using the above modifier on a canonical reference, all typically-valid search parameter token inputs are allowed. Note that any vertical pipe ( | ) characters that are part of the URL must be escaped ( %7C ) - the character is used as the separator between the URL and version components of the parameter. More information can be found in the section References and Versions . 3.2.1.5.5.1.3 above with token type search parameters When the above modifier is used with a token type search parameter, the supplied token is a concept with the form [system]|[code] and the intention is to test whether the coding in a resource subsumes the specified search code. Matches to the input token concept have an is-a relationship with the coding in the resource, and this includes the coding itself. When using the above gender:missing=false modifier on a token, will return all typically-valid search parameter token inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?code:above=http://snomed.info/sct|3738000 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code:above=http://snomed.info/sct|3738000 for Observations with a code above SNOMED 'Viral hepatitis (disorder)' will match any Observation resources with codes: SNOMED 3738000 - Viral hepatitis (this code) SNOMED 235862008 - Hepatitis due to infection (parent of 'Viral hepatitis') SNOMED 128241005 - Inflammatory disease of liver (parent of 'Hepatitis due to infection') etc. SNOMED 312130009 - Viral infection by site (parent of 'Viral hepatitis') SNOMED 301810000 - Infection by site (parent of 'Viral infection by site') etc. Note that there are two hierarchical parents to the requested code and parent matches traverse up each path. 3.2.1.5.5.1.4 above with uri type search parameters When the above modifier is used with have a uri type search parameter, the value is used for partial matching based on URL path segments. Because of the hierarchical behavior of above , the modifier only applies to URIs that are URLs and cannot be used with URNs such as OIDs. Note that there are not many use cases where above is useful compared to a below search. When using the above gender modifier on a uri, all typically-valid search parameter uri inputs are allowed. parameter. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/ValueSet?url:above=http://acme.org/fhir/ValueSet/123/_history/5 POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url:above=http://acme.org/fhir/ValueSet/123/_history/5 would match any ValueSet resources with a url of: http://acme.org/fhir/ValueSet/123/_history/5 - full match http://acme.org/fhir/ValueSet/123/_history - parent of requested URI http://acme.org/fhir/ValueSet/123 - ancestor of requested URI http://acme.org/fhir/ValueSet - ancestor of requested URI http://acme.org/fhir - ancestor of requested URI http://acme.org/ - ancestor of requested URI 3.2.1.5.5.2 below The below modifier allows clients to search hierarchies of simple data based on relationships. The below modifier is only allowed on search parameters of type reference , token , and uri . The exact semantics for use vary depending on the type of search parameter: 3.2.1.5.5.2.1 below with reference type search parameters - hierarchical searches When the below modifier is used with a reference type search parameter, the search is interpreted as a hierarchical search elements, :missing=true will match on linked resources of the same type, including exact matches and all children of those matches. The below modifier is only valid for circular references - that is, references that point to another instance of the same type of resource elements where those references establish a hierarchy. For example, the Location resource can define a hierarchy using the partOf element to track locations that are inside each other (e.g., Location/A101 , a room, is partOf Location/A , a floor). Meanwhile, the Patient resource could refer to other patient resources via the link element, but no hierarchical meaning is intended. Further discussion about the requirements and uses for this type of search can be found in the section Searching Hierarchies . When using the below modifier on a hierarchical reference, all typically-valid search parameter reference inputs are allowed. Note that the actual Resources that establish hierarchical references and the search parameters used are listed in the Circular Resource References section of the References page. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Procedure?location:below=BuildingA POST [base]/Procedure/_search Content-Type: application/x-www-form-urlencoded location:below=BuildingA for Procedures with a location below BuildingA would match any Procedure resources with locations: BuildingA , Location/BuildingA , https://example.org/Location/BuildingA - this location by ID A100 , Location/A100 , https://example.org/Location/A100 - child of BuildingA, representing the first floor A101 , Location/A101 , https://example.org/Location/A101 - child of A100, room 101 A1.. , etc. - child of A100, rooms on the first floor A200 , Location/A200 , https://example.org/Location/A200 - child of BuildingA, representing the second floor etc. 3.2.1.5.5.2.2 below with canonical references When the below modifier is used with a reference against a canonical reference, the search is interpreted as a version search against the canonical resource. The format of the parameter is either [url] or [url]|[version] . This search is only allowed if the version scheme for the resource underlying element is known (e.g., a known version-scheme extension or element). Version-related search criteria against resources with unknown versioning schemes SHALL be either ignored omitted or rejected TU . The below modifier comparison is performed as a 'less than' against the version-scheme defined by the resource. When using the below modifier on a canonical reference, all typically-valid search parameter token inputs are allowed. Note that any vertical pipe ( | ) characters that are part of the URL must be escaped ( %7C ) - the character is used as the separator between the URL and version components of the parameter. More information can be found in the section References and Versions . 3.2.1.5.5.2.3 below with token type search parameters When the below modifier is used with a token type search parameter, where the supplied token element is a concept present with the form [system]|[code] and the intention is to test whether the coding in a resource extensions but no @value is subsumed by the specified search code. Matches include resources that have a coding that has an is-a relationship with the input concept, and this includes the coding itself. When using the below modifier on a token, all typically-valid search parameter token inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?code:below=http://snomed.info/sct|235862008 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code:below=http://snomed.info/sct|235862008 for Observations with a code below SNOMED 'Hepatitis due to infection' would match any Observation resources with codes: SNOMED 235862008 - Hepatitis due to infection (this code)
• SNOMED 773113008 - Acute infectious hepatitis (child) SNOMED 95897009 - Amebic hepatitis (child) etc. Note that there is no limit inherent to the referential search. If child concepts contain child concepts of their own, the search continues down the tree in each path until reaching a terminal node. The below modifier is useful when trying to resolve MIME types. Further documentation can be found in the Searching MIME Types section of this page. 3.2.1.5.5.2.4 below with uri type search parameters When the below modifier is used with a uri type search parameter, the value is used for partial matching based on URL path segments. Because of the hierarchical behavior of below , the modifier only applies to URIs that are URLs and cannot be used with URNs such as OIDs. When using the below modifier on a uri, all typically-valid search parameter uri inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/ValueSet?url:below=http://acme.org/fhir POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url:above=http://acme.org/fhir would match any ValueSet resources with a url of: http://acme.org/fhir - full match http://acme.org/fhir/ValueSet - child of requested URI http://acme.org/fhir/ValueSet/123 - descendant of requested URI http://acme.org/fhir/ValueSet/123/_history - descendant of requested URI http://acme.org/fhir/ValueSet/123/_history/1 - descendant of requested URI etc. 3.2.1.5.5.3 code-text TU The code-text modifier allows clients to indicate that a supplied string string: :exact input should be matched as a case-insensitive and combining-character insensitive match against the start of target string. This modifier is used to do a 'standard' string search against code values. Note that the handling of extended grapheme clusters is within the discretion of the server, i.e. the server decides if a search parameter matches on canonically equivalent characters or matches on the actual used Unicode code points. Case-insensitive comparisons do not take locale into account, and will result in unsatisfactory results for certain locales. Character case definitions and conversions are out of scope for the FHIR standard, and the returns results of such operations are implementation dependent. code-text is only allowed on reference and token type search parameters. When using the 'code-text' modifier, all typically-valid search parameter string inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?language:code-text=en POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded language:code-text=EN would match any Patient resources with a communication language of: en - requested code text (case-insensitive) en-AU - starts with requested code text (case-insensitive) en-CA - starts with requested code text (case-insensitive) en-GB - starts with requested code text (case-insensitive) etc. 3.2.1.5.5.4 contains The contains modifier allows clients to indicate that a supplied string input should be matched as a case-insensitive and combining-character insensitive match anywhere in the target string. Note that the handling of extended grapheme clusters is within the discretion of the server, i.e. the server decides if a string search parameter matches on canonically equivalent characters or matches on the actual used Unicode code points. Case-insensitive comparisons do not take locale into account, and will result in unsatisfactory results for certain locales. Character case definitions and conversions are out of scope for the FHIR standard, and the results of such operations are implementation dependent. contains is allowed on string and uri type search parameters. When using the 'contains' modifier, all typically-valid search parameter string inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?family:contains=son POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded family:contains=son would match any Patient resources with a family names such as: Son - requested string (case-insensitive) Sonder - begins with requested string (case-insensitive) Erikson - ends with requested string (case-insensitive) Samsonite - contains requested string (case-insensitive) etc. 3.2.1.5.5.5 exact The exact modifier allows clients to indicate that a entire supplied string input is the complete and exact value that should be matched, parameter, including casing and combining characters. Note that the handling of extended (extended) grapheme clusters is within the discretion of the server, i.e. the server decides if a string search parameter matches on canonically equivalent characters characters, or matches on the actual used Unicode code points. Case-insensitive comparisons do not take locale into account, points, or :contains (case insensitive and will result combining character-insensitive, search text matched anywhere in unsatisfactory results for certain locales. Character case definitions and conversions are out the string), instead of scope for the FHIR standard, default behavior (case insensitive and accent-insensitive, partial matches at the results start of such operations are implementation dependent. exact is only allowed on string type search parameters. When using the 'exact' modifier, all typically-valid search parameter string inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?family:exact=Son POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded family:exact=Son will only match Patient resources with a family name of: Son - requested string (case-sensitive) string).
3.2.1.5.5.6 identifier The identifier modifier allows clients to indicate that a supplied token
• For token: :text should be used to (the match against the identifier element of a reference instead of the reference element. The format of the parameter is [system]|[code] . Note that chaining is not supported when using the identifier modifier and the modifier is not supported on canonical elements since they do not have an identifier separate from the reference itself. identifier is only allowed on reference type search parameters. When using the 'identifier' modifier, all typically-valid search parameter token inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?subject:identifier=http://example.org/fhir/mrn|12345 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject:identifier=http://example.org/fhir/mrn|12345 for observations with does a subject containing the identifier 'http://example.org/fhir/mrn|12345' would match Observation resources such as: Show as: FHIR+JSON | FHIR+XML "Observation": { "subject": { "reference": "Patient/abc", "identifier": { "system": "http://example.org/fhir/mrn", "value": "12345" } } } <Observation> <subject> <reference value="Patient/abc"/> <identifier> <system value="http://example.org/fhir/mrn"/> <value value="12345"/> </identifier> </subject> </Observation> but will not match: Show as: FHIR+JSON | FHIR+XML "Observation": { "subject": { "reference": "Patient/abc" } } <Observation> <subject> <reference value="Patient/abc"/> </subject> </Observation> even if the Patient resource for Patient/abc includes the requested identifier among its Patient.identifier values. For more details about the difference between the identifier modifier and chained-searches partial searches on the identifier element, see Searching Identifiers . 3.2.1.5.5.7 in The in modifier is used to filter based on value membership text portion of codes in Value Sets. The in modifier is only allowed on token type search parameters. When the in modifier is used with a token search parameter, the input is a uri (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is in the specified value set. The reference may be literal (to an address where the value set can be found) CodeableConcept or logical (a reference to ValueSet.url ). If the server can treat the reference as a literal URL, it does, else it tries to match known logical ValueSet.url values. Note that the URI need not point to the root value set, http://snomed.info/sct?fhir_vs=isa/235862008 is a valid reference to a subset display portion of SNOMED CT 'Hepatitis due to infection', but the parameter value will need to be URL Encoded in order to be a valid parameter. When using the in modifier on a token, only tokens targeting value sets are allowed (e.g., a boolean token parameter target is not allowed). For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Condition?code:in=ValueSet/123 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:in=ValueSet/123 would match any conditions that contain any code from 'ValueSet/123'. Similarly, the search: Show as: HTTP GET | HTTP POST GET [base]/Condition?code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F235862008 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F235862008 would match any conditions that contain any code from 'http://snomed.info/sct?fhir_vs=isa/235862008', e.g.: SNOMED 235862008 - Hepatitis due to infection (this code) SNOMED 773113008 - Acute infectious hepatitis (is-a 235862008) SNOMED 95897009 - Amebic hepatitis (is-a 235862008) etc. 3.2.1.5.5.8 iterate The iterate modifier is used to indicate that an inclusion directive should be applied to an included resource Coding), instead of the matching resource. Note that this modifier is not defined for any search parameter types. This modifier can only be applied to the search result parameters of _include and _revinclude . When the iterate modifier is used, the input provided is the same as the input for the inclusion directive (see Including other resources ). For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?code=http://snomed.info/sct|3738000&_include=Observation:patient&_include:iterate=Patient:link POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=http://snomed.info/sct|3738000&_include=Observation:patient&_include:iterate=Patient:link would match any observations with the SNOMED code 3738000 (Viral hepatitis (disorder)). The results would include resources from following the default search reference Observation.patient , which uses codes. Other defined modifiers are Patient resources linked via Observation.subject . Additionally, the server would iterate through the included patient records and follow the Patient.link references, including linked Patient or RelatedPerson resources. More information can be found in the section Including other resources 3.2.1.5.5.9 missing The missing modifier allows clients to filter based on whether resources contain values that can match a search parameter. Usually, this equates to testing if a resource has an element or not. missing is allowed on search parameter types that represent single-elements: date , number , quantity , reference , string , token , uri . When using the 'missing' modifier, the only valid input values are the literal values true and false . Searching for [parameter]:missing=true requests all resources that do not have a value in the matching element or where the element is present with extensions, but no value is specified. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?given:missing=true POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given:missing=true would match any Patient records that do not have any value in Patient.name that contains a value for given :in , even if a patient contains a Patient.name that has a given :below , :above with an extension and no value (e.g., a Data Absent Reason). Searching for [parameter]:missing=false requests all resources that do have a value in the matching element. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?given:missing=false POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded given:missing=false would match any Patient records that have any value in Patient.name that contains a value for given . 3.2.1.5.5.10 not The not modifier allows clients to filter based on whether resources do not contain a specified token based on the search parameter input. not :not-in is only allowed on search parameters of type token . When using the 'not' modifier, all typically-valid search parameter token inputs which are allowed. Searching for [parameter]:not=[value] requests all resources that do not have any matching value in the searched element(s). For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?gender:not=male POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded gender:not=male would match any Patient records that do not have male as the value in Patient.gender . This includes: female - Administrative Gender that is not 'male' other - Administrative Gender that is not 'male' described below.
• unknown For reference: :[type] - Administrative Gender that where [type] is not 'male' records without a Patient.gender value (even if a record has extensions, such as a Data Absent Reason) Similarly, the search: Show as: HTTP GET | HTTP POST GET [base]/Composition?section:not=48765-2 POST [base]/Composition/_search Content-Type: application/x-www-form-urlencoded Composition?section:not=48765-2 for documents without an "Allergies and adverse reaction" section ( LOINC 48765-2 ) would return all Composition records that do not contain any section with a code name of '48765-2'. This search does not return "any document that has a section that is not an Allergies and adverse reaction section". In the presence type of multiple possible matches, the negation applies to the set resource, :identifier, and, for some parameters, :above and not each individual entry. Note that the not :below
• For uri: :below,:above modifier can behave in undesirable ways with "or"-joined parameter values. Specifically, consider a query that uses a scalar (max cardinality one) value, such as: gender:not=male,female . Using the 'default' rules, the query is expanded to be the union of the sets of: patients that do not have a gender element value or that contain any value other than "male", and patients that do not have a gender element value or indicate that contain any value other than "female" - the union of those sets will always contain all records. Implementer feedback is requested on this behavior and if additional rules concerning the not modifier would be appropriate. In the meantime, use of the not modifier with "or"-joined search terms is not recommended. Implementers are instead recommended to use either the _filter parameter or Named Queries .   3.2.1.5.5.11 not-in The not-in modifier is used to filter based on a value exclusion test for codes of Value Sets. The not-in modifier is only allowed on token type search parameters. When the not-in modifier is used with a token search parameter, the input is a uri (relative or absolute) that identifies a value set, and an exact match, either the search parameter tests whether the coding is not in the specified value set. The reference may be literal (to an address where term left-matches the value set can be found) value, or logical (a reference to ValueSet.url ). If the server can treat the reference as a literal URL, it does, else it tries to match known logical ValueSet.url values. Note that the URI need not point to the root value set, http://snomed.info/sct?fhir_vs=isa/235862008 is a valid reference to a subset of SNOMED CT 'Hepatitis due to infection', but the parameter value will need to be URL Encoded in order to be a valid parameter. When using the not-in modifier on a token, only tokens targeting value sets are allowed (e.g., a boolean token parameter target is not allowed). For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Condition?code:not-in=ValueSet/123 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:not-in=ValueSet/123 would match any conditions that do not contain any code from 'ValueSet/123'. Similarly, the search: Show as: HTTP GET | HTTP POST GET [base]/Condition?code:not-in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F235862008 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:not-in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F235862008 would match any conditions that do not contain any code from 'http://snomed.info/sct?fhir_vs=isa/235862008', e.g.: SNOMED 235862008 - Hepatitis due to infection (this code) SNOMED 773113008 - Acute infectious hepatitis (is-a 235862008) SNOMED 95897009 - Amebic hepatitis (is-a 235862008) etc. vice-versa.

of-type is only allowed on Server SHALL reject any search parameters of type token , and further restricted to parameters targeting the Identifier type. When using the 'of-type' modifier, all typically-valid token values are valid for the system and code segments, and all typically-valid string values are valid for the value segment. Note request that input values MAY need to escaped in order to be processed correctly (e.g., if the 'value' contains a vertical pipe character). For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?identifier:of-type=http://terminology.hl7.org/CodeSystem/v2-0203|MR|12345 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded identifier:of-type=http://terminology.hl7.org/CodeSystem/v2-0203|MR|12345 for patients that contain an identifier that has a type coding of with a system of http://terminology.hl7.org/CodeSystem/v2-0203 , a code of MR (which identifies Medical Record Numbers), and a value of 12345 will return records such as: Show as: FHIR+JSON | FHIR+XML "Patient": { "identifier": [{ "type": { "coding" : { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" } } "system": "http://example.org/ehr-primary/", "value": "12345" }] } <Patient> <identifier> <type> <coding> <system value="http://terminology.hl7.org/CodeSystem/v2-0203"/> <value value="MR"/> </coding> </type> <system value="http://example.org/ehr-primary"/> <value value="12345"/> </identifier> </Patient> This can be used to disambiguate between data sets that contain collisions. For example, the above search will NOT return values with a different identifying type, such as: Show as: FHIR+JSON | FHIR+XML "Patient": { "identifier": [{ "type": { "coding" : { "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MRT" } } "system": "http://example.org/ehr-er", "value": "12345" }] } <Patient> <identifier> <type> <coding> <system value="http://terminology.hl7.org/CodeSystem/v2-0203"/> <value value="MRT"/> </coding> </type> <system value="http://example.org/ehr-er"/> <value value="12345"/> </identifier> </Patient> which signifies that the identifier is suffixed by a Temporary Medical Record Number. 3.2.1.5.5.13 text with reference TU or token type search parameters The text modifier on search parameters of type reference and token allows clients to indicate that a supplied string should be used to perform a string-search against the text associated with a code or value. For example, CodeableConcept.text , Coding.display , Identifier.type.text , or Identifier.assigner.display . Search matching is performed using basic string matching rules - begins with or is, case-insensitive. In this context, the text modifier is only allowed on reference and token type search parameters. When using the 'text' modifier, all typically-valid search parameter string inputs are allowed. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Condition?code:text=headache POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:text=headache would match Condition resources containing any codes that start with or equal the string 'headache' (case-insensitive), such as: SNOMED 25064002 - Headache finding SNOMED 398987004 - Headache following lumbar puncture SNOMED 230480006 - Headache following myelography (disorder) ICD-10 R51 - Headache ICD-10 R51.0 - Headache with orthostatic component, not elsewhere classified ICD-10 R51.9 - Headache, unspecified etc. Note that the search is not expected to return results with codes such as SNOMED 735938006 , since the code text of 'Acute headache' server does not match a default string search of the term headache (case-insensitive, begins with or equals). For advanced searching of related text, see the text-advanced search modifier. For more details about the difference between the identifier modifier and chained-searches on the identifier element, see Searching Identifiers . 3.2.1.5.5.14 text with string type search parameters The text modifier allows clients to request matching based on advanced string processing of the search parameter input. Implementers of this modifier 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.. Note that only a few servers are expected to offer this facility. Implementers could consider using the rules specified by the OData specification for the $search parameter . Typical implementations would use Lucene, Solr, an SQL-based full text search, or some similar indexing service. text is only allowed on search parameters of type string . When using the 'text' modifier, all typically-valid search parameter string inputs are allowed. that parameter. For example, assuming a search parameter section-text that applies to Composition.section.text , if the search: Show as: HTTP GET | HTTP POST GET [base]/Composition?section:text=(bone OR liver) and metastases POST [base]/Composition/_search Content-Type: application/x-www-form-urlencoded section:text=(bone OR liver) and metastases for compositions about metastases in server supports the bones or liver of subjects will name search for those literal values, parameter, but MAY also search for terms such as 'cancerous growth', 'tumor', etc.. 3.2.1.5.5.15 text-advanced TU The text-advanced not the :exact modifier allows clients to request matching based on advanced string processing of the search parameter input against the text associated with a code or value. For example, CodeableConcept.text , Coding.display , or Identifier.type.text . Implementers of this modifier SHOULD support name, it should reject a sophisticated search functionality of the type offered by typical text indexing services, but MAY support only basic search with minor additions (e.g., word-boundary recognition). 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.. text-advanced is allowed on search parameters of type reference and token . When name:exact=Bill , using the 'text-advanced' modifier, all typically-valid search parameter string inputs are allowed. For example, the search: Show as: HTTP GET | an HTTP POST GET [base]/Condition?code:text-advanced=headache POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:text-ad=headache would match Condition resources containing codes with text that equals or begins with 'headache', case-insensitive (e.g., same as the text modifier) such as: SNOMED 25064002 - Headache finding SNOMED 398987004 - Headache following lumbar puncture SNOMED 230480006 - Headache following myelography (disorder) ICD-10 R51 - Headache ICD-10 R51.0 - Headache with orthostatic component, not elsewhere classified ICD-10 R51.9 - Headache, unspecified etc. However, it would also match Condition resources containing codes with text containing the word 'headache' such as: SNOMED 735938006 - Acute headache SNOMED 95660002 - Thunderclap headache SNOMED 4969004 - Sinus headache ICD-10 G44.019 - Episodic cluster headache, not intractable ICD-10 G44.81 400 - Hypnic headache etc. Additionally, a server MAY also return Condition resources with codes containing synonymous text such as conditions error with the codes: SNOMED 37796009 - Migraine SNOMED 49605003 - Ophthalmoplegic migraine (disorder) ICD-10 G43.4 - Hemiplegic migraine ICD-10 G43.B0 - Ophthalmoplegic migraine, not intractable etc. 3.2.1.5.5.16 [type] an OperationOutcome The [type] modifier allows clients to restrict the resource type of a reference. The modifier does not use the literal '[type]' in any way, but rather the name of a resource - e.g., Patient , Encounter , etc.. Note that the modifier cannot 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. [type] is only allowed on reference type search parameters. When using the '[type]' modifier, all typically-valid search parameter reference inputs are allowed, but the value format is restricted to only [id] . For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?subject:Patient=23 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject:Patient=23 for observations where the subject is 'Patient 23' is functionally equivalent to: Show as: HTTP GET | HTTP POST GET [base]/Observation?subject=Patient/23 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject=Patient/23 as well as: Show as: HTTP GET | HTTP POST GET [base]/Observation?patient=23 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded patient=23 However, the modifier becomes more useful when used with Chaining and Reverse Chaining of search parameters. clear error message .

3.2.1.5.6 3.1.1.4.5 Prefixes

For the ordered parameter types of number , date , 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 described in the table below are used. Note that in the following table: parameter value refers to the value provided to search against (e.g., the parameter value in the request) resource value refers to the value being tested against in a resource (e.g., an element value in a data store) used:

Note that prefixes always test against values present in elements. In all cases, a prefix-based test against an element that does not exist will fail the test. To search for elements missing values, the use of search modifiers is required - either missing or not . Prefixes are allowed in searches that combine multiple terms. When using a prefix in "or" joined search parameter values, the prefix only applies to the value it precedes. For example, in value-quantity=lt60,gt100 , the lt prefix is applied to the value "60" and the gt prefix is applied to the value "100". Additional details can be found in the Searching Multiple Values section of the Search page. 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. sa ( starts-after ) and eb ( ends-before ) are not used with integer values but are used for decimals.

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 all the time during that day. If the resource target value is a Range , a Period , or a Timing , then the target is explicitly a range. Three ranges are identified:

Additional details about how The proper use of these ranges are applied are specific to each data type and are documented there. is discussed further below.

3.2.1.5.7 3.1.1.4.6 Escaping Search Parameters number

In the rules described above, special rules are defined for the characters $ , , , and | . As Searching on 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 simple numerical value in an actual parameter value, they must be prepended by the character \ , which also must be used to prepend itself. Therefore, a resource. Examples:

Notes about searching on Numbers:

• When a number search is used against a request for any Observation resource element that has stores a code of a,b . This escaping simple integer (e.g. ImmunizationRecommendation.recommendation.doseNumber ), and the search parameter is at not expressed using the exponential forms, and does not include any non-zero digits after a different level to decimal point, the percent encoding significance issues cancel out and searching is based on exact matches. Note that applies to all URL if there are non-zero digits after a decimal point, there cannot be any matches
• When a comparison prefix in the set lgt, lt, ge, le, sa & eb is provided, the implicit precision of the number is ignored, and they are treated as if they have arbitrarily high precision
• The way search parameters (as defined operate in RFC 3986 ). Standard percent escaping still applies, such that these URLs resources is not the same as whether two numbers are equal to each other in a mathematical sense
• Searching on decimals involves an implicit range. The number of significant digits of the implicit range is the number of digits specified in the search parameter value, excluding leading zeros. So 100 and 1.00e2 both have the same meaning: Show as: HTTP GET | HTTP POST number of significant digits - three

Here are some example searches:

GET
[base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,ValueSet/125
POST
[base]/ValueSet/_search
Content-Type:
application/x-www-form-urlencoded
url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,ValueSet/125
This
specification
defines
this
additional
form
of
escape
because
the
escape
syntax
using
\
applies
to

[base]/RiskAssessment?probability=gt0.8

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

3.2.1.5.8 3.1.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 yyyy-mm-ddThh:mm:ss.ssss[Z|(+|-)hh:mm] yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm] (the standard XML format). Note that fractional seconds MAY be ignored by servers TU .

Technically, this is any of the date , dateTime , and instant datatypes; 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 timezone 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 searches are intrinsically matches against 'periods', regardless of the underlying element type. For more information about how the different search prefixes work when comparing periods/ranges, refer to the Prefixes section. 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. Date searches can be controlled through the The use of prefixes as described in the following table: prefixes:

Please note in particular the differences between range comparison and boundary comparison prefixes when comparing ranges on both sides. Tests such as 'greater than' are evaluated true if any part of the value range is higher than the test range. Similarly, a test such as 'starts after' is non-inclusive of the range of the test value, so a request such as sa2013-01-14 is requesting values that start after January 14th has passed, not after January 14th started. In order to avoid unintentional overlapping of ranges, requests can increase the specificity of their request. For example, the test for sa2013-01-14T00:00:00 is a much clearer test. 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 time zones when performing queries. Dates do not have timezones, time zones, and timezones time zones should not be considered. Where both search parameters and resource element date times do not have timezones, time zones, the servers local timezone time zone should be assumed.

To search for all the procedures in a patient compartment that occurred over a 2-year period: Show as: HTTP GET | HTTP POST GET [base]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31 POST [base]/Patient/23/_search Content-Type: application/x-www-form-urlencoded Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31

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

Managing timezones time zones and offsets and their impact on search is a very difficult area. The FHIR implementation community is still investigating and debating the best way to handle timezones. time zones. Implementation guides may make additional rules in this regard.

Future versions of this specification may impose rules around the use of timezones time zones with dates. Implementers and authors of implementation guides should be aware of ongoing work in this area.

Implementer feedback is welcome on the issue tracker or chat.fhir.org .

3.2.1.5.12 3.1.1.4.8 string

For a simple string search, a string parameter serves as the input for a search against sequences of characters. This search is insensitive to casing and included combining characters, like accents or other diacritical marks. Punctuation and non-significant whitespace (e.g. repeated space characters, tab vs space) should also be ignored. Note that case-insensitive comparisons do not take locale into account, and will result in unsatisfactory results for certain locales. Character case definitions and conversions are out of scope for the FHIR standard, and the results of such operations are implementation dependent. 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 combining characters. Therefore, the default string search only operates on the base characters of the string parameter. 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.

When a string type search parameter points to a complex or backbone element (an element that contains sub-elements), by default the search is interpreted as a search against one or more string values in sub-elements, as selected by the implementation. A search parameter MAY explicitly choose elements by using an expression that instead points directly to the sub-elements. TU For example, if a search parameter is of type string and the expression points to Patient.name , the implementation MAY search against any one or more elements of the HumanName datatype (e.g., given , family , prefix , suffix , etc.) TU . However, if the search parameter intends to explicitly match against given and family only, the search parameter should use an expression of Patient.name.given | Patient.name.family . If the SearchParameter's narrative description includes additional considerations about what fields are indexed, SearchParameter.processingMode should have the value other . 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.

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 . For robust search, servers should search the parts of a family name independently. E.g. searching either "Carreno" or "Quinones" should match a family name of "Carreno Quinones". HL7 affiliates may make more specific recommendations about how search should work in their specific culture.

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

3.1.1.4.9 uri

The uri parameter refers to an element that contains a URI ( RFC 3986 ). By default, 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/
 GET [base]/ValueSet?url:above=http://acme.org/fhir/ValueSet/123/_history/5
 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 third line shows the converse - search for any value set above a given specific URL. This will match on any value set with the specified URL, but also on http://acme.org/ValueSet/123. Note that there are not many use cases where :above is useful as compared to the :below search
• The fourth 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

The search type uri is used with elements of type uri and url . The type reference is used for the types Reference and canonical . Note that for uri parameters that refer to the Canonical URLs of the conformance and knowledge resources (e.g. StructureDefinition , ValueSet , PlanDefinition etc), servers SHOULD support searching by canonical references, and SHOULD support automatically detecting a |[version] portion as part of the search parameter, and interpreting that portion as a search on the version.

3.2.1.5.13 3.1.1.4.10 token

A token type is a parameter that provides a close to exact match search on a string of characters, potentially scoped by a URI. It is mostly used against a code or identifier datatype data type where the value may have a URI that scopes its meaning, where the search is performed against the pair from a Coding or an Identifier. Tokens are also used against other fields where exact matches are required - uris, booleans, and ContactPoints , and ids . In these cases cases, the URI portion ( [system]| ) is not used (only the [code] portion). used.

For tokens, matches are literal (e.g. not based on subsumption or other code system features). Match is case sensitive unless the underlying semantics for the context indicate that the token should be interpreted case-insensitively (see, e.g. CodeSystem.caseSensitive ). Note that matches on _id are always case sensitive. If the underlying datatype data type is string then the search is not case sensitive.

Note : There are many challenging issues around case sensitivity and token searches. Some code systems are case sensitive (e.g. UCUM) while others are known not to be. For many code systems, it's ambiguous. Other kinds of values are also ambiguous. When in doubt, servers SHOULD treat tokens in a case-insensitive manner, on the grounds that including undesired data has less safety implications than excluding desired behavior. Clients SHOULD always use the correct case when possible, and allow for the server to perform case-insensitive matching.

To use subsumption-based logic, use the modifiers below, or list all the codes in the hierarchy. The syntax for the value is one of the following:

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

Notes:

• The namespace URI and code both must be escaped correctly. If a system is not applicable (e.g. an element of type uri , then just the form [parameter]=[code] is used.
• For token parameters on elements of type id , ContactPoint , uri , or boolean , the presence of the pipe symbol SHALL NOT be used - only the [parameter]=[code] form is allowed

Token search parameters are used for the following datatypes: 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 datatype. data type. The namespace for these codes is http://terminology.hl7.org/CodeSystem/special-values, 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
POST
[base]/Patient/_search
Content-Type:
application/x-www-form-urlencoded
identifier=http://acme.org/patient|2345

GET
[base]/Patient?gender=male
POST
[base]/Patient/_search
Content-Type:
application/x-www-form-urlencoded
gender=male

GET
[base]/Patient?gender:not=male
POST
[base]/Patient/_search
Content-Type:
application/x-www-form-urlencoded
gender:not=male

GET
[base]/Composition?section=48765-2
POST
[base]/Composition/_search
Content-Type:
application/x-www-form-urlencoded
section=48765-2

GET
[base]/Composition?section:not=48765-2
POST
[base]/Composition/_search
Content-Type:
application/x-www-form-urlencoded
section:not=48765-2

GET
[base]/Patient?active=true
POST
[base]/Patient/_search
Content-Type:
application/x-www-form-urlencoded
active=true

GET
[base]/Condition?code=http://acme.org/conditions/codes|ha125
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code=http://acme.org/conditions/codes|ha125

GET
[base]/Condition?code=ha125
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code=ha125

GET
[base]/Condition?code:text=headache
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code:text=headache

GET
[base]/Condition?code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F126851005
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F126851005

GET
[base]/Condition?code:below=126851005
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code:below=126851005

GET
[base]/Condition?code:in=http://acme.org/fhir/ValueSet/cardiac-conditions
POST
[base]/Condition/_search
Content-Type:
application/x-www-form-urlencoded
code:in=http://acme.org/fhir/ValueSet/cardiac-conditions

GET
[base]/Patient?identifier:of-type=http://terminology.hl7.org/CodeSystem/v2-0203|MR|446053
POST
[base]/Patient/_search
Content-Type:
application/x-www-form-urlencoded
identifier:of-type=http://terminology.hl7.org/CodeSystem/v2-0203|MR|446053

[base]/Patient?identifier:otype=http://terminology.hl7.org/CodeSystem/v2-0203|MR|446053

3.2.1.5.14 3.1.1.4.10.1 uri Searching Mime Types

The uri parameter refers to an element that contains a URI ( RFC 3986 ). By default, matches are precise, case and accent sensitive, and the entire URI must match. The modifier :above or :below can be used to indicate that partial matching is used. For example (note that the search parameter ValueSet.url modifier is of type uri ): Show as: HTTP GET | HTTP POST also very useful with searching mime types, such as for DocumentReference.contenttype GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123 POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url=http://acme.org/fhir/ValueSet/123 GET [base]/ValueSet?url:below=http://acme.org/fhir/ POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url:below=http://acme.org/fhir/ GET [base]/ValueSet?url:above=http://acme.org/fhir/ValueSet/123/_history/5 POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url:above=http://acme.org/fhir/ValueSet/123/_history/5 GET [base]/ValueSet?url=urn:oid:1.2.3.4.5 POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url=urn:oid:1.2.3.4.5 The first line is a request which refers to find any value set with the exact url "http://acme.org/fhir/ValueSet/123" The second line performs a Attachment.contentType . A simple search that such as:

GET [base]/DocumentReference?contenttype=text/xml

will return any value sets that have a URL that starts miss documents with "http://acme.org/fhir/" The third line shows the converse - search for any value set above a given specific URL. mime type such as text/xml; charset=UTF-8 . This search will match find all text/xml documents:

GET [base]/DocumentReference?contenttype:below=text/xml

For ease of processing on any value set with the specified URL, but also on http://acme.org/ValueSet/123. Note that there server, servers are not many use cases where :above is useful as compared only required to the support :below search The fourth line shows an example of searching by an OID. Note that on the :above and :below modifiers only apply to URLs, and not URNS such as OIDs The search type uri is used with elements base part of type uri and url . The type reference is used for the types Reference mime type; servers are not required to sort between different parameters and canonical . do formal subsumption logic.

3.2.1.5.15 3.1.1.4.11 Special Parameters quantity

A few parameters have the type 'special'. That indicates that the way this parameter works is unique to the quantity parameter and described with searches on the parameter. Quantity data type. The general modifiers and comparators do not apply, except as stated in the description. Implementers will generally need to do special implementations syntax for these parameters. These parameters are special: the value follows the form:

• _filter (all resources) section-text on Composition contains on Location near on Location [parameter]=[prefix][number]|[system]|[code] matches a quantity with the given unit

Composite search parameters are allow joining multiple elements into distinct single values with a $ . This The prefix is different from doing a simple intersection - the intersection rules apply at the resource level, so, for example, an Observation with multiple component repetitions may match because one repetition has a desired code optional, and is as described above , both regarding how precision and comparator/range operators are interpreted. Like a different repetition matches a value filter. The composite parameter approach works in this context because it allows searches based on a tuples of values. For example: Show as: HTTP GET | HTTP POST GET [base]/Observation?code-value-quantity=code$loinc|12907-2,value$ge150|http://unitsofmeasure.org|mmol/L POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code-value-quantity=code$loinc|12907-2,value$ge150|http://unitsofmeasure.org|mmol/L will match Observation records with a LOINC code number parameter, the number part of "12907-2" (Sodium [Moles/volume] in Red Blood Cells) AND a value greater than "150 mmol/L". Note that the sequence is a single search value and itself can be composed into a set of values. For example, searching Group.characteristic , searching for multiple key/value pairs (instead of an intersection of matches on key and value): Show as: HTTP GET | HTTP POST GET [base]/Group?characteristic-value=gender$mixed,owner$Eve POST [base]/Group/_search Content-Type: application/x-www-form-urlencoded characteristic-value=gender$mixed,owner$Eve will match Groups that have a decimal in exponential format. The gender system characteristic of "mixed" (the group contains people of multiple genders) OR the group has a and owner code characteristic of "Eve". Note that search modifiers follow the same pattern as token parameters are NOT allowed on composite parameters. Examples of using composite parameters: also optional. Example searches:

GET
[base]/DiagnosticReport?result.code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L
POST
[base]/DiagnosticReport/_search
Content-Type:
application/x-www-form-urlencoded
result.code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L

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

GET
[base]/Observation?component-code-value-quantity=http://loinc.org|8480-6$lt60
POST
[base]/Observation/_search
Content-Type:
application/x-www-form-urlencoded
component-code-value-quantity=http://loinc.org|8480-6$lt60

[base]/Observation?value-quantity=5.40e-3|http://unitsofmeasure.org|g

GET
[base]/Group?characteristic-value=gender$mixed
POST
[base]/Group/_search
Content-Type:
application/x-www-form-urlencoded
characteristic-value=gender$mixed

[base]/Observation?value-quantity=5.4||mg

GET
[base]/Questionnaire?context-type-value=focus$http://snomed.info/sct|408934002
POST
[base]/Questionnaire/_search
Content-Type:
application/x-www-form-urlencoded
context-type-value=focus$http://snomed.info/sct|408934002

[base]/Observation?value-quantity=5.4

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

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

The Logical Identifier of Specifying a resource represents system and a unique key code for an instance within a specific context (e.g., a single resource type in a server collection, a resource in a bundle, etc.). Searching by the logical id of an instance is done via search implies that the _id search parameter. Given is based on a particular code system - usually UCUM , and that a logical id precise (and potentially canonical) match is unique in the context, searching by logical id will always result in either zero or one records. desired. In many ways, the search this case, it is functionally equivalent inappropriate to an equivalent simple read operation . However, there are some differences in using search instead of read: Search operations always return bundles. If on the logical id exists and human display for the resource unit, which can be returned, the result will be a bundle containing the resource (search) instead of the resource itself (read). If the logical id does not exist or cannot be returned, the result of a valid is uncontrolled and may unpredictable.

The search will still be processor may choose to perform a bundle. The bundle MAY include further information in the form of an OperationOutcome . See Handling Errors search based on canonical units for more information. Additional resources (e.g. any value where the units can be requested and/or returned converted to a value in mg in the same request - see Including Other Resources for more information. Additional search functionality is available. case above). For example, asking for an observation may have a Patient resource by logical id, but also setting the search criteria value of deceased 23 mm/hr . This is equal to true would only return 0.23 m/hr . The search processer can choose to normalise all the Patient if they are deceased. Since _id requires values to a resource type context canonical unit such as 6.4e-6 m/sec , and there can only be zero or one resources of a type with a given logical id, the convert search is functionally equivalent terms to the simple read operation same units (m/sec). Such conversions can be performed based on the semantics defined in UCUM of GET [base]/Patient/23 . However, searching by logical identifier means that all other search functionality is available - e.g., OperationOutcome resources for issues, additional search parameters, inclusion of additional resources, etc..

3.2.1.6.1.2 3.1.1.4.12 Searching by Membership reference

Some resources (e.g., Group , List , and CareTeam ) are used A reference parameter refers to maintain collections of other resources. references between resources . For example, find all Conditions where the subject reference is a Group of Patients representing a cohort particular patient, where the patient is selected by name or a List identifier. The interpretation of patient allergies. While it a reference parameter is possible to retrieve the collection resource, iterate over the entries, and fetch each referenced resource, using search criterion allows for fewer round-trips and additional search criteria to be specified in-line. either:

• _in [parameter]=[id] to test against active membership, and the logical [id] of a resource using a local reference (i.e. a relative reference)
• _list [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 test against advanced List functionality (e.g., functional list definitions different types of resources (e.g. Observation.subject ). )
3.2.1.6.1.3 Identifiers and References
• [parameter]=[url] The Identifier datatype where the [url] is typically only used on by an absolute URL - a single element in reference to a resource and is typically named identifier . The element is typically cardinality 0..* , meaning that resources may have zero, one, by its absolute location, or more identifiers attached to them (e.g., a single patient record with MRNs for several related facilities). by it's canonical URL

Resources containing identifier elements usually expose Note: A relative reference resolving to the same value as a matching search parameter, e.g., Patient.identifier specified absolute URL, or CanonicalResource.identifier . Given the structure of the identifier type, vice versa, qualifies as a match. For example, if the search parameter value is a token type - see 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 token search type term also matches patient references like this:

 <patient>
   <reference value="http://example.org/fhir/Patient/123"/>
 </patient>

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

It is often useful Some references may point to search via reference across resource links. For example, if you more than one type of resource; e.g. subject: Reference(Patient|Group|Device|..). In these cases, multiple resources may have the MRN for same logical identifier. Servers SHOULD reject a patient and do not know search where the logical identifier, it is desireable 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 like "encounters for any observations where the subject refers to the patient resource with MRN 1234". There are two ways of searching references by identifier, depending on how data the logical identifier "23". A modifier is stored in also defined to allow the system: via 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 or via as explained in the next section. Note: The identifier [type] search modifier. 3.2.1.6.1.4 Canonical Identifiers Chaining functions by resolving modifier can't be used with a resource reference and then searching inside it. 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 this case, requesting: Show as: HTTP GET | HTTP POST GET [base]/Encounter?patient.identifier=http://example.org/facilityA|1234 POST [base]/Encounter/_search Content-Type: application/x-www-form-urlencoded patient.identifier=http://example.org/facilityA|1234 will some cases, search Encounter resources, following references in the parameters are defined with an implicitly limited scope. For example, patient Observation has an element subject , which is a reference to one of a number of types. This has a matching search parameter ("the patient present at the encounter"), and testing those Patient resources against the Patient.identifier value subject , which refers to any of 1234 in system http://example.org/facilityA . the possible types. In short, this search will return all Encounters for Patient records matching "1234" in "facilityA". This search addition to this, there is flexible, another search parameter patient , which also refers to Observation.subject , but does require resolving (searching against) Patient resources, even though the request is only for Encounters. If a system wants limited to enable searches via identifiers without chaining, the server can only include additional information in the Reference Datatype (in Reference.identifier ), which is then accessible by the references of type identifier Patient search modifier. Note that this approach requires additional bookkeeping by . When using the server - if a patient record search parameter, there is modified, e.g., to add an additional identifier, every resource that reference that patient record would no need to specify ":Patient" as a modifier, or "Patient/" in the search value, as this must always be updated. true.

The References are also allowed to have an identifier . The modifier functions :identifier allows for searching by testing the Reference.identifier element within resources. In this case, requesting: Show as: HTTP GET | HTTP POST GET [base]/Encounter?patient:identifier=http://example.org/facilityA|1234 POST [base]/Encounter/_search Content-Type: application/x-www-form-urlencoded patient:identifier=http://example.org/facilityA|1234 will identifier rather than the literal reference:

 GET [base]/Observation?subject:identifier=http://acme.org/fhir/identifier/mrn|123456

This is a search Encounter resources, testing for all observations that reference a patient by a particular patient MRN. When the Encounter.subject.identifier element against :identifier modifier is used, the search value of 1234 in system http://example.org/facilityA . In short, this works as a token search will return all Encounters for that . The :identifier modifier is not supported on canonical elements since they do not have Patient references and include the an identifier "1234" separate from "facilityA". the reference itself.

Note that the difference between the two searches Chaining is a single character - the . (period) in not supported when using the first example represents :identifier modifier, nor are chaining, includes or reverse includes supported for reference elements that do not have a chained search and the : reference (colon) in the second indicates the use of a search modifier. element.

Canonical Resources are identified by their url and possibly a version. Similarly, references to canonical resources are made with the canonical datatype. More details about canonical references can be found in the Canonical URLs section The reference search parameter is mostly used for resource elements of the references page. When searching type Reference or canonical references, the . However, it is also be used to search resource elements of type Resource - i.e. where one resource is reference , though with an additional syntax for version information. For more information about version resolution, directly nested within another - see the References and Versions Bundle search parameters section 'message' and 'composition' as an example of this page. this.

3.2.1.6.2 3.1.1.4.13 References and Versions

Elements of type Reference may contain a versioned reference: Show as: FHIR+JSON | FHIR+XML { "resourceType": "Condition", ... "evidence": { "detail": { "reference": "Observation/123/_history/234234" } }, ... } <Condition> ... <evidence> <detail> <reference value="Observation/123/_history/234234"/> </detail> </evidence> ... </Condition>

   <evidence>
      <reference value="Observation/123/_history/234234"/>
  </evidence>

When searching on versioned references, the following rules apply:

• If a resource has a reference that is versioned versioned, and chaining is performed, the criteria should ideally be evaluated against the version referenced, but most systems will not be capable of this because search is only defined to function against the current version of a resource
• Where a search does not act on the referenced version, search results SHOULD contain a OperationOutcome with a warning that indicates the discrepancy
• If a resource has a reference that is versioned and the resource is included (e.g., _include , _revinclude ), is performed, the specified version SHOULD be provided.
If a reference-type search parameter does not contain a version (i.e., no /_history/[version] in the URL), the search will match against resources containing both versioned and un-versioned references.

Elements of type canonical may contain a version specific reference, but this version is different in both meaning and format to version specific references that might be found in a Reference : Show as: FHIR+JSON | FHIR+XML { "resourceType": "QuestionnaireResponse", ... "questionnaire": "http://example.org/fhir/questionnaire/patient-intake|3.0", ... } <QuestionnaireResponse> ... <questionnaire value="http://example.org/fhir/questionnaire/patient-intake|3.0"/> ... </QuestionnaireResponse>

   <valueSet value="http://hl7.org/fhir/ValueSet/example|3.0"/>

This version is a reference to the business version of the resource.

For canonical references, servers SHOULD support searching by Canonical URLs, and SHOULD support automatically detecting a |[version] portion as part of the search parameter and interpreting that portion as a search on the business version of the target resource. The modifier :below is used with canonical references, to control whether the version is considered in the search. The search: Show as: HTTP GET | HTTP POST GET [base]/QuestionnaireResponse?questionnaire:below=http://example.org/fhir/questionnaire/patient-intake POST [base]/QuestionnaireResponse/_search Content-Type: application/x-www-form-urlencoded questionnaire:below=http://example.org/fhir/questionnaire/patient-intake would match QuestionnaireResponses based on Questionnaires:

GET {base]/Observation?definition:below=http:http://acme.com/some-profile

matches all of these element values:

• http://example.org/fhir/questionnaire/patient-intake|1.0 http://example.org/fhir/questionnaire/patient-intake|1.1 http://acme.com/some-profile|1.0
• http://example.org/fhir/questionnaire/patient-intake|2.0 http://acme.com/some-profile|1.1
• etc. http://acme.com/some-profile|2.0

The search: Show as: HTTP GET | HTTP POST GET [base]/QuestionnaireResponse?questionnaire:below=http://example.org/fhir/questionnaire/patient-intake|1 POST [base]/QuestionnaireResponse/_search Content-Type: application/x-www-form-urlencoded questionnaire:below=http://example.org/fhir/questionnaire/patient-intake|1 would match QuestionnaireResponses based on Questionnaires with a major version of '1', e.g.: http://example.org/fhir/questionnaire/patient-intake|1.0 http://example.org/fhir/questionnaire/patient-intake|1.1 For further information about searching canonical references, see Choosing

GET {base]/Observation?definition:below=http:http://acme.com/some-profile|1

matches the right Canonical Reference . first two element values.

3.2.1.6.3 3.1.1.4.14 Searching Hierarchies

Some references are circular - that is, the reference points to another resource of the same type. When the reference establishes a strict hierarchy, the modifiers above :above and below can :below may be used to search transitively through the hierarchy: Show as: HTTP GET | HTTP POST GET [base]/Procedure?location:below=42 POST [base]/Procedure/_search Content-Type: application/x-www-form-urlencoded location:below=42

GET [base]/Procedure?location:below=42

This search returns not no only all procedures that occurred at location with id 42, but also any procedures that occurred in locations that are part of location with id 42.

GET [base]/MedicationAdministration?encounter:above=21

Returns all medication administrations that happened during encounter with id 21 or during any "parent" encounter of that encounter.

Resources that establish hierarchical references are listed in the Circular Resource References section of the References page. Servers indicate that above / below :above/:below is supported on a search parameter by defining them as Modifiers on the Search Parameter definition.

3.2.1.6.5 3.1.1.4.15 Chaining (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 ( . ) 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 subject , which is usually a reference to a Patient resource, and the Patient resource includes a parameter name which searches on patient name, then the search: Show as: HTTP GET | HTTP POST GET [base]/DiagnosticReport?subject.name=peter POST [base]/DiagnosticReport/_search Content-Type: application/x-www-form-urlencoded subject.name=peter 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: Show as: HTTP GET | HTTP POST GET [base]/DiagnosticReport?subject:Patient.name=peter POST [base]/DiagnosticReport/_search Content-Type: application/x-www-form-urlencoded subject:Patient.name=peter

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

Note that chained parameters are applied independently to the target resource. For example, Show as: HTTP GET | HTTP POST GET [base]/Patient?general-practitioner.name=Joe&general-practitioner.address-state=MN POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded general-practitioner.name=Joe&general-practitioner.address-state=MN

GET Patient?general-practitioner.name=Joe&general-practitioner.address-state=MN

may return Patients cared for by Joe from CA and Jane from MN: no one practitioner need satisfy both conditions. E.g. the chains are evaluated separately. For use cases where the joins must be evaluated in groups, there are either Composite search parameters, or the _filter parameter.

Note that chained search parameters are not intended to work with search modifiers . While their use is not prohibited, searches requiring advanced matching across resources are encouraged to use Named Queries or Advanced filtering . 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.

3.2.1.6.6 3.1.1.4.16 Reverse Chaining

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 the _has parameter: Show as: HTTP GET | HTTP POST GET [base]/Patient?_has:Observation:patient:code=1234-5 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _has:Observation:patient:code=1234-5

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.

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

The _has parameter can be nested, chained, like this: Show as: HTTP GET | HTTP POST GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent=MyUserId POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _has:Observation:patient:_has:AuditEvent:entity:agent=MyUserId This search will fetch

GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:user=MyUserId

Fetch all Patient records the patients that have an Observation where the observation has an audit event from a specific user.

3.1.1.4.17 GET [base]/Encounter?patient._has:Group:member:_id=102 POST [base]/Encounter/_search Content-Type: application/x-www-form-urlencoded patient._has:Group:member:_id=102 to Composite Search Parameters

Composite search for parameters support joining single values with a $ . For example, the Encounters result of patients that are members the search operation is the intersection of the Group "102". 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.

Note If, instead, the search is to find patients that reverse-chained 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 parameters are not intended parameter, since the server is expected to work respond with results which match either value. Every search modifiers . While their parameter may be used with comma-separated values in this fashion; this includes the use is of search parameters with modifiers, such as `?code:text=this,that.

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 prohibited, 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 syntax definition of the parameter. These sequences are formed by joining the single values with a _has makes construction $ . Note: This sequence is a single value and parsing error-prone. Searches requiring advanced itself can be composed into a set of values, so that, for example, multiple matching across resources characteristic-value parameters can be specified as GET [base]/Group?characteristic-value=gender$mixed,owner$Eve .

Note: Modifiers are encouraged to use Named Queries or Advanced filtering . 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

GET
[base]/Questionnaire?context-type-value=focus$http://snomed.info/sct|408934002

3.2.1.6.7 3.1.1.4.18 Handling Missing Data

Consider the case of searching for all AllergyIntolerance resources: Show as: HTTP GET | HTTP POST GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active

GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active

This search will only return resources that have a value for clinicalStatus: Show as: FHIR+JSON | FHIR+XML { "resourceType" : "AllergyIntolerance", "clinicalStatus": { "coding": [ { "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical", "code": "active" } ] } } <AllergyIntolerance> <clinicalStatus> <coding> <system value="http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical"/> <code value="active"/> </coding> </clinicalStatus> </AllergyIntolerance>

{
  "resourceType" : "AllergyIntolerance",
   "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
        "code": "active"
      }
    ]
  }
}

Resources missing a clinicalStatus will not be returned. This is probably unsafe - it would not usually be appropriate to ignore AllergyIntolerance warnings with an unknown clinical status, and only return resources with an explicit clinicalStatus. Instead, it might be desired to return AllergyIntolerance resources with either an explicit value for clinicalStatus, or none: Show as: HTTP GET | HTTP POST GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active GET [base]/AllergyIntolerance?clinical-status:missing=true POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded clinical-status:missing=true

GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active
GET [base]/AllergyIntolerance?clinical-status:missing=true

Note that this is 2 separate queries. They can be combined in a batch , but not in a single operation. This query will always return an empty list, as no resource can satisfy both criteria at once: Show as: HTTP GET | HTTP POST GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active&clinical-status:missing=true POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active&clinical-status:missing=true

GET [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active&clinical-status:missing=true

There is no way to use the :missing modifier and mix with a value using the comma syntax documented above for composite search parameters.

An alternative approach is to use the _filter parameter, for servers that support this parameter.

3.1.1.4.19 Escaping Search Parameters

In the rules described above, special rules are defined for the characters $ ,,, 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 \ , which also must be used to prepend itself. Therefore, param=xxx$xxx indicates that it is a composite parameter, while param=xx\$xx indicates that the parameter has the literal value xx$xx . The parameter value xx\xx is illegal, and the parameter value param=xx\\xx indicates a literal value of xx\xx . This means that:

GET [base]/Observation?code=a,b

is a request for any Observation that has a code of either a or b , whereas:

GET [base]/Observation?code=a\,b

is a request for any Observation that has a code of a,b .

This escaping is at a different level to the % encoding that applies to all URL parameters. Standard % escaping still applies, such that these URLs have the same meaning:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124,125
GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124%2CValueSet/125

As do these URLs:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,125
GET [base]/ValueSet?url=http%58%47%47acme%46org%47fhir%47ValueSet%47123%44http%58%47%47acme%46org%47fhir%47ValueSet%47124%92%46125

This specification defines this additional form of escape because the escape syntax using \ applies to all parameter values after they have been 'unescaped' on the server while being read from the HTTP headers.

3.1.1.4.20 Text Search Parameters

The special text search parameters, _text and _content , search on the narrative of the resource, and the entire content of the resource respectively. Just like string parameters using the :text modifier, 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.

Implementers could consider using the rules specified by the OData specification for the $ search parameter . Typical implementations would use Lucene, Solr, an SQL-based full text search, or some similar indexing service.

3.1.1.4.21 Special Parameters

A few parameters have the type 'special'. That indicates that the way this parameter works is unique to the parameter and described with the parameter. The general modifiers and comparators do not apply, except as stated in the description.

Implementers will generally need to do special implementations for these parameters. These parameters are special:

• _filter (all resources)
• near on Location

3.1.1.4.22 Searching by list

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

 GET [base]/Patient?_list=42

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

 GET [base]/AllergyIntolerance?patient=42&_list=$current-allergies

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.

3.2.1.6.8 3.1.1.4.23 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, the _filter "_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 1234-5 ": Show as: HTTP GET | HTTP POST GET [base]/Observation?code=http://loinc.org|1234-5&subject.name=peter POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=http://loinc.org|1234-5&subject.name=peter

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

Using the _filter parameter, the search would be expressed like this (note that the value is unescaped for readability): Show as: HTTP GET | HTTP POST GET [base]/Observation?_filter=code eq http://loinc.org|1234-5 and subject.name co "peter" POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _filter=code eq http://loinc.org|1234-5 and subject.name co "peter" this:

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

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

3.2.1.6.9 3.1.1.4.24 Searching Multiple Specifying the type of Resource Types

Normally, a search is initiated against a known type of resource, e.g.: Show as: HTTP GET | HTTP POST GET [base]/Observation?params... POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded params... e.g.

GET [base]/Observation?params...

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

• Using search across all resource types ( [base]?params... ) (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 standard search parameter _type . parameter:

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

If no type is specified, the only search parameters that be can be used in global search like this are the base parameters that apply to all resources . If a single type is specified, all search parameters for that type are allowed. resources. If multiple types are specified, all any search parameters that can be referenced commonly between resources can be used (e.g., listed with the same name in the CapabilityStatement, typically shared across the value entire set of SearchParameter.code ) TU . For example, both Patient and Person define a search parameter referenced by name . Assuming a server implements both parameters and uses name to do so, the name parameter can specified resources may be used to search across both Patient and Person resources. Note that this is allowed even though the (see search parameters do not share a common definition. If a request references multiple parameters that are not the same type (e.g., if one parameter is a number type and another is a token type, despite sharing the same name), this is an error and servers SHOULD return a 400 status TU . 3.2.1.6.10 Implicit Resources Some resources are defined implicitly rather than as explicit instances (e.g. Implicit Code Systems registry ). When searching resources where implicit instances might exist, it is up to the server whether they will include implicit resources as part of the search set. Implementation Guides MAY set specific expectations about search behavior around implicit resources. TU 3.2.1.6.11 Named Queries 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. To support more advanced functionality, this specification defines a method for creating and using named . 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 OperationDefinition .

Query operations are only allowed in the base and type search contexts . Named queries cannot be defined at the instance level. Query operations SHOULD NOT be invoked via any method other than search with Technically, the _query _type parameter (e.g., servers SHOULD NOT execute query operations via [base]/$[operation code] , etc.). TU For named queries, all the standard search parameters (parameters for all resources and search result parameters) are potentially available for use in addition to any parameters defined by the query operation. In addition, if the query operation is defined in the scope of a specific resource, the search parameters for that resource are also potentially available. For example, a named query with a scope of Patient could include the _lastUpdated , _sort , and/or Patient.gender search parameters, even if those aren't explicitly listed as parameters on the query operation. Servers do not need to support ANY such 'inherited' parameters unless explicitly documented in the operation's description. Clients should not assume the availability of any search token parameter that is not supported for general queries (i.e. listed in the server's CapabilityStatement , either in CapabilityStatement.rest.searchParam or CapabilityStatement.rest.resource.searchParam ). Servers MAY further document the search parameters they support for a specific query operation - either in text or by defining a constrained operation based on the original that explicitly enumerates all supported parameters. TU In order to ensure consistent behavior, authors SHOULD include relevant search parameters in the named query definition ( OperationDefinition ). TU For example, the operation definition: Show as: FHIR+JSON | FHIR+XML { "resourceType": "OperationDefinition", "id": "current-high-risk", "url": "http://example.org/OperationDefinition/current-high-risk", "version": "0.0.1", "name": "Current High-Risk Patients", "status": "draft", "kind": "query", "description": "Filter Patients based on risk assessments", "code": "current-high-risk", "resource": [ "Patient" ], "system": false, "type": true, "instance": false, "parameter": [ { "name": "ward", "use": "in", "min": 0, "max": "*", "documentation": "Ward filters to apply to patient locations", "type": "string", "searchType": "reference" }, { "name": "return", "use": "out", "min": 1, "max": "1", "documentation": "Searchset bundle", "type": "Bundle" } ] } <OperationDefinition xmlns="http://hl7.org/fhir"> <id value="current-high-risk" /> <url value="http://example.org/OperationDefinition/current-high-risk" /> <version value="0.0.1" /> <name value="Current High-Risk Patients" /> <status value="draft" /> <kind value="query" /> <description value="Filter Patients based on risk assessments" /> <code value="current-high-risk" /> <resource value="Patient" /> <system value="false" /> <type value="true" /> <instance value="false" /> <parameter> <name value="ward" /> <use value="in" /> <min value="0" /> <max value="*" /> <documentation value="Ward filters to apply to patient locations" /> <type value="string" /> <searchType value="reference" /> </parameter> <parameter> <name value="return" /> <use value="out" /> <min value="1" /> <max value="1" /> <documentation value="Searchset bundle" /> <type value="Bundle" /> </parameter> </OperationDefinition> can be executed via: Show as: HTTP GET | HTTP POST Resource Types Request Description GET [base]/Patient?_query=current-high-risk POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _query=current-high-risk Query with no additional parameters GET [base]/Patient?_query=current-high-risk&ward=Location/A1 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _query=current-high-risk&ward=Location/A1 Query with a ward parameter value passed to the filter GET [base]/Patient?_query=current-high-risk&birthdate=ge1970-01-1 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _query=current-high-risk&birthdate=ge1970-01-01 Query with a no additional parameters, filter results according to a standard patient birthdate query. Note that servers SHOULD accept query parameters that are not enumerated in named queries based on their standard support (e.g., parameters that are supported for a given resource type), but servers MAY choose to ignore parameters not specified by the OperationDefinition TU . GET [base]/Patient?_query=current-high-risk&birthdate=ge1970-01-01&ward=Location/A1 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _query=current-high-risk&birthdate=ge1970-01-01&ward=Location/A1 Query with both a ward parameter value passed to the named query and a standard patient query filter by birthdate. Note that query parameters are unordered, so parameters to a named query MAY appear in any location or sequence TU . Note that operations defined as named queries (using a OperationDefinition.kind of query ) SHOULD NOT be invoked via any mechanism other than search (i.e., do not expose [base]/[type]/$[operation code] ) TU . Value Set.

3.2.1.7 3.1.1.5 Modifying Search Results Managing Returned Resources

3.2.1.7.1 3.1.1.5.1 Sorting (_sort)

The client can indicate which order to return the results by using the parameter _sort , which can contain a comma-separated list of sort rules in priority order: Show as: HTTP GET | HTTP POST GET [base]/Observation?_sort=status,-date,category POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _sort=status,-date,category

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

Each item in the comma-separated comma separated list is a search parameter, optionally with a '-' prefix. The prefix indicates decreasing order; in its 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 below ).
• Servers have discretion on the implementation of sorting for both repeated elements and complex elements. For example, if requesting a sort on Patient.name , servers might A search by family name then given, given name then family, or prefix, family, parameter can refer to an element that repeats, and then given. Similarly, when sorting with therefore there can be multiple values for a given names, search parameter for a single resource. In this case, the sort might be is based on the 'earliest' name item in sort order or the first name set of multiple parameters that comes earliest in the instance. 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.
• This specification does not specify exact exacts rules for consistency of sorting across servers. In general, this is deemed to be not as essential as consistency of filtering (though even that is a little variable). The purpose of sorting is to provide data in a "reasonable" order for end-users. "Reasonable" may vary by use case and realm, particularly for accented characters.
When sorting on search parameters of reference and token types, the search

3.2.1.7.3 3.1.1.5.3 Limiting Page Size (_count) Count

In order to keep the load on clients, servers, 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 an instruction to the server regarding how many resources should be returned in a single page. Servers SHALL NOT return more resources in a single page than requested, even if they don't support paging, but may return less than the client requested. NOTE: This means that all servers that support search or history SHALL support checking the _count parameter. The server SHOULD ensure that any pages reachable via links (e.g. previous/next) respect the should repeat the original requested _count expectations (or a server-overridden max parameter in its returned page size). 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 _sort and _count 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.

If if _count has the value 0, this shall be treated the same as _summary=count : the server returns 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. In the same way, the _count parameter only applies to resources with entry.search.mode = match search , and does not include included resources or operation outcomes.

The _count parameter has no impact on the value of Bundle.total as the latter represents the total number of matches, not how many are returned in a single Bundle response.

3.2.1.7.4 Limiting Total Result Size (_maxresults) TU 3.1.1.5.4 In some scenarios, a client knows that it will only process a certain number of results for a search, regardless of how many records there are. For example, if an application is providing an overview of patient activity and will only display the most recent observation on a summary screen, telling the server that additional records will never be retrieved allows the server to free any resources that might have been reserved for paging. The parameter _maxresults is defined as an instruction to the server regarding the limit on how many total resources should be returned from a query. If supported, a server SHOULD NOT return more resources than requested. As with Including other parameters, servers supporting _maxresults SHALL include this parameter in the Self Link when returning results. The _maxresults parameter has no impact on the value of Bundle.total as the latter represents the total number of matches, not how many are returned resources in a response. The combination of result ( _sort _include and _maxresults 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 _maxresults=1 . This way, the last matching resource will be returned. Note that _maxresults does not absolve a server from paging requirements. For example, a client can request _maxresults=10&_count=5 _revinclude to receive (at most) two pages of five results each. 3.2.1.7.5 Summary (_summary) )

The client can Clients may request that the server to engine return only a portion of the resources by using the parameter _summary : Show as: HTTP GET | HTTP POST GET [base]/ValueSet?_summary=true POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded _summary=true The _summary parameter requests the server to return a subset of the resource. It can contain one of the following values: true Return a limited subset of elements from the resource. This subset SHOULD consist solely of all supported elements that are marked as "summary" in the base definition of the resource(s) (see ElementDefinition.isSummary ) text Return only the text , id , meta , and top-level mandatory elements (these mandatory elements are included related to ensure that the payload is valid FHIR; servers MAY omit elements within these sub-trees as long as they ensure that the payload is valid). Servers MAY return extensions, but clients SHOULD NOT rely on extensions being present and SHOULD use another search mode if data contained results, in extensions is required. TU data Remove the text element count Search only: just return a count of the matching resources, without returning the actual matches false Return all parts of the resource(s) The intent of the _summary parameter is order to reduce the total processing load on server, client, and resources between them such as the network. It overall network delay of repeated retrievals of related resources. This is most useful for resources that are large, particularly ones that include images or elements that may repeat many times. The purpose of when 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 searching 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 clinical resource, but for resources in order to allow servers to store the summarized form(s) in advance. Servers SHOULD mark every such resource returned, the by populating meta.tag resources with client will also need the code SUBSETTED to ensure subject (patient) resource that the incomplete clinical resource is not accidentally used to overwrite a complete resource. refers to. The self link in the search result Bundle is important for the interpretation of the result and should always be returned, regardless of the type of _summary. Note that the _include and _revinclude parameters cannot be mixed with _summary=text . Implementation Note: There is some question about the inclusion of extensions in the summary. Additional rules may be made around this in the future. 3.2.1.7.6 Elements (_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 in the search results using use the _elements parameter: Show as: HTTP GET | HTTP POST GET [base]/Patient?_elements=identifier,active,link POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _elements=identifier,active,link The _elements _include parameter consists of a comma-separated list of base element names such as, elements defined at the root level in the resource. Each element name SHALL be the base element name without specifying [x] or one of the types (e.g., "value" is valid, while "value[x]" and "valueQuantity" are not) TU . 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. Servers have the right to return more data than request, however clients can generally expect that returned elements will be: elements explicity requested, mandatory elements, or modifier elements that have values. Servers are not obliged to return just the requested elements. Servers SHOULD always return mandatory and modifier elements whether they are requested or not. Servers SHOULD mark the resources with the tag SUBSETTED to ensure indicate that the incomplete resource is not actually used to overwrite a complete resource. If a client supplies _elements values prefixed with resource types, such as _elements=Patient.gender , then servers SHOULD apply these element-level restrictions to all subject resources be included in the returned bundle, rather than just to direct search matches (i.e., restrictions should be applied to bundle entries with any search.mode). 3.2.1.7.7 Relevance (_score) Where a search specifies a non-deterministic sort, results. An alternative scenario is where the search algorithm may generate a ranking score client wishes to indicate which resources meet the specified criteria better than others. The server can return this score in entry.score : Show as: FHIR+JSON | FHIR+XML "entry": { "score": 0.45, "resource": { "resourceType": "Patient", ... patient data ... } } <entry> <score value=".45"/> <resource> <Patient> ... patient data ... </Patient> </resource> </entry> The score is a decimal number with fetch a value between (and including) 0 and 1, where 1 is best match, particular resource, and 0 is least match. 3.2.1.7.8 Including Referenced Resources Along with any resources matching search criteria, clients may request that related resources are included with results (i.e., refer to reduce the overall network delay of repeated retrievals). it. For example, when searching for clinical resources (e.g., Condition , Observation , etc.), the client will also generally need the subject ( Patient ) resource may wish to fetch a MedicationRequest, and any provenance resources that refer to the clinical resource refers to. prescription. This section describes several mechanisms for requesting additional data within FHIR search. Note that implementers should also consider whether using GraphQL is an appropriate approach, but outside the scope of FHIR Search and thus not described here. 3.2.1.7.8.1 Inline Requests ( _include known as a reverse include, and is specified by providing a _revinclude ) parameter.

The most common method for requesting additional resources is inline, via the search result parameters Both _include and _revinclude . The parameters are similar to chaining based on search parameters, rather than paths in that they follow links between resources based on the resource, since joins, such as chaining , are already done by search parameters. parameter.

The parameter Each _include is used to follow links 'forward'. For example, to include relevant Patient resources for requested Encounter matches, based on the Encounter.subject element, using either the subject or patient parameter specifies a search parameters. parameter to join on:

 GET [base]/MedicationRequest?_include=MedicationRequest:patient
 GET [base]/MedicationRequest?_revinclude=Provenance:target

The parameter _revinclude is used to follow reverse links. For example, first search requests all matching MedicationRequests, to include relevant Observation resources for requested Patient matches, based on any patient that the Observation.subject element, using either medication prescriptions in the subject or patient result set refer to. The second search parameters. requests all matching prescriptions, return all the provenance resources that refer to them.

Both Parameter values for both _include and _revinclude share the same syntax - up to have three components, parts, separated by colon characters ( a : ). The details of the syntax are: character:

1. [_include|_revinclude]=[resource]:* : where [resource] is the The name of the source resource from which the join comes and the wildcard literal * (asterisk) is requesting all supported reference type search parameters for that resource. Note that the list of search parameters supported for _include or _revinclude is not the same as the list of supported search parameters.
2. [_include|_revinclude]=[resource]:[parameter] : where [resource] is the The name of the source resource from which the join comes and [parameter] is the name of a search parameter which must be of type reference .
3. [_include|_revinclude]=[resource]:[parameter]:[targetType] : where [resource] is the name of the source resource from which the join comes, [parameter] is the name of a search parameter which must be (Optional) A specific of type reference , and [targetType] is a specific of target resource type (for when a the search parameter refers to references of multiple types). possible target types)
Note that implementers intending to support wildcard ( * ) segments SHOULD advertise them along with other resources and search parameters in their capability statement (e.g., in CapabilityStatement.rest.resource.searchInclude ).

_include and _revinclude parameters do not include multiple values. Instead, the parameters are repeated for each different include criteria.

Each _include parameter specifies a search parameter to join on: Show as: HTTP GET | HTTP POST GET [base]/MedicationRequest?_include=MedicationRequest:requester POST [base]/MedicationRequest/_search Content-Type: application/x-www-form-urlencoded _include=MedicationRequest:requester GET [base]/MedicationRequest?_revinclude=Provenance:target POST [base]/MedicationRequest/_search Content-Type: application/x-www-form-urlencoded _revinclude=Provenance:target The first search requests all matching MedicationRequests, and asks the server to follow the references to any "requester" for each medication returned and include them in the returned result set. The second search requests all prescriptions, and that any Provenance resources referring to those prescriptions be included in the result set. 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.search.mode set to "include" (in some searches, it is not obvious which resources are matches, and which are includes). If there is no reference, or no matching resource, the resource cannot be retrieved (e.g. on a different server), then the resource is omitted, and no error is returned.

Servers SHOULD resolve _include and _revinclude requests for version-specific references by resolving the version named in the reference. _include and _revinclude are, by default, invoked The inclusion process can be iterative, if (and only on the initial results of the search set, not on any 'included' resources. To repeatedly perform the _include and _revinclude instructions on included resources, use if) the iterate modifier :iterate modifier. is included. For example, this search returns all MedicationRequest Medication Request resources and their prescribing Practitioner Resources for the matching MedicationDispense Medication Dispense resources: Show as: HTTP GET | HTTP POST GET [base]/MedicationDispense?_include=Medication:prescription &_include:iterate=MedicationRequest:requester&criteria... POST [base]/MedicationDispense/_search Content-Type: application/x-www-form-urlencoded _include=MedicationDispense:prescription&_include:iterate=MedicationRequest:requester&criteria... Details about the iterate modifier can be found in the section Modifier: iterate .

GET [base]/MedicationDispense?_include=MedicationDispense:prescription
    &_include:iterate=MedicationRequest:performer&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 iteratively, so it will retrieve observations that are directly related, and also any related observations to any other included observation. Show as: HTTP GET | HTTP POST GET [base]/Observation?_include=Observation:has-member&criteria... POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _include=Observation:has-member&criteria... GET [base]/Observation?_include:iterate=Observation:has-member&criteria... POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _include:iterate=Observation:has-member&criteria...

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

Both _include and _revinclude use the wild card "*" for the search parameter name, indicating that any search parameter of type=reference be included. Though both clients and servers need to take care not to request or return too many resources when doing this. Most notably, using iterative wildcards inclusions might lead to the retrieval of the full patient's record, or even more than that: resources are organized into an interlinked network and broad _include paths may eventually traverse all possible paths on the server. For servers, these iterative and wildcard _include s are demanding and may slow the search response time significantly.

It is at the server's discretion how deep to iteratively 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. Because iterative search is generally resource intensive, it is not the default behavior.

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.

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 Note: when considering using _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 Binary resource. For example, the include path may point to an attachment which is by reference, like this: Show as: FHIR+JSON | FHIR+XML "content": { "contentType": "image/jpeg", "url": "http://example.org/images/2343434/234234.jpg" } <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. 3.2.1.7.8.3 Graph Definitions (_graph) TU While inline requests for additional resources are flexible, there are times when a more structured approach is desired (e.g., optimizing frequent requests, etc.). To facilitate a structured approach, the _graph result parameter is defined. The _graph result parameter functions as a reference _revinclude, implementers should also consider whether using GraphQL type search parameter. The input is a reference to a and/or GraphDefinition resource, which is used to define the graph of desired resources for inclusion. are more appropriate approaches in their context.

3.2.1.7.8.4 3.1.1.5.5 Contained Resources (_contained)

By default, search results only include resources that are not contained in other resources. However, A chained parameters condition will be evaluated inside contained resources. To illustrate this, consider a MedicationRequest resource (id: MedicationRequest/23 ) that has a contained Medication resource specifying a custom formulation that has ingredient with an a itemCodeableConcept "abc" in "http://example.org/medications" (id: Medication/m1 ). "http://acme.com./medications". In this case, the a search: Show as: HTTP GET | HTTP POST GET [base]/MedicationRequest?medication.ingredient-code=abc POST [base]/MedicationRequest/_search Content-Type: application/x-www-form-urlencoded medication.ingredient-code=abc

GET MedicationRequest?medication.ingredient-code=abc

will include MedicationRequest/23 in the results as a match. The search chained into the contained MedicationRequest resource and met in the search criteria. results. However, the this search: Show as: HTTP GET | HTTP POST GET [base]/Medication?ingredient-code=abc POST [base]/Medication/_search Content-Type: application/x-www-form-urlencoded ingredient-code=abc

GET Medication?ingredient-code=abc

will not find Medication/m1 - include the medication is a contained Medication resource within a MedicationRequest and not subject to search. This is because in the results, since either the wrong type of resource would be returned (the MedicationRequest containing the Medication), returned, or the contained resource would be returned without its container resource (just the Medication), resource, which would be missing the required provides context provided by to the container contained resource.

Clients can modify the search this behavior for contained resources using the _contained parameter, which can have one of the following values:

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

When contained resources are being returned, the server can 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 : contained: return only the contained resource

To return just When returning a container resource, the contained Medication ( Medication/m1 ), server simply puts this in the following search could be used: Show as: HTTP GET | HTTP POST GET [base]/Medication?ingredient-code=abc&_contained=true&_containedType=contained POST [base]/Medication/_search Content-Type: application/x-www-form-urlencoded ingredient-code=abc&_contained=true&_containedType=contained This search would return a result bundle with the contained Medication records. Note that results:

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

      </MedicationRequest>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>

In the fullUrl case of returning container resources, the entry points to server SHALL populate the containing resource first entry.search.mode element, as shown, so that the client can pick apart matches and includes (since the required resolution for usual approach of doing it by type might not work).

If the return type is the contained resource: Show as: FHIR+JSON | FHIR+XML { "resourceType": "Bundle", ... "entry": [{ "fullUrl": "http://example.com/fhir/MedicationRequest/23#m1", "resource": { "resourceType": "Medication", "id": "m1", ... }, "search": { "mode": "match" } }] } <Bundle> ... <entry> <fullUrl value="http://example.com/fhir/MedicationRequest/23#m1"/> <resource> <Medication> <id value="m1"> ... </Medication> </resource> <search> <mode value="match"/> </search> </entry> </Bundle> resource, this must be done slightly differently:

<Bundle>
  ...
  <entry>
    <fullUrl value="http://example.com/fhir/MedicationRequest/23#m1"/>
    <resource>
      <Medication>
        <id value="m1">
        ...
      </Medication>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>

Similarly, In this case, the search could be performed to return fullUrl informs the MedicationRequests containing client that this is a contained resource, along with indicating the Medication records: Show as: HTTP GET | HTTP POST identity of the containing resource.

3.1.1.5.6 GET [base]/Medication?ingredient-code=abc&_contained=true&_containedType=container POST [base]/Medication/_search Content-Type: application/x-www-form-urlencoded ingredient-code=abc&_contained=true&_containedType=container This search would return a result bundle with External References

If the container MedicationRequest _include records and path selects a reference that refers to a resource on another server, the relevant contained resources. Note server can elect to include that even though resource in the request was search results for Medication resources, the container MedicationRequest entries are categorized with convenience of the client.

If the mode _include of match : Show as: FHIR+JSON | FHIR+XML 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 { "resourceType": "Bundle", ... "entry": [{ "resource": { "resourceType": "MedicationRequest", "id": "23", ... "contained": [{ "resourceType": "Medication", "id": "m1", ... }], ... }, "search": { "mode": "match" } }] } <Bundle> ... <entry> <resource> <MedicationRequest> <id value="23"> ... <contained> <Medication> <id value="m1"> ... </Medication> <contained> </MedicationRequest> </resource> <search> <mode value="match"/> </search> </entry> </Bundle> 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.

3.2.1.7.8.5 3.1.1.5.7 Paging and Other Resources

When returning paged results for a search with _include 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.

3.2.1.8.1 3.1.1.5.8 Parameters for all resources Summary

The following parameters apply to all resources : _content , _filter , _has , _id , _in , _language , _lastUpdated , _list , _profile , _query , _security , _source , _tag , _text , _type . In addition, client can request the search parameters _text and _filter , (documented below) also applies server to all return only a portion of the resources (as do by using the search result parameters). 3.2.1.8.1.1 _content The standard search parameter _content is used to allow searching all textual content of a resource. _summary :

   GET [base]/ValueSet?_summary=true

The _content _summary search parameter is defined as a special type parameter. While the actual format used by the parameter is implementation-dependant, requests the search is some form of string which can be used for advanced searching (similar server to _text ). For example, the following search: Show as: HTTP GET | HTTP POST GET [base]/Observation?_content=cancer OR metastases OR tumor POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _content=cancer OR metastases OR tumor is return a search for Observations that contain any subset of the phrases "cancer", "metastases", and "tumor" anywhere in the resource. For example, the key words may appear in: Observation.text - Text summary of the resource, for human interpretation Observation.code.text - Type of observation, Plain text representation of the concept Observation.note - Comments about the observation etc. The server MAY choose to search for related terms (e.g., "carcinoma", etc.), but is not required to do so. More information It can be found in contain one of the section Text Search Parameters . following values:

The standard search parameter _language is used to match resources based on the language intent of the resource used. Note that match testing is performed against the element Resource.language and does not match against the actual language used in elements. The _language _summary search parameter is defined as a token type parameter. Resource.language is restricted to Common Languages and All Languages . For example, reduce the search: Show as: HTTP GET | HTTP POST GET [base]/Questionnaire?_language=es POST [base]/Questionnaire/_search Content-Type: application/x-www-form-urlencoded _language=es will match Questionnaire resources with a Resource.language of es (Spanish). 3.2.1.8.1.6 _lastUpdated The standard search parameter _lastUpdated is used to match resources based total processing load on when the most recent change has been made. The _lastUpdated search parameter is defined server, client, and resources between them such as a date type parameter. Matching is performed against the element Resource.meta.lastUpdated , or an implementation's internal equivalent. For example, the following search: Show as: HTTP GET | HTTP POST GET [base]/Observation?_lastUpdated=gt2010-10-01 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _lastUpdated=gt2010-10-01 network. It is a search most useful for Observations changed since October 1, 2010. Applications considering using this parameter should also consider defined synchronization approaches - RESTful history and Subscriptions framework . 3.2.1.8.1.7 _list resources that are large, particularly ones that include images or elements that may repeat many times. The standard search parameter _list purpose of the summary form is used to test resources against references in allow a List resource. The _list search parameter is defined as client to quickly retrieve a special type parameter. Input values are treated as token values - either the logical identifier (id) large set of resources, and let a List or a literal user pick the appropriate one. The summary for a functional list, as an element is defined in Current Resource Lists . Note that when using functional lists, servers are not required to make the lists available allow a user to quickly sort and filter the clients as List resources, but may choose to do so. For example: Show as: HTTP GET | HTTP POST Description Search Any resource referenced by List "101" GET [base]/?_list=101 POST [base]/_search Content-Type: application/x-www-form-urlencoded _list=101 Conditions referenced by List "102" GET [base]/Condition?_list=102 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded _list=102 Female Patients referenced by List "103" GET [base]/Patient?_list=013&gender=female POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _list=013&gender=female Encounters for Patients in Group "104" GET [base]/Encounter?patient._in=Group/104 POST [base]/Encounter/_search Content-Type: application/x-www-form-urlencoded patient._in=Group/104 Current allergy list for patient "42" GET [base]/AllergyIntolerance?patient=42&_list=\$current-allergies POST [base]/AllergyIntolerance/_search Content-Type: application/x-www-form-urlencoded patient=42&_list=\$current-allergies For more information about membership testing, see Searching by Membership . 3.2.1.8.1.8 _profile The standard search parameter _profile is used to match resources based and typically omit important content on values in the Resource.meta.profile element. Note basis that the profile search does not test conformance of a entire resource against any profile, just the values of that element. The _profile search parameter is defined as a reference type parameter. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?_profile=http://hl7.org/fhir/StructureDefinition/bp POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _profile=http://hl7.org/fhir/StructureDefinition/bp will match Observation resources that contain be retrieved when the user selects a Resource.meta.profile of http://hl7.org/fhir/StructureDefinition/bp . resource.

The standard search parameter _query is used to execute a pre-defined and named query operation. Note that 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 are not recognize the _query parameter value. The _query search parameter is defined as a special type parameter. Input obliged to the parameter is treated as return just a token-based search TU , requiring an exact match to the query name, summary as defined by the OperationDefinition.code element. requested. There can are only ever be one _query parameter in a set limited number of search parameters. Servers processing search requests SHALL refuse to process a search request if they do not recognize the _query parameter value. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?_query=current-high-risk&ward=1A POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _query=current-high-risk&ward=1A is a request summary forms defined for resources in order to run the named query current-high-risk against Patient resources, with a parameter named ward set allow servers to store the value 1A . If a server does not have a definition for current-high-risk , it would reject the request. More information about named queries can be found summarized form(s) in advance. Servers SHOULD mark the section Named Queries . 3.2.1.8.1.10 _security The standard search parameter _security is used to match resources based on security labels in the Resource.meta.security element. The _security search parameter is defined as a token type parameter. For example, with the search: Show as: HTTP GET | HTTP POST tag GET [base]/Observation?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R will match Observation resources that contain a Resource.meta.security value matching the system http://terminology.hl7.org/CodeSystem/v3-Confidentiality SUBSETTED and code of R . For more information about security labels, please see the Security Labels page. 3.2.1.8.1.11 _source The standard search parameter _source is used to match resources based on source information in the Resource.meta.source element. Meta.source is a lightweight way of providing minimal provenance for resources. If more functionality is required, use of Provenance is recommended. The _source search parameter is defined as a uri type parameter. For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Patient?_source=http://example.com/Organization/123 POST [base]/Patient/_search Content-Type: application/x-www-form-urlencoded _source=http://example.com/Organization/123 will match Patient resources ensure that contain the Resource.meta.source value of http://example.com/Organization/123 . 3.2.1.8.1.12 _tag The standard search parameter _tag incomplete resource is not accidentally used to match resources based on tag information in the Resource.meta.tag element. Tags are intended to be used to identify and relate resources to process and workflow. The _tag search parameter is defined as overwrite a token type parameter. complete resource.

For example, the search: Show as: HTTP GET | HTTP POST GET [base]/Observation?_tag=http://terminology.hl7.org/ValueSet/v3-SeverityObservation|H POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _tag=http://terminology.hl7.org/ValueSet/v3-SeverityObservation|H will match Observation resources Note that contain a tag value matching the system http://terminology.hl7.org/ValueSet/v3-SeverityObservation _include and code H , indicating that an observation has been tagged as potentially life-threatening or _revinclude parameters cannot be mixed with the potential cause permanent injury. 3.2.1.8.1.13 _text The standard search parameter _text is used to perform searches against the narrative content of a resource. _summary=text .

The _text search parameter is defined as a string Implementation Note: type parameter. While the actual format used by the parameter is implementation-dependant, the search There is some form of string which can be used for advanced searching. For example, question about the following search: Show as: HTTP GET | HTTP POST GET [base]/Observation?_text=cancer OR metastases OR tumor POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded _text=cancer OR metastases OR tumor is a search for Observations that contain any inclusion of the phrases "cancer", "metastases", and "tumor" extensions in their narrative text ( Observation.text ). For example, the key words summary. Additional rules may appear in: Observation.text - Text summary of the resource, for human interpretation Observation.code.text - Type of observation, Plain text representation of the concept The server MAY choose to search for related terms (e.g., "carcinoma", etc.), but is not required to do so. More information can be found made around this in the section Text Search Parameters . future.

3.2.1.8.1.14 3.1.1.5.9 _type Elements

The standard search parameter _type is used to allow filtering If one of types in searches that are performed across multiple resource types (e.g., searches across the server root). The _type search parameter is summary views defined as a special type parameter, because there above is no standard path expression for searching the types not appropriate, a client can request a specific set of elements be returned as part of resources. However, the parameter is a token parameter restricted to the Resource Types Value Set. For example, resource in the following search: Show as: HTTP GET | HTTP POST GET [base]/?_type=Observation,Condition&patient=Patient/123 POST [base]/_search Content-Type: application/x-www-form-urlencoded _type=Observation,Condition&patient=Patient/123 is a search for Observations and Conditions that are about the patient Patient/123 . Since results using the patient _elements search parameter is valid on both the Observation and Condition resources, the search is valid. parameter:

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

The same search would not be valid if the _type _elements parameter was excluded, since patient is not consists of a search parameter that works across all resources. More information can be found comma-separated list of base element names such as, elements defined at the root level in the section Searching Multiple Resource Types . 3.2.1.8.2 Parameters for each resource In addition resource. Only elements that are listed are to the common parameters defined for be returned. Clients SHOULD list all resources, each FHIR resource type defines its own set of search parameters with their names, types, mandatory and meanings. These search parameters are on the same page as the modifier elements in a resource definitions, and are also published as part of the standard Capability statement ( XML 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 list of the paths contain matching content. If a path matches, the whole resource is returned in the search results. elements. The client may have to examine the resource list of elements does not apply to determine which path contains the match. included resources .

Servers are not required obliged to implement any of return just the standard search parameters. However, servers requested elements. Servers SHOULD support always return mandatory elements whether they are requested or not. Servers SHOULD mark the resources with the tag _id SUBSETTED parameter TU . Servers MAY also define their own parameters. Note to ensure that all search parameters defined in this specification, both common and resource-specific, are listed in the search parameter registry . incomplete resource is not actually used to overwrite a complete resource.

3.2.1.8.3 3.1.1.5.10 Text Search Parameters Relevance

The special text search parameters, _text and _content , search on the narrative of the resource, and the entire content of the resource respectively. Just like string parameters using the :text modifier, these parameters SHOULD support Where a sophisticated search functionality of the type offered by typical text indexing services. The value of specifies a non-deterministic sort, the parameter is search algorithm may generate a text-based search, ranking score to indicate which may involve searching multiple words with thesaurus and proximity considerations, and logical operations such as AND, OR etc. For example (note that the values are unescaped for clarity): Show as: HTTP GET | HTTP POST GET [base]/Condition?_text=(bone OR liver) AND metastases POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded _text=(bone OR liver) AND metastases This request returns all Condition resources with the word "metastases" and either "bone" or "liver" in meet the narrative. specified criteria better than others. The server MAY choose to search for related words as well. can return this score in entry.score :

  <entry>
    <score value=".45"/>
    <Patient>
      ... patient data ...
    </Patient>
  </entry>

Implementers could consider using the rules specified by the OData specification for the $ search parameter . Typical implementations would use Lucene, Solr, an SQL-based full text search, or some similar indexing service. 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.

3.2.1.9 3.1.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: Show as: FHIR+JSON | FHIR+XML "link": { "relation": "self", "url": "http://example.org/Patient?name=peter" } <link> <relation value="self"/> <url value="http://example.org/Patient?name=peter"/> </link>

  <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 _id above).
• Servers can choose when and where to implement parameter chaining, and when and where they support the _include parameter.
• Servers can declare additional parameters in the profiles referenced from their Capability statements. Servers SHOULD should define custom search parameters with codes starting with a hyphen ("-") "-" character to ensure that the names they choose do not clash with future parameters defined by this specification. TU
• 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 _sort parameter.

3.1.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 _query parameter:

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

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

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 _query parameter value.

3.2.1.10 3.1.1.8 Search Result Currency

The results of a search operation are only guaranteed to be current at the instant 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.

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

3.2.1.11 3.1.1.9 Summary Tables

Cross-map between search parameter types and Datatypes: Data types: