This page is part of the FHIR Specification (v3.3.0: R4 Ballot 2). The current version which supercedes this version is 5.0.0 . For a full list Continuous Integration Build of available versions, see FHIR (will be incorrect/inconsistent at times).
See the Directory of published versions . Page versions: R5 R4B R4 R3 R2

3.1.1 3.2.1 Search

Responsible Owner: FHIR Infrastructure Work Group

Ballot Standards Status : Normative

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 Summary Table Contents

• Introduction
  • Notes on URL-Encoding
  • Search Parameter Types Overview
  • Search Inputs Parameters for all resources
  • Search Contexts
  • Search result parameters Responses
    • Bundle Type Number
    • Self Link - Understanding a Performed Search Date/DateTime
    • Other Links - Paging String
    • Matches, Inclusions, and Outcomes - Bundle Entries Token
    • Handling Errors Reference
• Transport Protocols
  • Composite Multi-datastore Considerations Quantity
  • Batching Searches URI
  • Search in Messaging
• _id Search Parameters
  • Search Test Basics
  • _lastUpdated Matching and Cardinality
  • Matching and Sub-Elements
  • _tag Searching Multiple Values (joining with AND or OR)
  • Modifiers
  • _profile Prefixes
  • Escaping Search Parameters
  • _security Search Types and FHIR Types
  • Basic Parameter Types: date , number , quantity , reference , string , token , uri
  • Extended Parameter Types: composite , resource , special _text
• Special Search Conditions
  • Searching Ranges _content
  • Searching Identifiers
    • Logical Identifiers _list
    • Searching by Membership
    • Identifiers and References
    • Canonical Identifiers
  • References and Versions
  • Searching Hierarchies
  • Searching MIME Types
  • Chaining (chained parameters)
  • Reverse Chaining _has
  • Handling Missing Data
  • _type Advanced Filtering
  • Searching Multiple Resource Types
  • _sort Implicit Resources
  • Named Queries
  • _count Searching for Additional Resources
• Modifying Search Results
  • Sorting (_sort) _include
  • Total number of matching resources (_total)
  • _revinclude Limiting Page Size (_count)
  • Limiting Total Result Size (_maxresults)
  • Summary (_summary) _summary
  • Selecting Elements (_elements)
  • _elements Relevance (_score)
  • Including Referenced Resources
    • Inline Requests (_include, _revinclude)
    • External References
    • Graph Definitions (_graph)
    • Contained Resources (_contained) _contained
    • Paging and Other Resources
• _containedType Standard Parameters
  • Parameters for All Resources In addition, there is a special search parameters
  • _query Parameters for Each Resource
  • Text Search Parameters and _filter
• Server Conformance that allow for an alternative method of searching. Also, there is a single page that lists all the search parameters . 3.1.1.2
• Search Result Currency
• Conformance Summary
• Summary Tables

3.2.1.2 Introduction

In FHIR Search is the simplest case, a primary mechanism used to find and list resource instances. The search mechanism is executed by performing a GET operation in designed to be flexible enough to meet the RESTful framework: needs of a wide variety of use cases, and yet be simple enough to be commonly useful.

For this RESTful search (see definition in RESTful API ), the parameters are In a series typical RESTful interface, collections of name=[value] pairs encoded in the URL or instances are returned as an application/x-www-form-urlencoded submission for a POST: POST [base]/[type]/_search{?[parameters]{&_format=[mime-type]}} The server determines which arrays of the set a type. In order to include related information (e.g., number of resources it serves meet the specific criteria, total results), support extended functionality (e.g., paging), and returns the results allow multiple resource types in the HTTP response as results (e.g., returning Patient and Encounter resources), FHIR Search instead returns a bundle Bundle which includes the resources that are the results resource, with a type of searchset . Resources included in the search. results appear as individual entries in such a bundle. Note that the _format parameter works for search like for other interactions . More information about returned contents and elements can be found in Managing Returned Resources

Search operations There are safety issues associated with the implementation of searching that implementers need to always keep in mind. Implementers SHOULD review the safety checklist . § ¹

3.2.1.2.1 Notes on URL-Encoding

Note that for the readability of this document, syntaxes and examples are executed shown without URL-Encoding escaping applied. For example, a syntax of [url]|[version] will be URL encoded during transmission as [url]%7C[version] . when describing the format of token parameters, the vertical pipe character (

|

%7C

As noted in one the Escaping Search Parameters section, URL Encoding is transparent when processing. Clients and servers SHOULD be robust in their handling of three URLs present in the content of FHIR bundles, such as in Bundle.link.url . § ²

For example, the following unencoded request:

would actually be transmitted over-the-wire as:

3.2.1.2.2 Search Overview

Though search operations are typically performed via REST, search is defined contexts to be useful independently of HTTP. Note that control which set while different formats of resources search requests are being searched: functionally equivalent, implementation considerations can result in differences inherent to searching via a particular protocol. Details can be found on the Search section of the HTTP page.

3.2.1.2.3 Search Inputs

Input to search operations are referred to as Search Parameters . A search parameter can be:

• A specified resource type: a filter across all resources (e.g., GET [base]/[type]?parameter(s) _id , which is present on every resource),
• A specified compartment , perhaps with a specified filter on a specific resource type in that compartment: (e.g., GET [base]/Patient/[id]/[type]?parameter(s) Patient.birthDate , which applies to the Patient resource,)
• All resource types: GET [base]?parameter(s) (parameters common to all types only) a textual search across a resource, or
• a parameter that affects search results .

Search 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 define additional parameters with different meanings with names that only differ in case. § ³

Order of operations can also be implemented is not driven by order in the messaging framework . URL - with the exception of sort. First all filters are applied, then the result set is sorted, then paging is applied, and then included resources ( _include , _revinclude ) are added for each page.

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

Search using In the absence of any search filters, e.g., GET [base] , GET [base]/Patient , or POST [base]/_search may include sensitive information or POST [base]/Patient/_search with no body, a server SHOULD return all records in scope of the search parameters. Therefore, secure communications context. § ⁴ Servers MAY reject a search as overly-broad, and endpoint management SHOULD return an appropriate error in that situation (e.g., too-costly ). § ⁵

For more information about how search inputs are recommended, tested against resources, please see Security Communications Search Parameters .

3.2.1.2.4 Search Contexts

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

• All resource types: Note that if the _type parameter is included, all other search parameters SHALL be common to all provided types, and if _type is not included, all parameters SHALL be common to all resource types. § ⁶ Show as unencoded: 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 unencoded: 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.

  The outcome of a compartment search is the same as the equivalent system or type search and will have full URLs that are not compartment-specific (e.g. fullUrls reference [base]/Observation/[id] , not [base]/Patient/[pat-id]/Observation/[id] ). References within returned resources are also not rewritten to include the compartment path.

  Show as unencoded: 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)

3.2.1.3 Search Responses

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 in the bundle resource.

The response to any search operation is always a list of 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 . The Bundle.type value of searchset designates that a bundle is a search response and may be used in processing to classify bundles.

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 the parameters that were actually used to process a search. § ⁷ Applications processing 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 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. § ⁹ This means that the same self link 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. § ¹⁰ 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 for additional data. § ¹²

In some cases, a server might introduce additional search parameters into the executed query based on authorization rules. Servers MAY include such filters in the self link. § ¹³ Clients SHOULD be able to handle search parameters in a self link that they did not request. § ¹⁴ Servers SHOULD consider whether exposing search parameters in the self link would constitute inappropriate leakage of security information. § ¹⁵

3.2.1.3.3 Other Links - Paging

In addition to the self link, many bundles may contain links relevant to paging. These are identified via the relation value in the links. Common links include: first , last , next , prev , and previous . Note that prev and previous are widely-used synonyms and are interchangeable.

As with the self link, all relevant paging links SHALL be expressed as GET requests. § ¹⁶ Servers SHOULD NOT include content that is considered sensitive in URLs, excluding the self link. § ¹⁷

For best practices on when to include or exclude paging links, see the Paging Best Practices section on the FHIR HTTP page.

3.2.1.3.4 Matches, Inclusions, and Outcomes - Bundle Entries

Within the results bundle, there are three types of entries that may be present, identified by the search mode of the entry: match , include , or outcome .

Note that entries are unique (not allowed 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 search results indicate that a record is being returned because it meets the parameters specified in the search request (e.g., a record the client requested).

3.2.1.3.4.2 Include

Entries marked with include 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 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.

3.1.1.3 3.2.1.3.5 Handling Errors

If a server is unable to execute a search request, it may MAY either return an error for the request or return success with an outcome containing details of the 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: An § ¹⁹ Note that an empty search result is not a failure. an error.

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

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. (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 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: GET [base]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456 Show as unencoded: 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 and there is no patient for MRN 123456, the server would may return a bundle with no results and a warning outcome, such as this .

Unknown and unsupported parameters

Servers may can 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 request specific server should behave, behavior 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 prefer request, but are not required to do so. § ²³ For more information, see HTTP Headers on the HTTP Page.

3.1.1.4 3.2.1.4 Standard Parameters Transport Protocols

This specification defines FHIR Search operations in both HTTP POST and GET . For details about the HTTP methods regarding search, please see the Search section of the HTTP page.

3.1.1.4.1 3.2.1.4.1 Parameters for all resources Multi-datastore Considerations

The following parameters apply to all resources : _content , _id , _lastUpdated , _profile , _query , _security , _source , _tag . 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.

In addition, these "single endpoint/multiple back-end" scenarios, it is possible that the search parameter _text and _filter , (documented below) also applies internal repositories have different capabilities when it comes to all resources (as do the search result parameters). search.

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

This search finds the patient resource with the given id (there In any event, systems can only handle such limitations in at least four ways:

1. By requiring that some searches include certain mandatory criteria. For example, Observation searches might require that the category parameter be present (and only have one resource for a given id). Functionally, this is equivalent to a simple read operation : GET [base]/Patient/23 However, value) or Patient searches might require that the search with parameter _id organization returns a bundle with the requested resource, instead of just the resource itself. Additional parameters parameter be present. These permitted combinations can be added which may provide additional functionality conveyed by extensions on top of this base read equivalence (e.g. the _include ). Note CapabilityStatement . Clients that although fail to satisfy the _id parameter has a type of token, because servers SHALL use exact match with it, there is no 'combination' rules will not be able to search successfully.
2. By having the intermediary system for that handles the _id parameter. Note dispatch to different back ends perform supplementary filtering such that matches on _id are always case sensitive. The any search parameter _lastUpdated can parameters that cannot be used to select resources based on enforced by the back-end system are instead applied at the intermediary layer, and thus from a 'client' perspective the last time they were changed: GET [base]/Observation?_lastUpdated=gt2010-10-01 This search finds any observations changed since 1-Oct 2010. When this search parameter is used, applications should consider synchronization approaches ( RESTful history or was executed as desired.
3. By returning a warning message in the Subscription resource ). The search parameters _tag , _profile OperationOutcome and _security (see also: Handling Errors parameters search ) indicating that not all filters were applied on the equivalent elements in the meta element . For example, GET [base]/Condition?_tag=http://acme.org/codes|needs-review searches for all 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 resources. This SHOULD only DiagnosticReport resources that are tagged as conforming to a particular profile. The second reference occur in situations where it is relative, known that some filters haven't been applied. § ²⁴
4. By exposing distinct FHIR endpoints for each data source and refers a local profile on the same server. different capabilities in an endpoint-specific manner.

3.1.1.4.2 3.2.1.4.2 Parameters for each resource Batching Search Requests

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

Some When submitting multiple requests via a batch or transaction, the returned bundle is for the batch or transaction as an operation. Therefore, two search parameters defined by resources are associated with more than one path requests in a resource. This means batch would return a bundle that the search parameter matches if any contains at least two entries, each of the paths contain matching content. If a path matches, the whole resource which is returned in the result of a search results. The client may have to examine request (e.g., the resource to determine which path contains batch result bundle will contain entries that are the match. search result bundles).

Servers When bundling requests via batch or transaction , HTTP verbs and the URLs for RESTful interfaces are used. When requesting searches in a bundle, systems SHOULD accept searches via GET, even if they do not required typically accept GET-based searches. § ²⁶ There is no standard way to implement any of convey POST-based searches within a Bundle and the standard architectural differences when searching via GET or POST are not relevant within a Bundle. Servers receiving searches within a Bundle SHOULD NOT impose any GET-specific limitations on search parameters (except for (i.e., restrictions not imposed on POST-based searches) that they would impose if the _id parameter GET-based search had been received outside a Bundle. § ²⁷

3.2.1.4.3 Search via Messaging

Servers MAY support FHIR Messaging . § ²⁸ The mapping of search requests into messages is described above), and may define their own parameters. in more detail in the section Invoking Search via Messages .

3.1.1.4.3 3.2.1.5 Search Parameter Types Parameters

Each 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 search parameter is defined by a type that specifies how the search parameter behaves. These are the defined search parameter types:

The Individual search parameters can MAY also append allow "modifiers" that control their behavior. § ²⁹ The kinds of modifiers that available is dependent depend on the type of the search parameter. More details can be found in the Modifiers section of the search page.

Some search parameter being modified. 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.

3.1.1.4.4 3.2.1.5.1 Modifiers Search Test Basics

Parameters 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 inputs are dereferenced by a server based on their listing in the server's CapabilityStatement , according to the CapabilityStatement.rest.resource.searchParam.name element. These values are typically a computer-friendly code defined per by the SearchParameter resource for the parameter, either in SearchParameter.code or SearchParameter.alias . Note that the values listed in the SearchParameter resource are only suggestions, though some implementation guides will add requirements for improved interoperability.

Search input values are parsed according to the search parameter type, as defined in the relevant SearchParameter resource. Parameter names may specify The rules for parsing a modifier as search input value into the equivalent FHIR type can be found on the search page (e.g., converting a suffix. token input into a Coding ).

The modifiers type of test used to compare values are separated from 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 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 colon. Modifiers are: 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. § ³⁰

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 (except combination): :missing 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 can consider the _filter ; e.g. gender:missing=true (or false). Searching 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 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 unencoded: 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 unencoded: 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 gender:missing=true 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 unencoded: 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 all Patient records with EITHER a given name of "valueGivenA" OR "valueGivenB". This includes patient records that have BOTH "valueGivenA" and "valueGivenB" (e.g., inclusive or).

Each value of an "OR" query may contain a prefix if allowed by the resources search type. For example, a search for a heart rate value ( LOINC 8867-4 ) outside of the 'normal resting range of adults': Show as unencoded: 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 don't 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 unencoded: 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 unencoded: 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, the gender described use case of searching for a patient by any part of their name has a search parameter (which usually equates 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 having a combined search parameter defined or supported on a server, the relevant results can be retrieved by issuing multiple queries, either serially or in a batch.

The following table contains examples of how joins work depending on their element types. Note that this table is illustrative and not comprehensive. Additionally, the joins listed below can be combined in a single request to form more complicated logic. For brevity, this table demonstrates the joins only against the same element type, though this is not a requirement. For example, it is common to join one parameter against a simple scalar element with another that is an array of complex elements. In this table, the following definitions are used:

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

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.modifier element, which is bound to the search-modifier-code value set. § ³¹ Servers SHALL support any modifiers present in search 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 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 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:

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 simple 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 with search types reference , token , and uri . The exact semantics for use vary depending on the type elements, :missing=true will match of search parameter:

3.2.1.5.5.1.1 above with reference search type parameters and Reference FHIR type targets

When the above modifier is used with a reference type search parameter and the target is an element with the FHIR type Reference , the search is interpreted as a hierarchical search on linked resources of the same type, including exact matches and all elements 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 either those references establish a hierarchy. For example, the underlying 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 omitted or where 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 above modifier on a reference search type parameter, 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 unencoded: 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 reference search type parameters and canonical FHIR type targets

When the above modifier is used with a reference type search parameter and the target is an element with the FHIR type canonical , the search is present interpreted as a version search against the canonical resource. The format of the parameter is either [url] or [url]|[version] (see Encoding Note ). This search is only allowed if the version scheme for the resource is either specified or the server chooses to infer it. Version-related search criteria against resources with extensions but unknown versioning schemes SHALL be either ignored or rejected. § ³⁷ The above modifier comparison is performed as a 'greater than' against the version-scheme defined by the resource. Any versions that match the specified search are excluded from the result. The versions returned will be listed in no @value particular order.

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 ) and can cause issues with parsing of the parameter.

More information can be found in the section References and Versions .

3.2.1.5.5.1.3 above with token search type parameters

When the above modifier is used with a token type search parameter, the supplied token is a concept with the form [system]|[code] (see Encoding Note ) 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 modifier on a token, all typically-valid search parameter token inputs are allowed.

For example, the search: Show as unencoded: 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.

3.2.1.5.5.1.4 above with uri search type parameters

When the above 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 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 modifier on a uri, all typically-valid search parameter uri inputs are allowed.

For string: :exact example, the search: Show as unencoded: 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 (the - full match needs
• 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 be exact, search hierarchies of 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 and Reference FHIR type targets

When the below modifier is used with a reference type search parameter and the target is an element with the FHIR type Reference , 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 below 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 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 partial matches, case sensitive hierarchical meaning is intended. Further discussion about the requirements and accent-sensitive), or :contains uses for this type of search can be found in the section Searching Hierarchies .

When using the below (case insensitive modifier on a hierarchical reference, all typically-valid search parameter reference inputs are allowed. Note that the actual Resources that establish hierarchical references and accent-insensitive, partial the search parameters used are listed in the Circular Resource References section of the References page.

For example, the search: Show as unencoded: 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 at start or end), instead 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 default behavior (case insensitive and accent-insensitive, partial matches at first floor
• A101 , Location/A101 , https://example.org/Location/A101 - child of A100, room 101
• A1.. , etc. - child of A100, rooms on the start first floor
• A200 , Location/A200 , https://example.org/Location/A200 - child of BuildingA, representing the string). second floor
• etc.

3.2.1.5.5.2.2 below with reference type search parameters and canonical FHIR type targets

When the below modifier is used with a reference type search parameter and the target is an element with the FHIR type canonical , the search is interpreted as a version search against the canonical resource. The format of the parameter is either [url] or [url]|[version] (see Encoding Note ). This search is only allowed if the version scheme for the resource is either specified or the server chooses to infer it. Version-related search criteria against resources with unknown versioning schemes SHALL be either ignored or rejected. § ³⁸ The below modifier comparison is performed as a 'less than' against the version-scheme defined by the resource. Any versions that match the specified search are excluded from the result. The versions returned will be listed in no particular order.

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 ) and can cause issues with parsing 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, the supplied token is a concept with the form [system]|[code] (see Encoding Note ) and the intention is to test whether the coding in a resource 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 token: :text example, the search: Show as unencoded: 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 (the SNOMED 'Hepatitis due to infection' would match does 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 searches matching based on URL path segments. Because of the text portion 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 CodeableConcept uri, all typically-valid search parameter uri inputs are allowed.

For example, the search: Show as unencoded: 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

The code-text modifier allows clients to indicate that a supplied string input is used as a case-insensitive and combining-character insensitive test when matching 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 display portion 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.

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 unencoded: 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 Coding), instead 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 input is used as a containment test when matching against the target value. The exact semantics for use vary depending on the type of search parameter.

3.2.1.5.5.4.1 contains with reference search type parameters

When using the default contains modifier with reference type search which uses codes. Other defined modifiers parameters, reference test values are :in , :below , allowed (e.g., a logical identifier).

The search parameter is a reference to a resource that is part of a hierarchical tree, and the search should return the specified resource along with all resources above (ancestors) and below (descendants) it in the hierarchy. This is equivalent to combining both :above and :not-in :below which searches plus the specified resource itself.

This modifier is useful when you need the full context of a hierarchical resource in a single query. For example, when working on a specific task in a task tree, you may want to see the entire branch from root to leaves in one request.

For example, the search: Show as unencoded: HTTP GET | HTTP POST GET [base]/Task?part-of:contains=Task/T1A POST [base]/Task/_search Content-Type: application/x-www-form-urlencoded part-of:contains=Task/T1A would match any Task resources that contain task T1A in a hierarchy, including T1A itself, its ancestors, and its descendants. Given a task tree where:

• T1 is the root task
• T1A and T1B are described below. sub-tasks of T1
• For reference: :[type] T1A1 and T1A2 are sub-tasks of T1A

This search would return: T1 (ancestor), T1A (the specified task), T1A1 and T1A2 (descendants).

Note: The contains where [type] modifier can only be used with reference search parameters that support hierarchical relationships (typically those that reference the same resource type they are defined on, like Location.partOf or Task.partOf ).

3.2.1.5.5.4.2 contains with string and uri search type parameters

When using the contains modifier with string or uri type search parameters, all typically-valid search parameter string inputs are allowed.

The contains modifier in this context allows clients to indicate that a supplied string input is used as a case-insensitive and combining-character insensitive test when matching anywhere in the name target string. Note that the handling of extended grapheme clusters is within the discretion of the server, i.e., the server decides if a type 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 resource, :identifier, and, scope for some parameters, :above the FHIR standard, and :below the results of such operations are implementation dependent.

For example, the search: Show as unencoded: 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)
• For uri: :below , :above 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 instead of an a supplied string input is the complete and exact value that tested for a match, either including casing and combining characters. Note that the handling of extended grapheme clusters is within the discretion of the server, i.e., the server decides if a string search term left parameter matches the value, on canonically equivalent characters or vice-versa. 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.

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 unencoded: 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)

