FHIR Data Model With Couchbase N1QL

DZone 's Guide to

FHIR Data Model With Couchbase N1QL

In this article, learn more about the FHIR data model with Couchbase N1QL.

· Database Zone ·
Free Resource

Couchbase is a JSON database that has now become an alternative to the traditional RDBMS. It has achieved this, not only by providing the industry-leading Key Value store and the same query and ACID translation capabilities that organizations have come to expect, but also the flexibility of natively store its data in the JSON format. In addition, Couchbase also includes distributed storage, multi-dimensional scalability, high availability, and cross data center replication(XDCR). All this in a single Couchbase Data Platform that extends to the Edge with the Couchbase Mobile.

Couchbase is also committed to extend its capabilities well beyond that are needed in traditional RDBMS applications. With Couchbase Cloud, where everything is a fully managed and automated, providing a secure Database-as-a-Service (DBaaS) that simplifies database management by deploying, managing, and operating Couchbase Server across multi-cloud environments with just a few clicks. Couchbase Cloud is flexible, highly available, and provides a differentiated economical option for enterprises looking to reduce operational tasks while taking advantage of the most powerful NoSQL technology. 

We are also doing this by collaborating with many of our customers across different industries to understand their business needs and how Couchbase can help with those challenges. These industries extend from Retail & E-Commerce, Travel & Hospitality, Financial Services, Energy & Utilities, and also High Tech and Gaming.

We have done this by collaborating with many of our customers across different industries to understand their business needs and how Couchbase can help with those challenges. These industries extend from Retail & E-Commerce, Travel & Hospitality, Financial Services, Energy & Utilities, and also High Tech and Gaming.

In this blog, I'd like to focus on how the Couchbase database can be used in the Healthcare industry. Specifically, the focus will be on the Fast Healthcare Interoperability Resources (FHIR) specification as defined by HL7 FHIR. The reason for this blog is because of the level of interest from many of our customers who are currently planning or implementing their FHIR compliant applications using the Couchbase database.

Why Is FHIR With Couchbase of Interest to You?

  1. Your organization is planning to develop FHIR applications, and/or looking into taking advantage of the many benefits of NoSQL database, 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 data model, as defined by FHIR, that is both JSON hierarchical and relational in nature.

FHIR Extensibility With Couchbase JSON

