SQL on FHIR
2.1.0-pre - release International flag

SQL on FHIR, published by SQL on FHIR Working Group. This guide is not an authorized publication; it is the continuous build for version 2.1.0-pre built by the FHIR (HL7® FHIR® Standard) CI Build. 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

OperationDefinition: SQLQuery Run

Official URL: http://sql-on-fhir.org/OperationDefinition/$sqlquery-run Version: 2.1.0-pre
Active as of 2026-02-24 Computable Name: SQLQueryRun

Execute a SQLQuery Library against ViewDefinition tables.

Execute a SQLQuery Library against ViewDefinition tables synchronously.

Use Cases:

  • Run ad-hoc analytics queries
  • Interactive query development and testing
  • Real-time data retrieval with parameters

Endpoints:

Level Endpoint Query Source
System POST [base]/$sqlquery-run queryReference or queryResource
Type POST [base]/Library/$sqlquery-run queryReference or queryResource
Instance POST [base]/Library/[id]/$sqlquery-run The Library instance

Execution Flow:

  1. Resolve ViewDefinitions from relatedArtifact
  2. Materialize each ViewDefinition as a table
  3. Bind parameter values to SQL placeholders
  4. Execute SQL query
  5. Return results in requested format

Implementations MUST ensure parameter values are safely bound to queries and not subject to SQL injection. Use parameterized queries or equivalent safe binding mechanisms where available. Simple string interpolation MUST NOT be used to implement parameter binding.

URL: [base]/$sqlquery-run

URL: [base]/Library/$sqlquery-run

URL: [base]/Library/[id]/$sqlquery-run

Parameters

UseNameScopeCardinalityTypeBindingDocumentation
IN_formattype, instance1..1codeOutput Format Codes (Extensible)

Output format for the result (json, ndjson, csv, parquet).

INheadertype, instance0..1boolean

Include CSV headers (default true). Applies only when csv output is requested.

INqueryReferencetype0..1Reference

Reference to a SQLQuery Library stored on the server.

INqueryResourcetype0..1https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery

Inline SQLQuery Library resource to execute.

INparametertype, instance0..*

Query parameter values. Each parameter must match a declared parameter in the SQLQuery Library.

INparameter.name1..1string

Parameter name (must match Library.parameter.name).

INparameter.value1..1DataType

Parameter value (use valueString, valueDate, valueInteger, etc. matching the declared type).

INsourcetype, instance0..1string

External data source containing the ViewDefinition tables.

OUTreturn1..1Binary

Query results encoded in the requested output format.

Notes:

Examples

Instance-Level (Library on Server)

When the SQLQuery Library is stored on the server, invoke directly on the instance:

POST /Library/patient-bp-query/$sqlquery-run HTTP/1.1
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "_format", "valueCode": "csv" },
    { "name": "parameter", "part": [
      { "name": "name", "valueString": "patient_id" },
      { "name": "value", "valueString": "Patient/123" }
    ]},
    { "name": "parameter", "part": [
      { "name": "name", "valueString": "from_date" },
      { "name": "value", "valueDate": "2024-01-01" }
    ]}
  ]
}

Type-Level with Reference

Reference a stored Library by URL or relative reference:

POST /Library/$sqlquery-run HTTP/1.1
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "_format", "valueCode": "json" },
    { "name": "queryReference", "valueReference": {
      "reference": "Library/patient-bp-query"
    }},
    { "name": "parameter", "part": [
      { "name": "name", "valueString": "patient_id" },
      { "name": "value", "valueString": "Patient/123" }
    ]}
  ]
}

Type-Level with Inline Resource

Pass the SQLQuery Library inline for ad-hoc queries:

POST /Library/$sqlquery-run HTTP/1.1
Content-Type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    { "name": "_format", "valueCode": "ndjson" },
    { "name": "queryResource", "resource": {
      "resourceType": "Library",
      "meta": { "profile": ["https://sql-on-fhir.org/ig/StructureDefinition/SQLQuery"] },
      "type": { "coding": [{ "system": "https://sql-on-fhir.org/ig/CodeSystem/LibraryTypesCodes", "code": "sql-query" }] },
      "status": "active",
      "relatedArtifact": [
        { "type": "depends-on", "resource": "https://example.org/ViewDefinition/patient_view", "label": "p" }
      ],
      "content": [{
        "contentType": "application/sql",
        "title": "SELECT p.id, p.name FROM p WHERE p.active = true",
        "data": "U0VMRUNUIHAuaWQsIHAubmFtZSBGUk9NIHAgV0hFUkUgcC5hY3RpdmUgPSB0cnVl"
      }]
    }}
  ]
}

The inline SQL (base64-decoded): SELECT p.id, p.name FROM p WHERE p.active = true

Response

All examples return a Binary with results in the requested format:

HTTP/1.1 200 OK
Content-Type: text/csv

patient_id,systolic,effective_date
Patient/123,120,2024-01-15
Patient/123,118,2024-02-20

Parameter Types

Use the appropriate value[x] type matching the Library’s declared parameter type:

Library.parameter.type Parameters value
string valueString
integer valueInteger
date valueDate
dateTime valueDateTime
boolean valueBoolean
decimal valueDecimal

Error Handling

Status Condition
400 Bad Request Missing required parameter, invalid value type
404 Not Found Library or ViewDefinition not found
422 Unprocessable Entity SQL execution error