$run operation

SQL on FHIR provides the $run operation to run a given ViewDefinition. It can evaluate the provided or stored ViewDefinition on provided or stored resources.

SQL on FHIR specification defines $run operation .

General syntax

To call the $run operation, use the following request format:

POST /fhir/ViewDefinition/[<resource-id>/]$run
Content-Type: application/json
Accept: preferred format

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": parameter name,
      "resource": resource value
    },
    ...
  ]
}

The ViewDefinition resource should be specified by:

• URL (overrid parameter),
• viewResource or viewReference parameter (mutually exclusive).

Parameters

• viewReference: reference to the ViewDefinition resource.

  This parameter is exclusive with the viewResource parameter.

  Example:

  {
    "name": "viewReference",
    "valueReference": "ViewDefinition/patient-view"
  }
  

• viewResource: provided viewDefinition resource.

  This parameter is exclusive with the viewReference parameter.

  Example:

  {
    "name": "viewResource",
    "resource": {
      "id": "vd-1",
      "resourceType": "ViewDefinition",
      "status": "draft",
      "resource": "Patient",
      "select": [
        {
          "column": [
            {
              "name": "patient_id",
              "path": "getResourceKey()"
            }
          ]
        }
      ]
    }
  }
  

• resource: provided resources to run ViewDefinition on.

  If this parameter is specified, the server runs ViewDefinition only on this resource, and not on stored resources. Conversely, if this parameter is omitted, the server runs ViewDefinition on stored resources.

  Example:

  {
    "name": "resource",
    "resource": {
      "resourceType": "Patient",
      "active": true
    }
  }
  

  To provide multiple resources, provide this parameter multiple times.

• group: use only resources which are members of the specified group

  Filters all input resources, and runs ViewDefinition only on those resources which are members of the specified group.

  Example:

  {
    "name": "group",
    "valueReference": {
      "reference": "Group/my-group"
    }
  }
  

• patient: use only resources which are related to the specified patient.

  Filters all input resources and runs ViewDefinition only on those resources which are members of the patient compartment for the specified patient.

  Example:

  {
    "name": "patient",
    "valueReference": {
      "reference": "Patient/patient-1"
    }
  }
  

• _since: use only resources updated later than the specified date

  Filters all input resources and runs ViewDefinition only on those resources which were modified (meta.lastModified) since the specified date.

  Example:

  {
    "name": "_since",
    "valueInstant": "2020-02-25T17:59:02.812Z"
  }
  

• _format: output format (json/ndjson/csv)

  Returns response in the given format. Allowed values: json, ndjson, csv.

  Example:

  {
    "name": "_format",
    "valueCode": "json"
  }
  

• _limit: Maximum number of returned rows

  Limits the number of the returned rows to the given value. Note that it limits the number of the returned rows, not the number of input resources.

  Example:

  {
    "name": "_limit",
    "valueInteger": 1
  }
  

Output format (content negotiation)

Depending on the combination of the Accept header and _format parameter, the returned type is different.

By default, the response is wrapped in the Binary resource. But if Accept specifies the media type specified by format, the server doesn't wrap response in Binary.

For example, if you specify Accept: application/fhir+json and _format: JSON, the server will return Binary resource containing the returned payload.

If you specify Accept: application/json and _format: JSON, the server will return the processed data (without wrapping inside Binary resource).

Examples

Provided resources and ViewDefinition

POST /fhir/ViewDefinition/$run
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_format",
      "valueCode": "json"
    },
    {
      "name": "viewResource",
      "resource": {
        "id": "view-1",
        "resourceType": "ViewDefinition",
        "status": "draft",
        "resource": "Patient",
        "select": [
          {
            "column": [
              {
                "name": "patient_id",
                "path": "getResourceKey()"
              }
            ]
          }
        ]
      }
    },
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "source-1"
      }
    },
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "source-2"
      }
    }
  ]
}

Provided resources, stored ViewDefinition

POST /fhir/ViewDefinition/$run
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_format",
      "valueCode": "json"
    },
    {
      "name": "viewReference",
      "valueReference": {
        "reference": "ViewDefinition/patient"
      }
    },
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "source-1"
      }
    },
    {
      "name": "resource",
      "resource": {
        "resourceType": "Patient",
        "id": "source-2"
      }
    }
  ]
}

Stored resources, stored ViewDefinition

POST /fhir/ViewDefinition/$run
Content-Type: application/json
Accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_format",
      "valueCode": "json"
    },
    {
      "name": "viewReference",
      "valueReference": {
        "reference": "ViewDefinition/patient"
      }
    }
  ]
}

Output examples

With Accept: application/json and _format: JSON

[
  {
    "patient_id": "source-1"
  },
  {
    "patient_id": "source-2"
  }
]

With Accept: application/fhir+json and _format: JSON

{
  "resourceType": "Binary",
  "contentType": "application/json",
  "data": "WwogIHsKICAgICJwYXRpZW50X2lkIjogInNvdXJjZS0xIgogIH0sCiAgewogICAgInBhdGllbnRfaWQiOiAic291cmNlLTIiCiAgfQpdCg=="
}