Search for a Document

Scope

This capability supports the ability to find documents using parameterized queries.

This capability supports the following query behavior: 

• Searches that are intended to return a payload that includes any FHIR Documents that match the parameters provided. These types of queries combine search and retrieval but put more strain on the requesting system to manage and filter the volume of content in the response in a way that is more manageable to the user.

Note: Details on what the responder supports can be found within the CapabilityStatement that the requester retrieves as a separate step from this search. Querying for a CapabilityStatement is an expected pre-requisite for being able to query a source. However, it is not required to be conducted at the beginning of every session to avoid forcing performance costs on clients that interact with known servers that do not update their security services and/or supported capabilities frequently.

Use Cases

The following CA:FeX use cases leverage this capability:

• UC-02 Query and Retrieve Document

CA:FeX Transactions

This capability describes the FHIR implementation of the CA:FeX Search Data (CA:FeX-2) transaction found in the Sequence Diagram for UC-02: Query and Retrieve Document.

HTTP Operations

This capability can be leveraged using HTTP GET requests and/or HTTP POST. Implementers are expected to familiarize themselves with how searches are executed using the FHIR RESTful API framework.

See CA:FeX Actors and Transactions for more information on the supported HTTP operations.

HTTP GET

In the simplest case, a search is executed by performing a GET operation in the RESTful framework:

GET [base]/[resourcetype]?name=value&...

HTTP POST

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

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

Considerations for Document Search Patterns

While there is more space for variability of document submission patterns based on a number of factors (that will be discussed in more detail in a future FHIR Document Exchange Companion Whitepaper), variations in supported document search patterns incur a higher cost towards Data Consumers.

A primary driver of this specification is to fill the gap that "FHIR-first" implementers are experiencing with existing document exchange standards like MHD and XDS. See pan-Canadian FHIR Exchange (CA:FeX) Interoperability Specifications: Preface. One of these particular challenges, is the need to balance efficacious and consistent search patterns against the additional effort incurred to supply supplementary metadata/resources (e.g., DocumentReference) that include more potent attributes to aid in targeted searches.

Clinical systems in US markets are more familiar with using MHD-like patterns to exchange C-CDAs using FHIR - largely due to the proliferation of XDS implementations in the US Market. Many organizations that had already invested in XDS infrastructure opted to support a FHIR façade for retrieving C-CDAs and utilized MHD (and related IHE profiles) as the mechanism for doing so. Naturally, these systems are considering how to retrofit their existing configurations to support search and retrieval of other types of documents in a similar manner.

Systems that serve non-US markets (or new solutions built entirely in FHIR for document exchange) may not have the same historical context to immediately catalyze investment of effort to supply additional resources for more desirable search behaviors. Recently, new operations have been developed that are more lightweight and may ease the burden of supporting these more potent search attributes. However, these patterns are evolving and their place in the Canadian market is yet to be fully evaluated.

Note: The pattern intended for the search against FHIR Document Repositories (CA:FeX 2A) has received significantly more rounds of feedback and projectathon testing than the pattern that was socialized for implementers of Hybrid Repositories (CA:FeX 2B). CA:FeX 2B and advanced capabilities that require further implementer feedback have been migrated to a future release of the CA:FeX.

Document Search Patterns: CA:FeX-2A (Search Against FHIR Assembled Documents Repository)

This pattern is intended to represent the most straightforward method of searching for FHIR Documents from a repository that does not have an existing XDS/MHD architecture and has not further augmented their search capabilities.

Implementers who are trialing this pattern will either play the role of a Data Consumer or a Data Responder in an interaction where a query is constructed (using the parameters identified below) and then submitted to a [base]/Bundle endpoint using a HTTP GET or POST command. 

This will execute a search which will return the results in the HTTP response as a searchset Bundle containing any document Bundle resources that match the criteria of the search. While the endpoint is anchored around Bundle, the expectation is that searches will use chaining on a handful of parameters under bundle.composition, to narrow the search to FHIR Documents.

Per the FHIR standard on HTTP search interaction:

• Because of the way that some user agents and proxies treat GET and POST requests, in addition to the get based search method, servers that support search SHALL also support a POST based search
• Supporting GET means that PHI (Personal health information) might appear in search parameters, and therefore in HTTP logs. For this reason logs should be regarded as being as sensitive as the resources themselves. This is a general requirement irrespective of the use of GET - see the FHIR security page for further commentary.
• If the search succeeds, the server SHALL return a 200 OK HTTP status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero or more resources in a defined order.
• If the search fails (cannot be executed, not that there are no matches), the return value SHALL be a status code 4xx or 5xx with an OperationOutcome. See Response Handling.

Implementers are encouraged to review the Base FHIR Specification for further details on the HTTP search interaction.

Considerations for Document Search Using Bundle Endpoints

Anchoring searches around Bundle in this search pattern is recommended for implementers that want to retrieve all the FHIR Documents that meet their search criteria.

• Implementers that use this approach should consider using a combination of search parameters to reduce the processing load on responders and requesters.
• The result collection can be long, so servers may use paging. If they do, they SHALL use the method described here for breaking the collection into pages if appropriate.

This search pattern does not separate the act of search from retrieval. Clients that want to provide their users the ability to review high level information (lists, summaries, etc.) for matching documents to support selective retrieval of the desired FHIR Document bundles will need to utilize different search patterns or manage this behavior in the client's user interface.

Supported Search Parameters for Document Search Using Bundle Endpoints

The following search parameters are used generically to support document retrieval anchored around the Bundle endpoint. These will continue to evolve as new use cases and requirements are identified.

Additional search parameters that are specific to the requirements for a particular use case or IGuide may be further defined by those implementations. See Option 2 - FHIR Health Information Exchange (HIE) Pattern Using CA:FeX in the pan-Canadian Patient Summary (PS-CA) Specification for details and examples of which of the parameters below are used to retrieve patient summaries.