Query API (latest)

Description

Purpose

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

The Archetype Query Language(AQL) is the primary query language.

Prerequisite documents for reading this document include:

Related documents include:

Status

This specification is in the STABLE state, and can be downloaded as OpenAPI specification file (in YAML format) for validation, or for code generators. Users are encouraged to comment on and/or advise on these paragraphs as well as the main content.

The development version of this document can be found at https://specifications.openehr.org/releases/ITS-REST/latest/query.html.

Query types

Single EHR queries

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

This is achieved by supplying a ehr_id query parameter or setting a openEHR-EHR-id request header.

Population queries

Population queries are queries which are executed on several EHRs in the same request. These queries are not referring or using any ehr_id parameter to constrain the scope on a specific EHR.

Examples of use-cases can be:

  • Ward lists,
  • Explore correlations between patients in a pandemic situation,
  • Research, e.g. epidemiology, population health.

Stored queries

Stored queries are queries which have their definition stored (registered) on the server. These are identified by their qualified name and version.

Using stored queries has several of advantages:

  • separation of responsibilities (some users/developers write queries, others just call/execute them and consume the responses),
  • no need to pass long query string over the network.

Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

Ad-hoc queries

As opposed to stored queries, ad-hoc type queries does not have their definitions stored on the server, neither any associated identifier. These queries will be executed as-is, as part request body or query parameter, by the Execute ad-hoc AQL operation endpoint.

Qualified query name

Stored queries are identified by their name, used as qualified_query_name, and an optional version number.

Usually a qualified_query_name has a format of [{namespace}::]{query-name}.

The namespace is optional, and when used it should be in a form of a reverse domain name, which allows for separation of use of stored queries by teams, companies, etc. The query-name may include any combination of characters, matched by the pattern [a-zA-Z0-9_.-].

Examples of valid qualified_query_name:

  • org.openehr::my_compositions
  • my_compositions
  • ehr::all_influenza_vacc_candidates

The version identifier is in the format specified by SEMVER style (i.e. major.minor.patch). When only a partial version pattern is supplied, or when version is not supplied at all, the system must use the latest version with the supplied prefix - i.e. if only major or major.minor is used, then the latest query version matching supplied prefix will be used.

Request details

Below is a mostly self-documented AQL query in a request body.

{
    "q": "SELECT o/data[at0002]/events[at0003]/data[at0001]/items[at0004]/value/magnitude AS temperature, o/data[at0002]/events[at0003]/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]/data[at0001]/items[at0004]/value/magnitude > $temperature AND o/data[at0002]/events[at0003]/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"
    }
}

GET vs POST

Requests based on the GET method have URI length restriction, or some characters might not be allowed and have to be encoded. Long queries in the q parameter and having a long list of query_parameters may add up to reach that limit, thus we recommend clients using the POST method instead of GET.

Common Headers and Query Parameters

All query execution requests SHOULD support at least the following parameters:

  • ehr_id - used to execute the query within a single EHR context: an EHR identifier taken from EHR.ehr_id.value
  • offset - used for paging: the row number in result to start result-set from (0-based); default 0
  • fetch - used for paging: the number of rows to fetch (i.e. limit); default depends on the implementation, but cannot be combined with AQL-top
  • other parameter(s) to replace placeholder(s) within the query, here generically named query_parameters (see below).

Related request headers:

  • openEHR-EHR-id - used to execute the query within a single EHR context: an EHR identifier taken from EHR.ehr_id.value

Related response headers:

  • ETag - A unique identifier of the resultSet

About the ehr_id parameter

The ehr_id parameter SHOULD be supplied by clients 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.

Depending on the needs, clients MAY supply it as a query parameter ehr_id or alternatively as a request header named openEHR-EHR-id.

Query parameters

Depending on each query definition, various query parameters SHOULD be supported, generically named query_parameters in this specification, but in the real request they will have specific names (e.g. uid, systolic_bp, etc.) according to their names in the query definition.

Provided query parameters SHOULD NOT be prefixed with $ sign. Instead, the server will (whenever necessary) add the prefix or format queries as valid AQL queries.

As an example, for the following AQL query

SELECT c/name/value FROM COMPOSITION c WHERE c/uid/value = $uid

named as 'myQuery', the client can supply the uid as a query parameter:

GET https://openEHRSys.example.com/v1/query/myQuery?uid=90910cf0-66a0-4382-b1f8-c0f27e81b42d::openEHRSys.example.com::1

As another example, the request

GET https://openEHRSys.example.com/v1/query/com.vendor::compositions?temperature_from=36&temperature_unit=Cel

will pass query parameters temperature_from and temperature_unit to the underlying AQL query named com.vendor::compositions.

See AQL-parameters specification for more details.

Response details

RESULT_SET response

Below is a synthesized RESULT_SET response with all attributes.

object (ResultSetMetadata)

RESULT_SET metadata.

name
string (QueryName)

The (fully qualified) name of the query (when is registered as a stored query), in a format of [{namespace}::]{query-name}. The namespace prefix is optional, and when used it should be in a form of a reverse domain name.

q
string (AQL)

The given AQL query.

Array of objects (RESULT_SET_COLUMN)

A set of AQL column specifications, defined in the given AQL.

rows
required
Array of any (RESULT_SET_ROW) [ items ]

An ordered set of RESULT_SET rows.

