Implement FHIR REST server with Couchbase

This is a follow up to my previous post that covered the topic of FHIR Data Model with Couchbase N1QL. In this blog, I will discuss the topic of how to implement the FHIR Search REST API Server over the Couchbase services, including actual examples of how the different FHIR search patterns work with Couchbase using the synthetic FHIR data provided by Synthea.

Please refer to my previous blog for background information on FHIR Data Model with Couchbase N1QL. 

Why is this of interest to you

1. Your organization is planning to develop an FHIR compliant Electronic Health Record system (EHR), and you are looking into taking advantage of the many benefits of NoSQL databases, such as Distributed, High Availability, XDCR, and Multi-Dimensional Scalability.
2. You are an architect, or developer and like understand how Couchbase JSON database can greatly reduce the complexity of your applications, by relegating the complex FHIR Search  [https://www.hl7.org/fhir/searchparameter-registry.html] processing to the database server layer.
3. You are a data analyst and like to understand how you can leverage your SQL knowledge to query FHIR data directly with Couchbase N1QL and Full-Text-Search.
4. You are interested in finding out how Couchbase N1QL, a SQL for JSON, can provide an efficient way to query a JSON data modelt hat is both hierarchical and relational in nature, as defined by HL7 Administrative Module.

FHIR Application with Couchbase

The diagram above shows the processes involved in a typical FHIR application. The FHIR Rest server is central to this application, and needs to support the search specifications  as specified by FHIR https://www.hl7.org/fhir/search.html. The REST server manages all the interactions between the client applications and translates the FHIR search requests into N1QL statements, and submits the requests to the Couchbase Query Service.

How to set up the FHIR Server with Couchbase

You can set up the Couchbase FHIR API server, and the Couchbase NoSQL database on a single server, or even your laptop. The setup process requires:

1. Installing Couchbase Server 6.5.
2. Load the Synthea Data into the Couchbase Server.
3. Deploy the dotnet FHIR Server code.

Please follow the instructions https://github.com/AV25242/dotnet-fhir-server-couchbase.git

FHIR Sample Data Set

Before you start using FHIR search to query, let’s familiarize ourselves with the FHIR sample data set.

1. The Synthea data set consists of 1K synthetic patient records. 
2. The patient record is in a FHIR resource bundle format, meaning a patient record includes all of the patient’s related FHIR objects.

For the purpose of this demonstration, the patient resource bundle have been normalized into individual resource type documents, to allow us to query the FHIR object directly or indirectly via the reference id of the object.

The FHIR model is shown with relationships to convey that

FHIR searches

You can test out the REST API server using any REST clients of your choice. For simplicity, I use CURL on my terminal.

1. Search any FHIR resource

2. Search resource by id

All FHIR resources have an id identifier, and can be searched directly.

3. Search resource by any top level field

Search all insurance Claims that were provided by “BAYSIDE MEDICAL CENTER”

4. Search resource by name  –  N1QL ARRAY Search

The FHIR resource has a comprehensive structure to capture the resource name.

The FHIR search on name has to take into account all the different names the patient may use.

5. Search Patients by Medical Identifier – N1QL ARRAY Search

FHIR also supports identifiers for the resource. In the example below, a patient can be identified with his/her SSN and OID (for non-FHIR systems). 

Search Patient by the SSN identifier

6. Search resource by medical system/code – N1QL ARRAY Search

FHIR uses the medical code to identify Procedure, Observation, or DiagnosticReport.

Search DiagnosticReport by its system & code

7. Search resource by Phone / Email – N1QL ARRAY Search

FHIR record encapsulates all the communication channels to the resource in the “telecom” field.

The FHIR search on telecom  has to take into account all the different telecom types the resource may use.

Search Patients by phone

Search Practitioners by email

Search Hospitals by phone

8. Search resource using Date Range – N1QL Range Scan

FHIR objects may include a datetime range to indicate the period in which an event occurred.

Search Procedures that took place between two dates

9. Search resource with _text search – Couchbase FTS

FHIR search specification also includes a text search capability. A search request using the ‘_text’ field will instruct the server to perform a text search on all the text field.

Search Conditions with the term ‘Fracture’ in text description.

Search Observations with the term ‘Cholesterol’’ in text description.

10. Search Patients by their related objects – N1QL JOIN

The FHIR data model is relational in nature. The objects that are associated with a Patient contain the Patient’s id in the subject field.  A patient has multiple CarePlans, and the plan has a subject field with the patient’s id to denote that the care plan belongs to the patient.

Using the subject.reference field, the FHIR REST server can implement a database JOIN between the Patient and the related objects, to allow a search for the patient record who owns a specific plan with a plan id value

Search all Patients who had a particular Observation code

Search all Patients who have had a s particular medical Condition

Why Couchbase is a better platform to build your FHIR Server

A quick Google on FHIR Server returns 300K results, and the HL7 FHIR implementation page lists over dozen open source projects. Ready built FHIR server implementations are also available from many vendors. These implementations rely on different database technologies from traditional RDBMS, as well as many of the current NoSQL databases in the market today.

The dotnot-fhir-server-couchbase provides several examples on how you can build the FHIR search specifications using the Couchbase platform. The code translates the FHIR API search APIs and parameters into Couchbase N1QL statements, then submits them to the Couchbase Query service, where all the processing are processed. This approach can reduce the complexity in the REST server or the REST client application. A few key points to note:

1. The FHIR JSON data are stored as-is in the Couchbase Data Service. There are no pre/post processing required when you need to POST/GET the FHIR document to/from the server.
2. Couchbase N1QL query language has a rich set of operations that support the processing of the hierarchical data of the FHIR JSON format. Allowing seamless access to nested array of data, such as those used to describe patient’s conditions, observations,  treatments, and diagnostic reports.
3. FHIR requirements for Text Search can be met directly in Couchbase Full Text Search with N1QL Search() function, there is no need to map your searches to Lucene, ElasticSearch or Solr.
4. FHIR chained search specifications could require a FHIR server implementation to submit multiple searches to the database in order process the request. However with N1QL, an ANSI join query can result in a much simpler code to meet the requirement.

Summary

FHIR Rest Servers are being implemented in all types of platforms.  The search protocols are relatively simple, focusing on the support of retrieving Patient, and other FHIR related objects by their specific attributes. The search APIs insulate the REST client from complex hierarchical and array processing, which are fundamentals to JSON data format.  However, the specification, as it is currently stands:

1. Does not define a clear way to allow querying of patients (or other FHIR objects) by its related information, other than a simple parent and child capability. 
2. There is no support for aggregation, thus limiting any analysis capabilities.

Because of these limitations, the REST client applications can become more complex as it needs to embed the logic of traversing the FHIR data model.  The example REST Server API code in this blog article, seeks to illustrate three key points

1. The simplicity of implementing searching on array elements using Couchbase N1QL array construct.
2. The ability to push down to the Couchbase Query service, to perform the search on Patient objects using related objects. In effect, leveraging N1QL ANSI JOIN supports.
3. The ability to seamlessly integrate Full Text Search capabilities with Couchbase N1QL, without the need to use dedicated FTS platforms such ElasticSearch or Solr, as suggested in the FHIR Search specification.

I would also like to thank Arun Vijayraghavan, our Principal Product Manager for all Couchbase SDKs, who developed the dotnet-fhir-server-couchbase code, and the feedback from customers who have helped reviewing our FHIR search implementation. Please let us know if you have any questions, feedback or running into any issue setting the environment.

Resources

1. Fast Healthcare Interoperability Resource: https://www.hl7.org/fhir/index.html
2. SyntheticMass: “Jason Walonoski, Mark Kramer, Joseph Nichols, Andre Quina, Chris Moesel, Dylan Hall, Carlton Duffett, Kudakwashe Dube, Thomas Gallagher, Scott McLachlan, Synthea: An approach, method, and software mechanism for generating synthetic patients and the synthetic electronic health care record, Journal of the American Medical Informatics Association, Volume 25, Issue 3, March 2018, Pages 230–238, https://doi.org/10.1093/jamia/ocx079“
3. N1QL Tutorial: https://query-tutorial.couchbase.com/tutorial/#1
4. FHIR Search Parameters: https://www.hl7.org/fhir/searchparameter-registry.html