0.0.1-pre - ci-build International flag

SQL on FHIR, published by HL7. This is not an authorized publication; it is the continuous build for version 0.0.1-pre. This version is based on the current content of https://github.com/FHIR/sql-on-fhir-v2/ and changes regularly. See the Directory of published versions


Official URL: http://hl7.org/fhir/uv/sql-on-fhir/ImplementationGuide/hl7.fhir.uv.sql-on-fhir Version: 0.0.1-pre
Draft as of 2023-11-10 Computable Name: SQLonFHIR

This is an evolution of the original “SQL on FHIR” draft, which can still be found here.


The FHIR® standard is a great fit for RESTful and JSON-based systems, helping make healthcare data liquidity real. This spec aims to take FHIR usage a step futher, making FHIR work well with familiar and efficient SQL engines and surrounding ecosystems.

We do this by creating simple, tabular views of the underlying FHIR data that are tailored to specific needs. Views are defined with FHIRPath expressions in a logical structure to specify things like column names and unnested items.

Let’s start with a simple example, defining a “patient_demographics” view with the following ViewDefinition structure:

  "name": "patient_demographics",
  "resource": "Patient",
  "select": [
      "column": [
          "path": "getResourceKey()",
          "name": "id"
          "path": "gender",
          "name": "gender"
      // Create columns from the official name selected here.
      "forEach": "name.where(use = 'official').first()",
      "column": [
          "path": "given.join(' ')",
          "name": "given_name",
          "description": "A single given name field with all names joined together."
          "path": "family",
          "name": "family_name"

This will result in a “patient_demographics” table that looks like this. The table can be persisted and queried in your database of choice, using the view name as the table name:

id gender given_name family_name
1 female Malvina Gerda Vicario
2 male Yolotzin Adel Bristow
3 other Jin Gomer Aarens

Such tabular views can be created for any FHIR resource, with more examples here. See the View Definition page for details, and the System Layers page for how views fit into a larger analytic ecosystem.


Contributors and early users are welcome! Here are some places to start:

How to read this guide


FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of the contents of this repository by HL7, nor affirmation that this data is conformant to the various applicable standards


  • Nikolai Ryzhikov @niquola (Health Samurai)
  • Dan Gottlieb @gotdan (Central Square Solutions)
  • Vadim Peretokin @vadi2 (Philips)
  • Marat Surmashev @aitem (Health Samurai)
  • Ryan Brush @rbrush (Google)
  • Brian Kaney @bkaney (Vermonster)
  • Josh Mandel @jmandel (Microsoft)
  • John Grimes @johngrimes (CSIRO)
  • FHIR Community - https://chat.fhir.org/

Work is sponsored and supported by: