{ "resourceType" : "OperationDefinition", "id" : "SQLRun", "language" : "en", "text" : { "status" : "generated", "div" : "

Generated Narrative: OperationDefinition SQLRun

URL: [base]/$sql-run

Parameters

UseNameScopeCardinalityTypeBindingDocumentation
INsubjectCanonical0..1canonical (View Definition, SQL Query Library, SQL View Library)

Canonical URL of the ViewDefinition, SQLQuery Library or SQLView Library to execute, optionally with a |version suffix pinning a version. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request.

\n
INsubjectReference0..1Reference (View Definition, SQL Query Library, SQL View Library)

Literal location of the subject to execute: a relative URL on this server, or an absolute URL. Not a canonical URL; use subjectCanonical for that. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request.

\n
INsubjectResource0..1CanonicalResource (View Definition, SQL Query Library, SQL View Library)

Inline ViewDefinition, SQLQuery Library or SQLView Library to execute. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request. Carries a resource, so it requires POST. The declared type is CanonicalResource because ViewDefinition is a logical model rather than a FHIR resource; see Common Operation Behavior (operations-common.html#declared-type).

\n
INparameters0..1Parameters

Input parameter values for the subject, bound by name to the parameters the Library declares (Library.parameter.name), using the value[x] type matching each declared type. Permitted only where the subject is a SQLQuery or SQLView; supplying it where the subject is a ViewDefinition is rejected with 400 Bad Request, because a ViewDefinition declares no parameters. Carries a resource, so it requires POST.

\n
INcontext0..*CanonicalResource (View Definition, SQL View Library)

Supporting artifacts the server cannot itself resolve, supplied inline and matched by canonical URL against the dependencies in the subject's transitive relatedArtifact graph. Accepts inline resources only; there is no context by canonical URL, because a URL is exactly what the server has already failed to resolve. Carries a resource, so it requires POST. See Common Operation Behavior (operations-common.html#context).

\n
INresource0..*Resource

FHIR resources to transform instead of using server data. Repeatable. A Bundle supplied here is unwrapped: the view runs against each Bundle.entry[*].resource rather than against the Bundle itself. Permitted only where the subject is a ViewDefinition; supplying it where the subject is a SQLQuery or SQLView is rejected with 400 Bad Request, because how inline resources reach each dependency view is not specified. Carries a resource, so it requires POST. See OperationDefinition-SQLRun notes (Resource parameter and Bundle inputs).

\n
IN_format0..1codeOutput Format Codes (Extensible)

Output format for the result (json, ndjson, csv, parquet, fhir). Use fhir to return results as a FHIR Parameters resource. Optional; if omitted, the server returns ndjson by default. See Common Operation Behavior (operations-common.html).

\n
INheader0..1boolean

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

\n
INpatient0..*Reference

Restrict the FHIR resources feeding the view, before projection, to the supplied patient(s). Where the subject is a SQLQuery or SQLView, that means before the SQL executes. An unresolvable patient is rejected with 400 Bad Request. See Common Operation Behavior (operations-common.html#patient-filter).

\n
INgroup0..*Reference

Restrict the FHIR resources feeding the view, before projection, to members of the supplied group(s). Where the subject is a SQLQuery or SQLView, that means before the SQL executes. An unresolvable group is rejected with 400 Bad Request. See Common Operation Behavior (operations-common.html#group-filter).

\n
IN_since0..1instant

Include only resources whose state changed after this instant. See Common Operation Behavior (operations-common.html#since-filter).

\n
INsource0..1string

External data source to read from instead of the server's own data (for example a URI or bucket name). Where the subject is a SQLQuery or SQLView, this is where the ViewDefinition tables the query selects from are found.

\n
IN_limit0..1integer

Maximum number of rows to return.

\n
OUTreturn1..1Binary

Result rows in the requested output format, returned as a raw binary stream in the format's native media type, not a serialized Binary resource envelope. When _format=fhir is requested, the response is a Parameters resource instead. See Common Operation Behavior (operations-common.html).

\n
" }, "extension" : [{ "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-wg", "valueCode" : "fhir" }, { "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm", "valueInteger" : 2, "_valueInteger" : { "extension" : [{ "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom", "valueCanonical" : "http://hl7.org/fhir/uv/sql-on-fhir/ImplementationGuide/hl7.fhir.uv.sql-on-fhir" }] } }, { "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status", "valueCode" : "trial-use", "_valueCode" : { "extension" : [{ "url" : "http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom", "valueCanonical" : "http://hl7.org/fhir/uv/sql-on-fhir/ImplementationGuide/hl7.fhir.uv.sql-on-fhir" }] } }], "url" : "http://hl7.org/fhir/uv/sql-on-fhir/OperationDefinition/SQLRun", "identifier" : [{ "system" : "urn:ietf:rfc:3986", "value" : "urn:oid:2.16.840.1.113883.4.642.40.77.33.6" }], "version" : "3.0.0-ballot", "versionAlgorithmString" : "semver", "name" : "SQLRun", "title" : "SQL Run", "status" : "active", "kind" : "operation", "date" : "2026-08-13T15:42:34+00:00", "publisher" : "HL7 International / FHIR Infrastructure", "contact" : [{ "name" : "HL7 International / FHIR Infrastructure", "telecom" : [{ "system" : "url", "value" : "http://www.hl7.org/Special/committees/fiwg" }] }], "description" : "Execute a ViewDefinition, SQLQuery Library or SQLView Library and return the result in the requested output format.", "jurisdiction" : [{ "coding" : [{ "system" : "http://unstats.un.org/unsd/methods/m49/m49.htm", "code" : "001", "display" : "World" }] }], "code" : "sql-run", "system" : true, "type" : false, "instance" : false, "parameter" : [{ "name" : "subjectCanonical", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Canonical URL of the ViewDefinition, SQLQuery Library or SQLView Library to execute, optionally with a |version suffix pinning a version. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request.", "type" : "canonical", "targetProfile" : ["http://hl7.org/fhir/StructureDefinition/ViewDefinition", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"] }, { "name" : "subjectReference", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Literal location of the subject to execute: a relative URL on this server, or an absolute URL. Not a canonical URL; use subjectCanonical for that. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request.", "type" : "Reference", "targetProfile" : ["http://hl7.org/fhir/StructureDefinition/ViewDefinition", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"] }, { "name" : "subjectResource", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Inline ViewDefinition, SQLQuery Library or SQLView Library to execute. Exactly one of subjectCanonical, subjectReference and subjectResource is supplied; supplying none, or more than one, is rejected with 400 Bad Request. Carries a resource, so it requires POST. The declared type is CanonicalResource because ViewDefinition is a logical model rather than a FHIR resource; see Common Operation Behavior (operations-common.html#declared-type).", "type" : "CanonicalResource", "targetProfile" : ["http://hl7.org/fhir/StructureDefinition/ViewDefinition", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"] }, { "name" : "parameters", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Input parameter values for the subject, bound by name to the parameters the Library declares (Library.parameter.name), using the value[x] type matching each declared type. Permitted only where the subject is a SQLQuery or SQLView; supplying it where the subject is a ViewDefinition is rejected with 400 Bad Request, because a ViewDefinition declares no parameters. Carries a resource, so it requires POST.", "type" : "Parameters" }, { "name" : "context", "use" : "in", "min" : 0, "max" : "*", "documentation" : "Supporting artifacts the server cannot itself resolve, supplied inline and matched by canonical URL against the dependencies in the subject's transitive relatedArtifact graph. Accepts inline resources only; there is no context by canonical URL, because a URL is exactly what the server has already failed to resolve. Carries a resource, so it requires POST. See Common Operation Behavior (operations-common.html#context).", "type" : "CanonicalResource", "targetProfile" : ["http://hl7.org/fhir/StructureDefinition/ViewDefinition", "http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"] }, { "name" : "resource", "use" : "in", "min" : 0, "max" : "*", "documentation" : "FHIR resources to transform instead of using server data. Repeatable. A Bundle supplied here is unwrapped: the view runs against each Bundle.entry[*].resource rather than against the Bundle itself. Permitted only where the subject is a ViewDefinition; supplying it where the subject is a SQLQuery or SQLView is rejected with 400 Bad Request, because how inline resources reach each dependency view is not specified. Carries a resource, so it requires POST. See OperationDefinition-SQLRun notes (Resource parameter and Bundle inputs).", "type" : "Resource" }, { "name" : "_format", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Output format for the result (json, ndjson, csv, parquet, fhir). Use fhir to return results as a FHIR Parameters resource. Optional; if omitted, the server returns ndjson by default. See Common Operation Behavior (operations-common.html).", "type" : "code", "binding" : { "strength" : "extensible", "valueSet" : "http://hl7.org/fhir/uv/sql-on-fhir/ValueSet/OutputFormatCodes" } }, { "name" : "header", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Include CSV headers (default true). Applies only when csv output is requested.", "type" : "boolean" }, { "name" : "patient", "use" : "in", "min" : 0, "max" : "*", "documentation" : "Restrict the FHIR resources feeding the view, before projection, to the supplied patient(s). Where the subject is a SQLQuery or SQLView, that means before the SQL executes. An unresolvable patient is rejected with 400 Bad Request. See Common Operation Behavior (operations-common.html#patient-filter).", "type" : "Reference" }, { "name" : "group", "use" : "in", "min" : 0, "max" : "*", "documentation" : "Restrict the FHIR resources feeding the view, before projection, to members of the supplied group(s). Where the subject is a SQLQuery or SQLView, that means before the SQL executes. An unresolvable group is rejected with 400 Bad Request. See Common Operation Behavior (operations-common.html#group-filter).", "type" : "Reference" }, { "name" : "_since", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Include only resources whose state changed after this instant. See Common Operation Behavior (operations-common.html#since-filter).", "type" : "instant" }, { "name" : "source", "use" : "in", "min" : 0, "max" : "1", "documentation" : "External data source to read from instead of the server's own data (for example a URI or bucket name). Where the subject is a SQLQuery or SQLView, this is where the ViewDefinition tables the query selects from are found.", "type" : "string" }, { "name" : "_limit", "use" : "in", "min" : 0, "max" : "1", "documentation" : "Maximum number of rows to return.", "type" : "integer" }, { "name" : "return", "use" : "out", "min" : 1, "max" : "1", "documentation" : "Result rows in the requested output format, returned as a raw binary stream in the format's native media type, not a serialized Binary resource envelope. When _format=fhir is requested, the response is a Parameters resource instead. See Common Operation Behavior (operations-common.html).", "type" : "Binary" }] }