Should SQLQuery be represented by Library or OperationDefinition?

[niquola]

Context: considering whether SQLQuery should remain a Library (query definition + content + dependencies) with a separate $sqlquery-run OperationDefinition, or be replaced by an OperationDefinition (possibly kind=query / _query).

Questions:

• Pros/cons of keeping Library vs switching to OperationDefinition as the primary query artifact?
• If keeping Library, should we also define a kind=query OperationDefinition for named-parameter GET invocations?
• Any precedent in FHIR for storing executable queries in OperationDefinition?

Notes: Library currently carries SQL attachments (dialect variants), relatedArtifact dependencies (ViewDefinitions), and parameters. OperationDefinition is execution-oriented. Want community input before changing direction.

[niquola]

Detailed Proposal with Examples

Context

We currently represent SQLQuery as a Library (content + dependencies + parameters) and define $sqlquery-run as an OperationDefinition for execution. We’re considering whether SQLQuery should remain Library-based or be replaced by an OperationDefinition (possibly kind="query" and invoked via _query).

---

Option A — Keep Library as the SQLQuery definition (current approach)

Why it fits

• Library is designed to carry logic/content and metadata.
• It naturally supports multiple SQL dialect attachments via content.
• It already has parameters and relatedArtifact for dependencies.

Example: SQLQuery Library

{
  "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" }] },
  "name": "PatientBloodPressure",
  "status": "active",
  "relatedArtifact": [
    { "type": "depends-on", "resource": "https://example.org/ViewDefinition/patient_view", "label": "patient" },
    { "type": "depends-on", "resource": "https://example.org/ViewDefinition/bp_view", "label": "bp" }
  ],
  "parameter": [
    { "name": "patient_id", "type": "string", "use": "in" },
    { "name": "from_date", "type": "date", "use": "in" }
  ],
  "content": [{
    "contentType": "application/sql",
    "title": "SELECT patient.id, bp.systolic FROM patient JOIN bp ON patient.id = bp.patient_id WHERE patient.id = :patient_id AND bp.effective_date >= :from_date",
    "data": "U0VMRUNUIHBhdGllbnQuaWQsIGJwLnN5c3RvbGljIEZST00gcGF0aWVudCBKT0lOIGJwIE9OIHBhdGllbnQuaWQgPSBicC5wYXRpZW50X2lkIFdIRVJFIHBhdGllbnQuaWQgPSA6cGF0aWVudF9pZCBBTkQgYnAuZWZmZWN0aXZlX2RhdGUgPj0gOmZyb21fZGF0ZQ=="
  }]
}

Execution

• Defined separately via $sqlquery-run OperationDefinition.
• The operation resolves ViewDefinitions and executes SQL.

---

Option B — Replace Library with OperationDefinition

How it might look

• SQL is stored in OperationDefinition (not typical usage).
• Parameters are already modeled in OperationDefinition.
• Execution and definition are merged into one artifact.

Concerns

• OperationDefinition isn’t designed to store multiple SQL attachments/dialects.
• It’s execution‑centric, not content‑centric.
• Less reuse outside of execution contexts.

---

Option C — Add a named query OperationDefinition (kind = "query")

Motivation

• For simple URL‑style invocations: ?_query=...&param=value
• Official FHIR mechanism for query operations.

FHIR rules

• kind="query" requires parameters to be search‑style.
• Must return a single output parameter named result of type Bundle.

Example invocation

GET [base]/Patient?_query=patient-bp&patient_id=123&from_date=2024-01-01

---

Questions for the Community

1. Should SQLQuery remain a Library (definition) + OperationDefinition (execution), or be moved to OperationDefinition?
2. If we keep Library, should we also define a kind="query" OperationDefinition for URL‑style invocations?
3. Is there any FHIR precedent for storing executable SQL directly in OperationDefinition?
4. What would best serve interoperability and tooling?