{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Metadata

RESULT_SET metadata comprise a set of optional (implementation dependent) attributes, useful for debugging.

_href
string <uri>

URL of the executed query (only for GET endpoint).

_type
string

The type of the serialized result object.

_schema_version
string

The version of the specification defining the serialized object.

_created
string <date-time>

Result creation time (in the extended ISO 8601 format).

_generator
string

Some identifier of the application that generated the result, useful for debugging.

_executed_aql
string

The actual AQL query that was executed by the server, after replacing the query parameters. This attribute is not mandatory, but is useful for debugging.

property name*
additional property
any
{
  • "_type": "RESULTSET",
  • "_schema_version": "1.0.0",
  • "_created": "2017-08-19T00:25:47.568+02:00",
  • "_generator": "openEHRSys.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)",
  • "_executed_aql": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= 50"
}

Execute Query

Execution of AQL queries. Actions upon resources of this group are also formally described in the I_QUERY_SERVICE Abstract Service Model interface.

Execute ad-hoc AQL

Execute a given ad-hoc AQL query, supplied by q parameter, fetching fetch numbers of rows from offset and passing query_parameters to the underlying query engine.

See also details on usage of query parameters.

query Parameters
q
required
string (AQL)
Example: q=SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp

The AQL query to be executed.

ehr_id
string
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398

An optional parameter to execute the query within an EHR context.

offset
integer <int32> (Offset)
Default: 0
Example: offset=10

The row number in result-set to start result-set from (0-based), default is 0.

fetch
integer <int32> (Fetch)
Example: fetch=10

Number of rows to fetch (the default depends on the implementation).

object (QueryParameters)
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398&systolic_bp=140

Query parameters (can appear multiple times).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Execute ad-hoc AQL (POST)

Execute a given ad-hoc AQL query, supplied by q attribute, fetching fetch numbers of rows from offset and passing query_parameters to the underlying query engine.

See also details on usage of query parameters.

Request Body schema: application/json
required
q
required
string (AQL)

The given AQL query.

offset
integer <int32> (Offset)
Default: 0

The row number in result-set to start result-set from (0-based), default is 0.

fetch
integer <int32> (Fetch)

Number of rows to fetch (the default depends on the implementation).

object (QueryParameters)

A set of query parameters.

Responses

Request samples

Content type
application/json
{
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "offset": 10,
  • "fetch": 10,
  • "query_parameters": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Execute stored AQL

Execute a stored query, identified by the supplied qualified_query_name (at latest version), fetching fetch numbers of rows from offset and passing query_parameters to the underlying query engine.

See also details on usage of query parameters.

Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

path Parameters
qualified_query_name
required
string (QueryName)
Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

query Parameters
ehr_id
string
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398

An optional parameter to execute the query within an EHR context.

offset
integer <int32> (Offset)
Default: 0
Example: offset=10

The row number in result-set to start result-set from (0-based), default is 0.

fetch
integer <int32> (Fetch)
Example: fetch=10

Number of rows to fetch (the default depends on the implementation).

object (QueryParameters)
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398&systolic_bp=140

Query parameters (can appear multiple times).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Execute stored AQL (POST)

Execute a stored query, identified by the supplied qualified_query_name (at latest version).

See also details on usage of query parameters.

Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

path Parameters
qualified_query_name
required
string (QueryName)
Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

Request Body schema: application/json
required

Specifications for a stored AQL query execution.

offset
required
integer <int32> (Offset)
Default: 0

The row number in result-set to start result-set from (0-based), default is 0.

fetch
required
integer <int32> (Fetch)

Number of rows to fetch (the default depends on the implementation).

required
object (QueryParameters)

A set of query parameters.

Responses

Request samples

Content type
application/json
{
  • "offset": 10,
  • "fetch": 10,
  • "query_parameters": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Execute stored AQL version

Execute a stored query, identified by the supplied qualified_query_name (at specified version), fetching fetch numbers of rows from offset and passing query_parameters to the underlying query engine.

See also details on usage of query parameters.

Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

path Parameters
qualified_query_name
required
string (QueryName)
Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

version
required
string
Example: 1.0

A SEMVER version number. This can be a an exact version (e.g. 1.7.1), or a pattern as partial prefix, in a form of {major} or {major}.{minor} (e.g. 1 or 1.0), in which case the highest (latest) version matching the prefix will be considered.

query Parameters
ehr_id
string
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398

An optional parameter to execute the query within an EHR context.

offset
integer <int32> (Offset)
Default: 0
Example: offset=10

The row number in result-set to start result-set from (0-based), default is 0.

fetch
integer <int32> (Fetch)
Example: fetch=10

Number of rows to fetch (the default depends on the implementation).

object (QueryParameters)
Example: ehr_id=7d44b88c-4199-4bad-97dc-d78268e01398&systolic_bp=140

Query parameters (can appear multiple times).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}

Execute stored AQL version (POST)

Execute a stored query, identified by the supplied qualified_query_name (at specified version).

See also details on usage of query parameters.

Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.

path Parameters
qualified_query_name
required
string (QueryName)
Example: org.openehr::compositions

The (fully qualified) name of the query to be executed, in a format of [{namespace}::]{query-name}.

version
required
string
Example: 1.0

A SEMVER version number. This can be a an exact version (e.g. 1.7.1), or a pattern as partial prefix, in a form of {major} or {major}.{minor} (e.g. 1 or 1.0), in which case the highest (latest) version matching the prefix will be considered.

Request Body schema: application/json
required

Specifications for a stored AQL query execution.

offset
required
integer <int32> (Offset)
Default: 0

The row number in result-set to start result-set from (0-based), default is 0.

fetch
required
integer <int32> (Fetch)

Number of rows to fetch (the default depends on the implementation).

required
object (QueryParameters)

A set of query parameters.

Responses

Request samples

Content type
application/json
{
  • "offset": 10,
  • "fetch": 10,
  • "query_parameters": {
    }
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "name": "org.openehr::compositions",
  • "q": "SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp",
  • "columns": [
    ],
  • "rows": [
    ]
}