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.