Query Requirements ¶

Release: 1.0.0

Purpose ¶

This specification describes the service endpoints and data-models used when querying an openEHR system.

AQL Archetype Query Language is the primary query language.

The query response may also be used by other API endpoints in the openEHR REST API. I.e. composition resource might return several compositions. These operations will return the response structure defined here.

Single EHR queries ¶

A common use-case is to execute queries within a specific EHR.

Population queries ¶

Population queries are queries which are executed on several EHRs in the same request. Examples of use-cases will be:

• Ward lists

• Explore correlations between patients in an pandemic situation

• Research, e.g. epidemiology, population health

Stored queries ¶

Stored queries are queries which have their definition stored on the server. The queries will expose mandatory and optional parameters for the clients.

Using stored queries has lots of advantages:

• separation of responsibilites (some users/developers write queries, others just call/execute them and consume the responses)

• no need to pass long query string over the network

Common Headers and Query Parameters ¶

All query calls will be able to use at least the following parameters:

• ehr_id - this parameter SHOULD be supplied when executing single EHR queries and MAY be used by the underlying backend to perform routing, optimizations or similar, It MUST NOT be supplied for ’population queries’ and similar multi-patient queries. It can be supplied as query parameter ehr_id or as header openEHR-EHR-id.

• offset and fetch - these two parameters can be used for paging, both 0-based. Default for offset is 0. Default for limit depends on the implementation.

• other parameters to replace placeholders within the query. For the following AQL query SELECT c/name/value FROM COMPOSITION c WHERE c/uid/value = $uid, user can supply parameter uid, i.e.: /aql?uid=90910cf0-66a0-4382-b1f8-c0f27e81b42d::default::1

Data structures ¶

Request structure ¶

Below is a mostly self-documented AQL query request.

{
  "q": "select o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/magnitude as temperature, o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/units as unit from EHR[ehr_id/value='554f896d-faca-4513-bddf-664541146308d'] CONTAINS Observation o[openEHR-EHR-OBSERVATION.body_temperature-zn.v1] WHERE o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0004]/value/magnitude > $temperature and o/data[at0002]/events[at0003 and name/value='Any event']/data[at0001]/items[at0.63 and name/value='Symptoms']/value/defining_code/code_string=$chills order by temperature desc fetch 3",
  "query-parameters": {
    "temperature": 38.5,
    "chills": "at0.64"
  }
}

Response structure ¶

Metadata ¶

Data ¶

ResultSet example ¶

Below is a synthesized response with all attributes.

{
  "meta": {
    "_href": "<the URI for the executed AQL - used only for GET executions >",
    "_type": "RESULTSET",
    "_schema_version": "1.0.0",
    "_created": "2017-08-19T00:25:47.568+02:00",
    "_generator": "DIPS.OpenEhr.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)",
    "_executed_aql": "< the executed aql >", /* should only be returned in debug mode */
  },
  "name": "<the name/identifier of the stored query that was executed>",
  "q": "select e/ehr_id/value, c/context/start_time/value as startTime,  c/uid/value as cid, c/name from EHR e contains  Composition c limit 2",
  "columns": [
    {
      "name": "#0",
      "path": "/ehr_id/value"
    },
    {
      "name": "startTime",
      "path": "/context/start_time/value"
    },
    {
      "name": "cid",
      "path": "/uid/value"
    },
    {
      "name": "#3",
      "path": "/name"
    }
  ],
  "rows": [
    [
      "81433066-c417-4813-9b29-79783e7bed23",
      "2017-02-16T13:50:11.308+01:00",
      "90910cf0-66a0-4382-b1f8-c0f27e81b42d::default::1",
      {
        "_type": "DV_TEXT",
        "value": "Labs"
      }
    ]
  ]
}

Query ¶

The REST API currently supports AQL queries. Other query types might be added at a later time.