While the FHIR specification was designed to ensure interoperability across different implementations and healthcare functional areas, it also includes an extensibility option built into each resource [https://www.hl7.org/fhir/patient-profiles.html]. This allows specific implementations to include child elements to capture additional requirements that may not be part of the common specification [https://www.hl7.org/fhir/extensibility.html].

So how would this influence your decision when choosing a database for your FHIR implementation? Traditional RDBMS with strict schema will most certainly require additional logic to handle FHIR resources that contain extension fields.  Whereas databases that store its data in a schema-less JSON format are well positioned to handle this type of extensibility. 

Couchbase, being a native JSON database with an expressive SQL like query capability, allows FHIR applications to seamlessly integrate resources with or without these extension fields. Similar to SQL, N1QL query can ignore the extension, or include them without affecting the applications.

In fact, the ability to support schema evolution for application development is what makes Couchbase an ideal platform for FHIR applications. 

A Brief Description of FHIR

FHIR® – Fast Healthcare Interoperability Resources (hl7.org/fhir) – is a next generation standards framework created by HL7. FHIR combines the best features for HL7 and leverages the latest web standards and applying a tight focus on implementability. FHIR applications are based on the concept of “Resources”. These resources are assembled into specific healthcare applications, spanning from the administrative, clinical to patient care functions. FHIR is suitable for use in a wide variety of contexts – mobile phone apps, cloud communications, EHR-based data sharing, server communication for healthcare providers. One of the key objectives of FHIR is to specify a standard in which different healthcare applications can adopt, thus allowing interoperability between different functional applications and ultimately drive down the cost of implementations.

Please refer to the FHIR website for further information.

The FHIR Data Model

At the heart of FHIR is the common definition of the different resource types that encompasses all the different aspects of healthcare. From the administrative function of Patient, Practitioner, CareTeam, Device, Organization, Location, Healthcare Service, to the Clinical, Diagnostic, Medications, as well as the Financial functions such as Insurance Coverage.

For the purpose of this article, I am using the sample synthetic data set available from SyntheticMass that has been generated by SyntheaTM [https://synthetichealth.github.io/synthea], an open-source patient population simulation made available by The MITRE Corporation.

The data was made available as a resource bundle for each synthetic patient, which are then imported into an instance of Couchbase 6.5 database.



SELECT resourceType, COUNT(1) doc_count
 FROM fhir_admin
 GROUP BY resourceType
doc_count    resourceType
567    "AllergyIntolerance"
3577    "CarePlan"
3577    "CareTeam"
52387    "Claim"
8714    "Condition"
57    "Device"
17069    "DiagnosticReport"
42019    "Encounter"
42019    "ExplanationOfBenefit"
2942    "Goal"
965    "ImagingStudy"
14982    "Immunization"
926    "MedicationAdministration"
10368    "MedicationRequest"
235332    "Observation"
1033    "Organization"
1177    "Patient"
1034    "Practitioner"
32454    "Procedure"

A Few Notable Points About the FHIR Data Model

  1. The model centers around the 'patient' object
  2. The object type is represented by the 'resourceType' field
  3. The JSON structure supports a richer set of information that can be kept about the patient, such as contact details, addresses, communications, etc..
  4. Each object has a uniquely identifiable 'id' field.
  5. The objects are referencing  each other. Most are have references to the 'patient' object.

Why Couchbase Is Well Suited for FHIR

As mentioned above, Couchbase stores its data natively in JSON, which is a readable document format. Applications can either use the Key Value APIs, or leverage Couchbase Query Language to manipulate the documents. The advantage of storing the data in the JSON format, instead of as a column type as in many RDBMSs, is the ease with which users can access the information therein. JSON document elements, such as field, array object, and hierarchical object can be accessed directly from the parent object without requiring additional syntax. Here is an example of the Patient document as defined by the FHIR.

What it means for the FHIR application is that users with RDBMS experience who have a basic working knowledge of SQL can access the FHIR patient and the associated resources in the exact same way as with the traditional RDBMS. 

Couchbase N1QL to Search FHIR Data

Query patients by ID



FROM fhir_admin res
WHERE res.resourceType='Patient'
AND  res.id='e3ae7831-14c8-4d13-a8fb-dad68fa12bc9'

Query patients by age group


  1. The patient's age has to be calculated from taking the current date - DOB.
  2. The query uses the N1QL LET construct to define 'age' and bucket the age into 'agegroup'.
  3. A standard ANSI GROUP BY and COUNT returns the number of patients by age group.

In addition, the ability to JOIN and UNNEST documents with Couchbase N1QL allows users to query related information of the patient.

Query patients and their current unresolved conditions 


  1. A patient can have multiple names, which is represented in the 'name' array. This query uses the ARRAY operator to filter out only the official 'name' array element.
  2. The query joins the 'condition'  to the 'patient'  object using part the 'subject.reference' field of the 'condition' object to the 'patient.id'.
  3. Each 'patient' may have multiple conditions, hence the need to flatten (UNNEST) the 'condition->code' array.
  4. There could be multiple 'clinical.status' for the 'condition', but the query only needs to return the conditions that are not resolved

List of all patients who was at Beverley hospital on the week beginning of 2011-08-18



SELECT ARRAY v FOR v IN p.name WHEN v.`use`='official' END fullname ,
       p.telecom phonecontact,
FROM fhir_admin m
 INNER JOIN fhir_admin p ON split(m.subject.reference,':')[2] = p.id AND p.resourceType='Patient' 
WHERE m.resourceType='Encounter'
AND DATE_FORMAT_STR(m.period.`start`, '1111-11-11') BETWEEN '2011-08-18' AND '2011-08-25'
AND m.serviceProvider.display = 'BEVERLY HOSPITAL CORPORATION' 

  1. The query examines the 'encounter' object to find out all the 'patient' treatment at this specific hospital.
  2. ARRAY operator is used to get the 'patient' official name.

List of patients with their insurance claim detail - services and cost


  1. The 'claim' object is JOINED to the 'patient' object to access the patient's detail.
  2. The 'claim' object has nested array for 'claim->item'.
  3. The 'claim->item' is associated to a 'productOrService' with an array coding that contain the description of the treatment.
  4. The cost is at the claim level.

Rank the Procedure count by Hospital



 SELECT  c.patient.reference, cis.display,SUM( c.total.`value`)
FROM fhir_admin c
 INNER JOIN fhir_admin p ON split(c.patient.reference,':')[2] = p.id AND p.resourceType='Patient' 
 UNNEST c.item as ci
 UNNEST ci.productOrService.coding as cis
WHERE c.resourceType='Claim'
GROUP by cis.display,c.patient.reference 

Rank the Procedure count by Hospital



SELECT e.serviceProvider.display hospital,
       p.code.text treatment,
       RANK() OVER ( PARTITION BY e.serviceProvider.display ORDER BY COUNT(p.code.text) DESC ) serviceRank
FROM fhir_admin p
  INNER JOIN fhir_admin e USE HASH(PROBE) ON split(p.encounter.reference,':')[2] = e.id and e.resourceType='Encounter'
WHERE p.resourceType='Procedure'
GROUP by e.serviceProvider.display,p.code.text

  1. The 'procedure' object is JOINED to the 'encounter' object to access the hospital where the procedure was administered.
  2. The N1QL Window RANK function is used to assign a value by the count of the procedure.
  3. Hash Join hint is used to improve the performance for the document JOIN.


Couchbase is well suited for the FHIR application implementation because of the approach it uses to store the data in JSON format. Its powerful N1QL query language allows developers with SQL experience to navigate the FHIR data model to perform all the CRUD operations that users would expect to see in a database. With its ability to perform document JOIN to advanced processing of embedded array objects, the N1QL query language will move all the processing needs to the Couchbase Query and Indexing Service, thus reducing the burden of the FHIR applications to having to perform all the object associations.

As with any new applications, there will always be a need to perform direct examinations of the underlying data, either by the application administrators or the data analysts who may have the need to perform search beyond what are supported by the FHIR search capability with FHIR REST API server.

In the next blog, I will examine what it takes to set up a FHIR REST API server that can communicate with the Couchbase server to provide the basic FHIR search requirements as specified in https://www.hl7.org/fhir/search.html


  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
  5. FHIR Extensibility: https://www.hl7.org/fhir/extensibility.html
couchbase, data modeling, database, fhir, json, n1ql, nosql, tutorial

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}