Editor

• Sebastian Iancu, Architect, Code24, Netherlands

Contributors

This specification benefited from wide formal and informal input from the openEHR and wider health informatics community. The openEHR Foundation would like to recognise the following people for their contributions.

• Birger Haarbrandt, MSc, Peter L. Reichertz Institut for Medical Informatics (PLRI), Germany
• Bjørn Næss, DIPS, Norway
• Bostjan Lah, Senior Architect, Better, Slovenia
• Erik Sundvall, Information Architect at Karolinska University Hospital, Sweden
• Heath Frankel, Ocean Informatics, Australia
• Ian McNicoll MD, FreshEHR, UK
• Jake Smolka, Software Engineer, Better, Slovenia
• Matija Polajnar, PhD, Software Engineer, Better, Slovenia
• Pablo Pazos Gutierrez, Senior engineer, CaboLabs, Uruguay
• Rong Chen MD, PhD, Cambio Healthcare Systems, Sweden
• Sebastian Iancu, Architect, Code24, Netherlands
• Seref Arikan, MEcon, Ocean Informatics UK, Centre for Health Informatics and Multi-professional Education (CHIME) UK
• Thomas Beale, Ars Semantica UK, openEHR Foundation Management Board

Trademarks

• 'openEHR' is a trademark of the openEHR Foundation
• 'OpenAPI' is a trademark of the The Linux Foundation

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.

Related Documents

Prerequisite documents for reading this document include:

• The Archetype Query Language(AQL)

Related documents include:

• The openEHR Architecture Overview
• The openEHR Global Class Index
• The XML-Schemas (XSD)
• The JSON-Schemas and Simplified Data Template (SDT)
• The openEHR Platform Abstract Service Model

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.

Feedback

Feedback may be provided on the Implementation Technology Specifications forum.

Issues may be raised on the specifications Problem Report tracker.

To see changes made due to previously reported issues, see the ITS component Change Request tracker.

Conformance

tbd.

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 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 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.

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.

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.

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"
    }
}

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.

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

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.

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.

Below is a synthesized RESULT_SET response with all attributes.

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

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

The following resources are formally specified in the Archetype Query Language (AQL) and in the Query Service.

The AdhocQueryExecute resource:

The stored-query execute, known as the Query resource:

This resource is formally specified in the Service Model as Query Result.