OpenEHR REST Query API

Release: 0.9.4

Status: DEVELOPMENT

Query Requirements

Release: 0.9.4

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

Field Description
_href URL of the query executed (only for GET endpoint)
_type Defines type of the serialized object
_schema_version The version of the specification defining the serialized object
_created Result creation timestamp (in full ISO8601 format)
_generator Some identifier of the application that generated the result. Useful i.e. for debugging
_executed_aql The actual query (i.e. AQL) that was executed by the server after exploding the parameters. This attribute is not mandatory, but is useful for debugging

Data

Field Description
name Name of a query when registered as a stored query
q The AQL which was given in the request
columns Columns are defined by the client provided with the given AQL. I.e. select c/uid/value as CidValue, c/context/start_time as StartTime from .... will give two columns. One columns for CidValue and another for StartTime.
columns.name Name of the column. I.e. CidValue or StartTime from the example above, when column alias is not present in the AQL a 0-based column index is used prefixed by a hash sign (i.e. #0, #1…)
columns.path Path from the given AQL of the specified column. I.e. columns CidValue will have path /uid/value
rows Ordered list with results.
rows.row Each row list of cells. One cell for each column. Content of a cell is ANY (i.e. a OBJECT in most programming languages)

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_q": "< 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.

Execute Query

Release: 0.9.4

GET http://www.openehr.org/api/v1/query/aql?q=&query_parameter=&offset=&fetch=
Responses200
Headers
Content-Type: application/json
ETag: cdbb5db1-e466-4429-a9e5-bf80a54e120b
Body
{
    /* See discussion on result-set in overview */
}

Execute ad-hoc (non-stored) AQL query
GET/query/aql{?q,query_parameter,offset,fetch}

Warning: URIs in practice have a length restriction. Long AQLs in parameter q and many long query_parameters may add up to reach that limit, thus we recommend using the POST /query/aql instead when such risks are expected.

URI Parameters
HideShow
q
string (required) 

the AQL to be executed

offset
number (optional) 

row number in result-set to start result-set from (0-based)

fetch
number (optional) 

number of rows to fetch

query_parameter
string (optional) 

query parameters


POST http://www.openehr.org/api/v1/query/aql
Requestsexample 1
Headers
Content-Type: application/json
Body
{
    "q": "<the query to be executed>",
    "offset": NUMBER_TO_START_FROM,
    "fetch": NUMBER_TO_FETCH,
    "query-parameters": {
        "parameter-x-name": "parameter-x-value",
        "parameter-y-name": "parameter-y-value"
    }
}
Responses200
Headers
Content-Type: application/json
ETag: cdbb5db1-e466-4429-a9e5-bf80a54e120b
Body
{
    /* See discussion on result-set in overview */
}

Execute ad-hoc (non-stored) AQL query
POST/query/aql


GET http://www.openehr.org/api/v1/query/qualified_query_name/version?offset=&fetch=&query_parameter=
Responses200
Headers
Content-Type: application/json
ETag: cdbb5db1-e466-4429-a9e5-bf80a54e120b
Body
{
  /* See discussion on result-set in overview */
}

Execute stored query
GET/query/{qualified_query_name}/{version}{?offset,fetch,query_parameter}

Execute a stored query with the supplied qualified_query_name.

All query parameters found except “offset” and “fetch” are sent to the query execution engine. For parameters in AQL queries, see http://www.openehr.org/releases/QUERY/latest/docs/AQL/AQL.html#_parameters. For example call:

  • GET /query/com.vendor::compositions?temperature_from=36&temperature_unit=Cel

Will pass parameters temperature_from and temperature_unit to the underlying query.

URI Parameters
HideShow
qualified_query_name
string (required) 

qualified query name to be executed. It may be formatted as <namespace>::<query-name>, this way we can separate queries by domain, etc. Example qualified query name: org.openehr::compositions

version
string (optional) 

SEMVER style (major.minor.patch) version prefix. If only major or major.minor are used then the latest version with supplied prefix will be used.

offset
string (optional) 

Query response row number to start from (default: 0)

fetch
string (optional) 

Number of query response rows to fetch (from offset). For AQL queries: cannot be combined with http://www.openehr.org/releases/QUERY/latest/docs/AQL/AQL.html#_top

query_parameter
string (optional) 

query parameters (can appear multiple times)


POST http://www.openehr.org/api/v1/query/qualified_query_name/version
Requestsexample 1
Headers
Content-Type: application/json
If-None-Match: cdbb5db1-e466-4429-a9e5-bf80a54e120b
Body
{
    "offset": NUMBER_TO_START_FROM,
    "fetch": NUMBER_TO_FETCH,
    "query-parameters": {
        "parameter-x-name": "parameter-x-value",
        "parameter-y-name": "parameter-y-value"
    }
}
Responses200
Headers
Content-Type: application/json
ETag: cdbb5db1-e466-4429-a9e5-bf80a54e120b
Body
{
  /* See discussion on result-set in overview */
}

Execute stored query
POST/query/{qualified_query_name}/{version}

Execute a stored query with the supplied qualified_query_name.

The absence of the http header ‘ehr_id’ means that the stored query or request parameters MAY contain a list of several ehr_ids or be unconstrained regarding ehr_id (e.g. population queries).

URI Parameters
HideShow
qualified_query_name
string (required) 

qualified query name to be executed. It may be formatted as <namespace>::<query-name>, this way we can separate queries by domain, etc. Example qualified query name: org.openehr::compositions

version
string (required) 

SEMVER style (major.minor.patch) version prefix. If only major or major.minor are used then the latest version with supplied prefix will be used.


Generated by aglio on 17 Jul 2018