<?xml version="1.0" encoding="UTF-8"?>

<OperationDefinition xmlns="http://hl7.org/fhir">
  <id value="SQLRun"/>
  <language value="en"/>
  <text>
    <status value="generated"/><div xmlns="http://www.w3.org/1999/xhtml"><p class="res-header-id"><b>Generated Narrative: OperationDefinition SQLRun</b></p><a name="SQLRun"> </a><a name="hcSQLRun"> </a><p>URL: [base]/$sql-run</p><h3>Parameters</h3><table class="grid"><tr><td><b>Use</b></td><td><b>Name</b></td><td><b>Scope</b></td><td><b>Cardinality</b></td><td><b>Type</b></td><td><b>Binding</b></td><td><b>Documentation</b></td></tr><tr><td>IN</td><td>subjectCanonical</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#canonical">canonical</a> (<a href="StructureDefinition-ViewDefinition.html" title="http://hl7.org/fhir/StructureDefinition/ViewDefinition">View Definition</a>, <a href="StructureDefinition-SQLQuery.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery">SQL Query Library</a>, <a href="StructureDefinition-SQLView.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView">SQL View Library</a>)</td><td/><td><div><p>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.</p>
</div></td></tr><tr><td>IN</td><td>subjectReference</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/references.html#Reference">Reference</a> (<a href="StructureDefinition-ViewDefinition.html" title="http://hl7.org/fhir/StructureDefinition/ViewDefinition">View Definition</a>, <a href="StructureDefinition-SQLQuery.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery">SQL Query Library</a>, <a href="StructureDefinition-SQLView.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView">SQL View Library</a>)</td><td/><td><div><p>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.</p>
</div></td></tr><tr><td>IN</td><td>subjectResource</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/canonicalresource.html">CanonicalResource</a> (<a href="StructureDefinition-ViewDefinition.html" title="http://hl7.org/fhir/StructureDefinition/ViewDefinition">View Definition</a>, <a href="StructureDefinition-SQLQuery.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery">SQL Query Library</a>, <a href="StructureDefinition-SQLView.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView">SQL View Library</a>)</td><td/><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>parameters</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/parameters.html">Parameters</a></td><td/><td><div><p>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.</p>
</div></td></tr><tr><td>IN</td><td>context</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/canonicalresource.html">CanonicalResource</a> (<a href="StructureDefinition-ViewDefinition.html" title="http://hl7.org/fhir/StructureDefinition/ViewDefinition">View Definition</a>, <a href="StructureDefinition-SQLView.html" title="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView">SQL View Library</a>)</td><td/><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>resource</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/resource.html">Resource</a></td><td/><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>_format</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#code">code</a></td><td><a href="ValueSet-OutputFormatCodes.html">Output Format Codes</a> (Extensible)</td><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>header</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#boolean">boolean</a></td><td/><td><div><p>Include CSV headers (default true). Applies only when csv output is requested.</p>
</div></td></tr><tr><td>IN</td><td>patient</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/references.html#Reference">Reference</a></td><td/><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>group</td><td/><td>0..*</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/references.html#Reference">Reference</a></td><td/><td><div><p>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).</p>
</div></td></tr><tr><td>IN</td><td>_since</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#instant">instant</a></td><td/><td><div><p>Include only resources whose state changed after this instant. See Common Operation Behavior (operations-common.html#since-filter).</p>
</div></td></tr><tr><td>IN</td><td>source</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#string">string</a></td><td/><td><div><p>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.</p>
</div></td></tr><tr><td>IN</td><td>_limit</td><td/><td>0..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/datatypes.html#integer">integer</a></td><td/><td><div><p>Maximum number of rows to return.</p>
</div></td></tr><tr><td>OUT</td><td>return</td><td/><td>1..1</td><td><a href="http://hl7.org/fhir/6.0.0-ballot5/binary.html">Binary</a></td><td/><td><div><p>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).</p>
</div></td></tr></table></div>
  </text>
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-wg">
    <valueCode value="fhir"/>
  </extension>
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-fmm">
    <valueInteger value="2">
      <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical value="http://hl7.org/fhir/uv/sql-on-fhir/ImplementationGuide/hl7.fhir.uv.sql-on-fhir"/>
      </extension>
    </valueInteger>
  </extension>
  <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-standards-status">
    <valueCode value="trial-use">
      <extension url="http://hl7.org/fhir/StructureDefinition/structuredefinition-conformance-derivedFrom">
        <valueCanonical value="http://hl7.org/fhir/uv/sql-on-fhir/ImplementationGuide/hl7.fhir.uv.sql-on-fhir"/>
      </extension>
    </valueCode>
  </extension>
  <url value="http://hl7.org/fhir/uv/sql-on-fhir/OperationDefinition/SQLRun"/>
  <identifier>
    <system value="urn:ietf:rfc:3986"/>
    <value value="urn:oid:2.16.840.1.113883.4.642.40.77.33.6"/>
  </identifier>
  <version value="3.0.0-ballot"/>
  <versionAlgorithmString value="semver"/>
  <name value="SQLRun"/>
  <title value="SQL Run"/>
  <status value="active"/>
  <kind value="operation"/>
  <date value="2026-08-13T15:42:34+00:00"/>
  <publisher value="HL7 International / FHIR Infrastructure"/>
  <contact>
    <name value="HL7 International / FHIR Infrastructure"/>
    <telecom>
      <system value="url"/>
      <value value="http://www.hl7.org/Special/committees/fiwg"/>
    </telecom>
  </contact>
  <description value="Execute a ViewDefinition, SQLQuery Library or SQLView Library and return the result in the requested output format."/>
  <jurisdiction>
    <coding>
      <system value="http://unstats.un.org/unsd/methods/m49/m49.htm"/>
      <code value="001"/>
      <display value="World"/>
    </coding>
  </jurisdiction>
  <code value="sql-run"/>
  <system value="true"/>
  <type value="false"/>
  <instance value="false"/>
  <parameter>
    <name value="subjectCanonical"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="canonical"/>
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/ViewDefinition"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"/>
  </parameter>
  <parameter>
    <name value="subjectReference"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="Reference"/>
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/ViewDefinition"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"/>
  </parameter>
  <parameter>
    <name value="subjectResource"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="CanonicalResource"/>
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/ViewDefinition"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLQuery"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"/>
  </parameter>
  <parameter>
    <name value="parameters"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="Parameters"/>
  </parameter>
  <parameter>
    <name value="context"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="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 value="CanonicalResource"/>
    <targetProfile value="http://hl7.org/fhir/StructureDefinition/ViewDefinition"/>
    <targetProfile value="http://hl7.org/fhir/uv/sql-on-fhir/StructureDefinition/SQLView"/>
  </parameter>
  <parameter>
    <name value="resource"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="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 value="Resource"/>
  </parameter>
  <parameter>
    <name value="_format"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="code"/>
    <binding>
      <strength value="extensible"/>
      <valueSet value="http://hl7.org/fhir/uv/sql-on-fhir/ValueSet/OutputFormatCodes"/>
    </binding>
  </parameter>
  <parameter>
    <name value="header"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="Include CSV headers (default true). Applies only when csv output is requested."/>
    <type value="boolean"/>
  </parameter>
  <parameter>
    <name value="patient"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="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 value="Reference"/>
  </parameter>
  <parameter>
    <name value="group"/>
    <use value="in"/>
    <min value="0"/>
    <max value="*"/>
    <documentation value="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 value="Reference"/>
  </parameter>
  <parameter>
    <name value="_since"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="Include only resources whose state changed after this instant. See Common Operation Behavior (operations-common.html#since-filter)."/>
    <type value="instant"/>
  </parameter>
  <parameter>
    <name value="source"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="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 value="string"/>
  </parameter>
  <parameter>
    <name value="_limit"/>
    <use value="in"/>
    <min value="0"/>
    <max value="1"/>
    <documentation value="Maximum number of rows to return."/>
    <type value="integer"/>
  </parameter>
  <parameter>
    <name value="return"/>
    <use value="out"/>
    <min value="1"/>
    <max value="1"/>
    <documentation value="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 value="Binary"/>
  </parameter>
</OperationDefinition>