3.2.1.5.5.6 identifier

The identifier modifier allows clients to indicate that a supplied token is used to match against the Reference.identifier element of a reference instead of the Reference.reference element. The format of the parameter is [system]|[code] (see Encoding Note ). Note that chaining behavior is not defined when using the identifier modifier, nor is the behavior defined when targeting references without explicit reference values (e.g., canonical references, etc.). Server SHALL reject any implementers have discretion on behavior for searches in these cases.

identifier is only allowed on reference type search request parameters and target elements that are the Reference FHIR type. When using the 'identifier' modifier, all typically-valid search parameter token inputs are allowed.

For example, the search: Show as unencoded: 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 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 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 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 search input value may be literal (to an address where the value set can be found) or logical (values of ValueSet.url ). If the server can treat the value 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 input as a 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 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 unencoded: 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 unencoded: HTTP GET | HTTP POST GET [base]/Condition?code:in=http://snomed.info/sct?fhir_vs=isa/235862008 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:in=http://snomed.info/sct?fhir_vs=isa/235862008 would match any conditions that contain any code from SNOMED CT that contains is suffixed by a 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 included resources as well, rather than only the matching resources. Note that this modifier is not defined for any search parameter types and 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 unencoded: 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 found by following the chained search reference Observation.patient , which are Patient resources linked via Observation.subject . Additionally, the server does would iterate through the included patient records and follow the Patient.link FHIR references, including linked Patient or RelatedPerson resources.

More information can be found in the section Including other resources

3.2.1.5.5.8.1 Performance Warning

Note that the iterate modifier causes implementations to perform a sub-query for each iterate directive for each resource it is based on. Using iterate directives can often reduce the total processing time of a set of queries (by reducing the number of round-trips) but can significantly increase the processing time of a single query.As noted in Including Referenced Resources , servers have discretion about limiting the depth of recursion, which iterations to support, and how many resources to include. When results are truncated, it is recommended for servers to inform clients via search outcome.

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 support 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 unencoded: 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 , even if a patient contains a Patient.name that parameter. has a given 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 unencoded: 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 is only allowed on search parameters of type token . When using the 'not' modifier, all typically-valid search parameter token inputs 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 unencoded: 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'
• unknown - Administrative Gender that is not 'male'
• records without a Patient.gender value (even if a record has extensions, such as a Data Absent Reason)

Similarly, the server supports search: Show as unencoded: 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 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 of multiple possible matches, the negation applies to the set and not each individual entry.

Note that the name not 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 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 param, but terms is not recommended. Implementers are instead recommended to use either the :exact _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 name, not-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 not in the specified value set. The search input value may be literal (to an address where the value set can be found) or logical (values of ValueSet.url ). If the server can treat the value as a literal URL, it should reject 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 input as a 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 unencoded: 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 unencoded: HTTP GET | HTTP POST GET [base]/Condition?code:not-in=http://snomed.info/sct?fhir_vs=isa/235862008 POST [base]/Condition/_search Content-Type: application/x-www-form-urlencoded code:not-in=http://snomed.info/sct?fhir_vs=isa/235862008 would match any conditions that do not contain any code from SNOMED CT that is a 235862008 , e.g., all codes excluding :

• 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.12 of-type

The of-type modifier allows clients to filter for resource Identifier , based on the Identifier.type.coding.system , Identifier.type.coding.code and Identifier.value . This allows searches for specific values only within a specific identifier code system. The format when using 'of-type' is [system]|[code]|[value] (see Encoding Note ), where [system] and [code] refer to the code and system in Identifier.type.coding ; the system and code portion is considered a match if the the system|code token would match a given Identifier.type.coding . The [value] test is a string match against Identifier.value . All three parts must be present.

of-type is only allowed on 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 that input values need to escaped in order to be processed correctly and values including reserved characters such as a vertical pipe ( | ) can cause parsing issues.

For example, the search: Show as unencoded: 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 a Temporary Medical Record Number.

3.2.1.5.5.13 text with reference or token type search parameters

The text modifier on search parameters of type reference and token allows clients to indicate that a supplied string is to be used to perform a string search against a textual value 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 unencoded: 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 name:exact=Bill 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' 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 the text 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.

For example, assuming a search parameter section-text that applies to Composition.section.text , the search: Show as unencoded: 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 the bones or liver of subjects will search for those literal values, but may also search for terms such as 'cancerous growth', 'tumor', etc..

3.2.1.5.5.15 text-advanced

The 400 text-advanced error 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 the text-advanced modifier SHOULD support 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 using the 'text-advanced' modifier, all typically-valid search parameter string inputs are allowed.

For example, the search: Show as unencoded: HTTP GET | 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 - Hypnic headache
• etc.

Additionally, a server may return Condition resources with codes containing synonymous text such as conditions 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]

The [type] modifier allows clients to restrict the resource type when following a resource 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 servers can impose restrictions on the use of the modifier (e.g., only allowing on local references, only allowing if Reference.type is populated, etc.) and allow for extended behavior (e.g., allowing on canonical references, etc.). Note that since external references are always absolute references, there can be no ambiguity about the resource type when resolving.

When resolving references, it is possible that a resolved resource does not match the specified type. In this case, the reference is considered to not match the search parameter. If a reference resolves to a type different than indicated or expected, a server SHOULD consider if it is appropriate to include the issue via an OperationOutcome in the response. § ⁴¹

[type] is only allowed on reference type search parameters that target elements with a clear error message . the Reference FHIR type. 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 unencoded: 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 unencoded: 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 unencoded: 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.

3.1.1.4.5 3.2.1.5.6 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: 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)

Following is a table showing some example ranges and how they interact with the prefixes, with [P] representing the parameter range and [R] representing the resource range, with each additional column showing whether the test result is a match or not. Empty columns indicate no match, while a match for a particular test will show the prefix code used for that test. Note that for 'approximately', the actuality of a match depends on both the actual spans of ranges and the server's definition of 'approximately'. Any test that could possibly match is indicated with ap .

             |--[P]--|
|--[R]--|

        |--[P]--|
|--[R]--|

    |--[P]--|
|--[R]--|

    |--[P]--|
|--[R]------|

  |--[P]--|
|----[R]----|

 |----[P]----|
[R]

|----[P]----|
|--[R]--|

|--[P]--|
|--[R]--|

|--[P]--|
|--[R]----|

|----[P]----|
|--[R]--|

|---[P]---|
|--[R]--|

|--[P]--|
|--[R]--|

|----[P]----|
[R]

|--[P]--|
|--[R]--|

|--[P]--|
|--[R]--|

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

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

3.1.1.4.6 3.2.1.5.7 number Escaping Search Parameters

Searching on In the rules described above, special rules are defined for the characters $ ,,, and | . As a simple numerical value 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 resource. Examples: composite parameter, while [parameter]=100 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: Show as unencoded: HTTP GET | HTTP POST GET [base]/Observation?code=a,b POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=a,b is a request for any Observation that has a code of either a or b , whereas: Show as unencoded: HTTP GET | HTTP POST Values GET [base]/Observation?code=a\,b POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code=a\,b is a request for any Observation that equal 100, has a code of a,b .

This escaping is at a different level to 3 significant figures precision, so range [99.5 ... 100.5) the percent encoding that applies to all URL parameters (as defined in RFC 3986 ). Standard percent escaping still applies, such that these URL strings have the same meaning:

• http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124,ValueSet/125
• [parameter]=100.00 http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,ValueSet/125
• Values that equal 100, to 5 significant figures precision, so range [99.995 ... 100.005). Whole numbers also equal 100.00, but not 100.01 http%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F123%2Chttp%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F124%2CValueSet%2F125

Note that all of the above representations would be transmitted via an HTTP request in the same form as: Show as unencoded: HTTP GET | HTTP POST GET [base]/ValueSet?url=http%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F123%2Chttp%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F124%2CValueSet%2F125 POST [base]/ValueSet/_search Content-Type: application/x-www-form-urlencoded url=http%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F123%2Chttp%3A%2F%2Facme.org%2Ffhir%2FValueSet%2F124%2CValueSet%2F125

Note that an escaped delimiter (e.g., an escaped comma) can appear within a multi-value delimited request, for example: Show as unencoded: HTTP GET | HTTP POST 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 is a request for ValueSets with a url literal of [parameter]=lt100 http://acme.org/fhir/ValueSet/123 or http://acme.org/fhir/ValueSet/124,ValueSet/125 .

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

Values 3.2.1.5.8 Search Types and FHIR Types

The following table shows the mapping between search types and FHIR types that they can be tested against.

Note that in addition to elements of the specified type, any search type is allowed to be tested against elements that contain other elements, such as Backbone Elements and complex datatypes , that contain at least one element of a valid FHIR type.

Generally, search testing against complex elements are performed by "or-joining" each valid sub-element of an appropriate FHIR type (see Combining for details). However, some types may include additional guidance or specific behavior - for example, when performing string searches against HumanName and Address elements (see string ). For clarity, the table below generally excludes FHIR types that are less than 100 just containers for other elements.

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

Technically, this is The date search type can be used to represent data from any of the date , dateTime , and instant data types; e.g. datatypes. Any degree of precision can be provided, but it SHALL be populated from the left (e.g. (e.g., can't specify a month without a year), except that the minutes SHALL be present if an hour is present, and you SHOULD provide a time zone timezone 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. Date parameters may can be used with the following data types:

Implicitly, The 'period' of a date search is from the earliest instant of the value through to the latest instant of the value. When comparing, the period start is adjusted to have maximum precision with the lowest possible value of all non-specified levels. For example, first month of the year, first day of the month, 0-filled time. The period end is adjusted to have maximum precision with the highest possible value of all non-specified levels - last month of the year, last day of the month (allowing for leap years), last time of the day (i.e. 23:59:59.99999).

For more information about how the different search prefixes work when comparing periods/ranges, refer to the Prefixes section.

A missing lower boundary is "less than" any actual date. A missing upper boundary is "greater than" any actual date. The Date searches can be controlled through the use of prefixes as described in the prefixes: following table:

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 exact value here range is at higher than the discretion test range. Similarly, a test such as 'starts after' is non-inclusive of the system 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 Matches against it dates 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. 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. e.g., 2000-04 is equivalent to an interval of [2000-04-01T00:00, 2000-04-30T23:59].
  • Dates with the year, month, and day are equivalent to an interval that starts at the first instant of day and ends on the last instant of the day, e.g. 2000-04-04 is equivalent to an interval of [2000-04-04T00:00, 2000-04-04T23:59.9999].
• Where possible, the system should SHOULD correct for timezones when performing queries. § ⁴⁵ Dates do not have time zones, timezones, and time zones should not timezones SHOULD NOT be considered. § ⁴⁶ Where both search parameters and resource element date times date-times do not have time zones, timezones, the servers local time zone should timezone SHOULD be assumed. § ⁴⁷

To search for all the procedures in a patient compartment that occurred over a 2 year 2-year period: Show as unencoded: 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

Managing timezones 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. Implementation guides may make additional rules in this regard.

Future versions of this specification may impose rules around the use of timezones 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.10 number

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

Notes about searching on Numbers:

• When a number search is used against a resource element that stores a simple integer (e.g. ImmunizationRecommendation.recommendation.doseNumber ), and the search parameter is not expressed using the exponential forms, and does not include any non-zero digits after a decimal point, the significance issues cancel out and searching is based on exact matches. Note that if there are non-zero digits after a decimal point, there cannot be any matches
• When a comparison prefix in the set gt, 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 operate in resources is not the same as whether two numbers are equal to each other in a mathematical sense
• Searching on decimals without using one of the comparisons listed in the earlier bullet 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 number of significant digits - three

Here are some example searches:

3.2.1.5.11 quantity

A quantity parameter searches on the Quantity datatype. The syntax for the value follows the form (see Encoding Note ):

• [parameter]={[prefix]}[number] matches a quantity by value , with an optional prefix
• [parameter]={[prefix]}[number]|[system]|[code] matches a quantity by value , system and code , with an optional prefix
• [parameter]={[prefix]}[number]||[code] matches a quantity by value and code or unit , with an optional prefix

The prefix is optional, and is as described in the section on Prefixes , both regarding how precision and comparator/range operators are interpreted. Like a number parameter, the number part of the search value can be a decimal in exponential format. The system and code follow the same pattern as token parameters are also optional. Note that when the [system] component has a value, it is implied that a precise (and potentially canonical) match is desired. In this case, it is inappropriate to search on the human display for the unit, which can be is uncontrolled and may unpredictable. Example searches:

Specifying a system and a code for the search implies that the search is based on a particular code system - usually UCUM , and that a precise (and potentially canonical) match is desired. In this case, it is inappropriate to search on the human display for the unit, which can be is uncontrolled and may be unpredictable.

The search processor may choose to perform a search based on canonical units (e.g., any value where the units can be converted to a value in mg in the case above). For example, an observation may have a value of 23 mm/hr . This is equal to 0.023 m/hr . The search processor can choose to normalize all the values to a canonical unit such as 6.4e-6 m/sec , and convert search terms to the same units (m/sec). Such conversions can be performed based on the semantics defined in UCUM . Servers that do not search based on canonical units will not be able to search against ranges whose low and high quantities use different units or where the search expression uses different units than are found in low and high.

3.2.1.5.12 reference

The reference search parameter type is used to search references between resources . For example, find all Conditions where the subject is a particular patient, where the patient is selected by name or identifier. The interpretation of a reference parameter is either (see Encoding Note ):

• [parameter]=[id] the logical [id] of a resource using a local reference (i.e., a relative reference).
• [parameter]=[type]/[id] the logical [id] of a resource of a specified type using a local reference (i.e., a relative reference), for when the reference can point to different types of resources (e.g., Observation.subject ).
• [parameter]=[type]/[id]/_history/[version] the logical [id] of a resource of a specified type using a local reference (i.e., a relative reference), for when the reference can point to different types of resources and a specific version is requested. Note that server implementations may return an error when using this syntax if resource versions are not supported. For more information, see References and Versions .
• [parameter]=[url] where the [url] is an absolute URL - a reference to a resource by its absolute location, or by its canonical URL
• [parameter]=[url]|[version] where the search element is a canonical reference, the [url] is an absolute URL, and a specific version or partial version is desired. For more information, see References and Versions .

Notes:

• A relative reference resolving to the same value as a specified absolute URL, or vice versa, qualifies as a match.
• If a reference value is a non-versioned relative reference (e.g., does not contain [url] or _history/[version] parts), the search SHOULD match instances that match the reference in it contains a versioned reference. § ⁴⁸

For example, if the base URL of a server is http://example.org/fhir, the search: Show as unencoded: HTTP GET | HTTP POST GET http://example.org/fhir/Observation?subject=Patient/123 POST http://example.org/fhir/Observation/_search Content-Type: application/x-www-form-urlencoded subject=Patient/123 will match Observations with subject.reference values:

• Patient/123 - exact match of search input
• http://example.org/fhir/Patient/123 - search input with implicit resolution to the local server
• Patient/123/_history/1 - reference to a specific version of the search input

Similarly, the search: Show as unencoded: HTTP GET | HTTP POST GET http://example.org/fhir/Observation?subject=http://example.org/fhir/Patient/123 POST http://example.org/fhir/Observation/_search Content-Type: application/x-www-form-urlencoded subject=http://example.org/fhir/Patient/123 will match Observations with subject.reference values:

• http://example.org/fhir/Patient/123 - exact match of search input
• Patient/123 - search input with implicit reference to the local server

Also, the search: Show as unencoded: HTTP GET | HTTP POST GET http://example.org/fhir/Observation?subject=123 POST http://example.org/fhir/Observation/_search Content-Type: application/x-www-form-urlencoded subject=123 will match Observations with subject.reference values:

• Patient/123 - search input of type Patient
• http://example.org/fhir/Patient/123 - search input with implicit resolution to the local server, of type Patient
• Practitioner/123 - search input of type Practitioner
• http://example.org/fhir/Practitioner/123 - search input with implicit resolution to the local server, of type Practitioner
• etc.

Some resource references may point to more than one type of resource; e.g., subject: Reference(Patient|Group|Device|..) . In these cases, multiple resources may have the same logical identifier. Servers SHOULD fail a search where the logical id in a reference 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: Show as unencoded: HTTP GET | HTTP POST GET [base]/Observation?subject=Patient/23 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject=Patient/23

This searches for any observations where the subject refers to the patient resource with the logical identifier "23". A modifier is also defined to allow the client to be explicit about the intended type: Show as unencoded: HTTP GET | HTTP POST GET [base]/Observation?subject:Patient=23 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject:Patient=23

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

In some cases, search parameters are defined with an implicitly limited scope. For example, Observation has an element subject , which is a reference to one of a number of types. This has a matching search parameter subject , which refers to any of the possible types. In addition to this, there is another search parameter patient , which also refers to Observation.subject , but is limited to only include references of type Patient . When using the patient search parameter, there is no need to specify ":Patient" as a modifier, or "Patient/" in the search value, as this must always be true.

FHIR References are also allowed to have an identifier . The modifier :identifier allows for searching by the identifier rather than the literal reference: Show as unencoded: HTTP GET | HTTP POST GET [base]/Observation?subject:identifier=http://acme.org/fhir/identifier/mrn|123456 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded subject:identifier=http://acme.org/fhir/identifier/mrn|123456

This is a search for all observations that reference a patient by a particular patient MRN. When the :identifier modifier is used, the search value works as a token search . The :identifier modifier is not supported on canonical elements since they do not have an identifier separate from the reference itself.

Chaining is not supported when using the :identifier modifier, nor are chaining, includes or reverse includes supported for reference search parameters that target elements without a reference element. For example, a search parameter that targets an element with the Reference FHIR type can be chained through, but a search parameter that targets a canonical element cannot.

The reference search parameter type is mostly used for resource elements of type Reference or canonical . However, it is also be used to search resource elements of type Resource - i.e., where one resource is directly nested within another - see the Bundle search parameters 'message' and 'composition' as an example of this.

3.1.1.4.8 3.2.1.5.13 string

For a simple string search, a string parameter serves as the input for a case- and accent-insensitive 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 accent. 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 SHOULD be considered 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. § ⁵²

For example, if a search parameter is of type string and the expression points to Patient.name , the implementation can test against any one or more elements of the HumanName datatype (e.g., given , family , prefix , suffix , etc.). 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 SHOULD search the parts of a family name independently. E.g. Searching § ⁵³ e.g., searching either Carreno "Carreno" or Quinones "Quinones" should match a family name of "Carreno Quinones". HL7 affiliates may MAY make more specific recommendations about how search should work expectations regarding names 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 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.10 3.2.1.5.14 token

A token type is a parameter that provides an 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 data type datatype 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. used (only the [code] portion).

For tokens, matches are literal (e.g. (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 tokens are to be interpreted case-insensitively (see, e.g. e.g., CodeSystem.caseSensitive ). Note that matches on _id are always case sensitive. If the underlying data type datatype is string then the search is not case sensitive.

Note : There are many challenging issues around case senstivity sensitivity and token searches. Some code systems are case sensitive (e.g. (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 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: following (see Encoding Note ):

• [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. (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 NOT be used - only the [parameter]=[code] form is allowed § ⁵⁷

Token search parameters are used for the following data types: datatypes:

Data Type Datatype	URI	Code	Comments
Coding	Coding.system	Coding.code
CodeableConcept	CodeableConcept.coding.system	CodeableConcept.coding.code	Matches against any coding in the CodeableConcept
Identifier	Identifier.system	Identifier.value	Clients can search by type not system using the :of-type modifier, see below below. To search on a CDA II.root - which may appear in either Identifier.system or Identifier.value , use the syntax identifier=|[root],[root]
ContactPoint		ContactPoint.value	At the discretion of the server, token searches on ContactPoint may use special handling, such as ignoring punctuation, performing partial searches etc.
code	(implicit)	code	the system is defined in the value set (though it's not usually needed)
boolean		boolean	The implicit system for boolean values is http://hl7.org/fhir/special-values http://terminology.hl7.org/CodeSystem/special-values but this is never actually used
id		id
uri		uri
string	n/a	string	Token is sometimes used for string to indicate that exact case-insensitive full-string matching is the correct default search stategy strategy

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

Modifiers: Modifier Use :text The search parameter is processed as a string that searches text associated with the code/value - either CodeableConcept.text , Coding.display , or Identifier.type.text . :not Reverse the code matching described in the paragraph above: return all resources that do not have a matching item. Note that this includes resources that have no value for the parameter - e.g. ?gender:not=male includes all patients that do not have gender = male, including patients that do not have a gender at all :above The search parameter is a concept with the form [system]|[code] , and the search parameter tests whether the coding in a resource subsumes the specified search code. For example, the search concept has an is-a relationship with the coding in the resource, and this includes the coding itself. :below the search parameter is a concept with the form [system]|[code] , and the search parameter tests whether the coding in a resource is subsumed by the specified search code. For example, the coding in the resource has an is-a relationship with the search concept, and this includes the coding itself. :in The search parameter is a URI (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is in the specified value set . The reference may be literal (to an address where the value set can be found) 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. :not-in The search parameter is a URI (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is not in the specified value set. :of-type The search parameter has the format system|code|value, where the system and code refer to a Identifier.type.coding.system and .code , and match if any of the type codes match. All 3 parts must be present 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:

3.1.1.4.11 3.2.1.5.15 quantity uri

A quantity The uri search parameter searches on the Quantity type is used to search elements that contain a URI ( RFC 3986 data type. The syntax for ). By default, matches are precise, case and accent sensitive, and the value follows entire URI must match. The modifier :above or :below can be used to indicate that partial matching is used. For example (note that the form: search parameter ValueSet.url is of type uri ): Show as unencoded: HTTP GET | HTTP POST 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

• [parameter]=[prefix][number]|[system]|[code] matches The first line is a quantity 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 unit 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 prefix search type uri can be used with elements of type canonical , uri , and url . The search type reference can also be used for those same types and is optional, always used for the type Reference . The search type reference is generally preferred for elements of type canonical because it can handle versioned canonical values. Where more than one search type can apply to a search parameter, the decision of which to use is based on the desired search behavior.

3.2.1.5.16 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)
• section-text on Composition
• contains on Location
• near on Location

3.2.1.5.17 Composite Search Parameters

Composite search parameters allow joining multiple elements into distinct single values with a $ . This 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 and 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 described above unencoded: HTTP GET | HTTP POST GET [base]/Observation?code-value-quantity=loinc|12907-2$ge150|http://unitsofmeasure.org|mmol/L POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded code-value-quantity=loinc|12907-2$ge150|http://unitsofmeasure.org|mmol/L will match Observation records with a LOINC code 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 value and itself can be composed into a set of values. For example, searching Group.characteristic , both regarding how precision searching for multiple key/value pairs (instead of an intersection of matches on key and comparator/range operators value): Show as unencoded: HTTP GET | HTTP POST GET [base]/Group?characteristic-value=gender$mixed,owner$john-smith POST [base]/Group/_search Content-Type: application/x-www-form-urlencoded characteristic-value=gender$mixed,owner$john-smith will match Groups that have a gender characteristic of "mixed" (the group contains people of multiple genders) OR the group has a owner characteristic of "john-smith".

Note that search modifiers are interpreted. Example searches: NOT allowed on composite parameters.

Composite search parameters SHALL NOT declare components that reference other composite search parameters. § ⁵⁸ All components of a composite search parameter must be non-composite (i.e., of one of the other basic or extended types). If a desired design would logically include the behavior of an existing composite search parameter, that nesting can be flattened by listing the underlying "leaf" component search parameters directly in the new composite.

For example, instead of defining a composite parameter code-value-quantity-and-device whose components are the existing code-value-quantity composite plus a device component (which would constitute nesting), define a new composite parameter with components code , value-quantity , and device (each pointing to the appropriate non-composite search parameters).

Examples of using composite parameters:

3.2.1.5.18 Resource Parameters

Specifying A resource type parameter is a system and special case parameter type that is used to enable chaining through elements that are actual resources (e.g., Bundle.entry.resource ).

Note that the resource search parameter type does not define a code test behavior for the search implies that parameter itself. For example, when using the Bundle-composition search parameter, the behavior of a test such as Bundle?composition=Composition/123 is based on undefined . Since search parameters of resource type are only defined to chain a particular code system - usually UCUM search through to a resource, thus the correct search would be shaped like Bundle?composition._id=123 .

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

,

Implementation Note:

In FHIR R5 and that a precise (and potentially canonical) match is desired. earlier versions, the resource search type did not exist and some search parameters of type reference were defined expecting to chain through embedded resources.

3.2.1.6 Special Search Conditions

In this case, it is inappropriate addition to search on the human display 'basic' searching, this specification defines behaviors for many 'special' cases that are common across implementations.

3.2.1.6.1 Searching ranges

Explicit boundary searching on elements with the unit, which Range datatype can be is uncontrolled and may unpredictable. performed using composite search parameters . Composite search parameters allow a single search to test against multiple aspects of the same range.

The When a composite search processor may choose parameter references the same underlying search parameter that targets an element with a Range type multiple times, the search performs object-level joining rather than set-level joining. This means that the criteria apply to perform the same Range instance, not independently across multiple Range values in a repeating element.

For example, if we define a search based on canonical units parameter for Observation.valueRange named value-range and a composite search parameter named value-range-values that includes two components both referencing value-range , then a search such as: Show as unencoded: HTTP GET (e.g. any | HTTP POST GET [base]/Observation?value-range-values=ge20$le30 POST [base]/Observation/_search Content-Type: application/x-www-form-urlencoded value-range-values=le20$ge30 will match Observation records with a value where the units can be converted range that has a low boundary greater than or equal to 20 AND a high boundary less than or equal to 30 on the same Range instance .

Note that this search will NOT match an Observation with two value in mg in ranges, one with a low of 25 and another with a high of 28, because the case above). low and high values do not belong to the same Range instance.

3.1.1.4.12 3.2.1.6.2 reference Searching Identifiers

A reference parameter refers In FHIR data, there are a few types of identifiers that may apply to references between resources . For example, find all Conditions where the subject reference is a particular patient, where resource: a single logical identifier (the Resource.id of a resource), zero or more Identifier-type elements (e.g., Patient.Identifier ), and, if the patient resource is selected by name or identifier. The interpretation a Canonical Resource , a canonical url . Each of these 'identifiers' have a reference parameter is either: different datatype and expose different search functionality. Some details about each are included below.

[parameter]=[id] 3.2.1.6.2.1 Logical Identifiers the logical [id]

The Logical Identifier of a resource using represents a local reference (i.e. unique key for an instance within a relative reference) 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 the [parameter]=[type]/[id] _id search parameter.

Given that a logical id is unique in the context, searching by logical [id] id will always result in either zero or one records. In many ways, the search is functionally equivalent to an equivalent simple read operation . However, there are some differences in using search instead of read:

• Search operations always return bundles.
  • If the logical id exists and the resource 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 specified type using a local reference (i.e. valid search will still be a relative reference), for when bundle. The bundle may include further information in the reference can point to different types form of resources (e.g. Observation.subject an OperationOutcome . See Handling Errors ) for more information.
• [parameter]=[url] where Related resources can be requested and/or returned in the [url] is an absolute URL same request - see Including Other Resources for more information.
• Additional search functionality is available. For example, asking for a reference to a Patient resource by its absolute location logical id, but also setting the search criteria of deceased to true would only return the Patient if they are deceased.

Note: A relative reference resolving to the same value as Since _id requires a specified absolute URL, resource type context and there can only be zero or vice versa, qualifies as one resources of a match. For example, if type with a given logical id, the search parameter value is Patient/123, then this will find references like this: <patient> <reference value="Patient/123"/> </patient> If the server base address is http://example.org/fhir, then functionally equivalent to the full URL for that reference is http://example.org/fhir/Patient/123, which simple read operation of GET [base]/Patient/23 . However, searching by logical identifier means that the all other search term also matches patient references like this: <patient> <reference value="http://example.org/fhir/Patient/123"/> </patient> In addition, searching for functionality is available - e.g., reference=http://example.org/fhir/Patient/123 OperationOutcome will also match both references. resources for issues, additional search parameters, inclusion of related resources, etc..

3.2.1.6.2.2 Searching by Membership

Some references resources (e.g., Group , List , and CareTeam ) are allowed to point used to more than one type maintain collections of resource; e.g. subject : Reference(Patient|Group|Device|..). In these cases, multiple resources may have the same logical identifier. Servers SHOULD reject other resources. For example, a search where the logical id refers to more than one matching resource across different types. In order Group of Patients representing a cohort or a List of patient allergies. While it is possible to allow retrieve the client to perform a search in these situations collection resource, iterate over the type is entries, and fetch each resource listed therein, using search criterion allows for fewer round-trips and additional search criteria to be specified explicitly: in-line.

This searches for any observations where the subject refers to the patient resource with the logical identifier "23". A modifier is also There are two standard search parameters defined by this specification to support searching against collection resources:

• _in to allow the client test against active membership, and
• _list to be explicit about the intended type: test against advanced List functionality (e.g., functional list definitions ).