AQL Syntax Description

An archetype path is the path referring to any node within an archetype. The following is an ADL workbench screen shot of apgar observation node map. The table below shows some examples.

Another type of openEHR path is the path pointing to an attribute of openEHR Reference Model classes. The examples shown below uses the attributes from the COMPOSITION class.

A parameter always starts with a dollar sign $ followed by the parameter name, e.g. $ehrUid. The parameter name can consist of letters, digits and underscores. It cannot have spaces and it cannot be an AQL reserved word.

A parameter can be used for any criteria values within an AQL statement, e.g.:

Parameters are needed when the same AQL query statement is used with different criteria values. This AQL example is to return all abnormal blood pressure values for a single specific EHR. This query has a parameter $ehrUid. This parameter will be substituted by a specific EHR.ehr_id value at run time. Consequently, this query can be reused for all EHRs either within an EHR system or by other EHR systems (assuming these EHR systems support AQL).

AQL query parameters can be resolved at application level, or EHR system level. It depends on what the query parameters are used for and the design/implementation of the system or components. Query parameters would be normally resolved outside of a query engine.

If a query needs to be reusable across different EHR systems, any query parameters normally need to be registered in these EHR systems so that they can be resolved with real values from each environment. A typical example of this type of query parameter is $ehrUid. If the query is only used within an application, then the query parameters would be resolved by the application, such as the parameter of healthcare facility identifier or template identifier.

There are no specific guidelines on how to resolve query parameters. Generally speaking, a parameter name is used as a key (or a key is associated with a parameter name) and the key needs to be unique within the boundary where the parameters are resolved. The EHR system or application needs to have the API functions to get the real value with a given parameter name or key.

Standard predicates always have a left operand, operator and right operand, e.g. [ehr_id/value='123456'].

An archetype predicate is a shortcut of a standard predicate, i.e. the predicate does not have the left operand and operator. It only has an archetype id, e.g. [openEHR-EHR-COMPOSITION.encounter.v1]. The archetype predicate is a specific type of query criterion indicating which archetype instances are relevant to this query. It is used to scope the data source from which the query result data is to be retrieved. Therefore, an archetype predicate is only used within an AQL FROM clause, for example,

This predicates could also be written as Standard predicates:

This equivalence could be used by implementers of AQL to transform predicates into their standard form, as a canonical representation of the query, which can simplified its processing, validation, evaluation and transformation into specific database query languages.

A node predicate is also a shortcut of a standard predicate. It has the following forms:

A node predicate defines criteria on fine-grained data.

The table below shows the supported AQL comparison operators, meaning and example.

The matches binary operator is used in the WHERE clause. The left operand is an AQL identified path. The right operand is enclosed within braces ('{}'), and may take the following forms:

In AQL, an identified path is the association of a variable reference (the identifier; see above) and an archetype path and/or predicate. Except for the FROM clause, an identified path may appear in any clause of an AQL statement. For example, it can be used to indicate the data to be returned in a SELECT clause, or the data item on which query criteria are applied in a WHERE clause.

An AQL identified path can take any of the following forms:

Integers are represented as numeric literals, such as 1, 2, 365. Commas or periods for breaking long numbers are not allowed. Hexadecimal representation is not supported.

Real numbers are the decimal literals that include a decimal point, such as 3.1415926. Commas or periods for breaking long numbers are not allowed.

Boolean values are indicated using the case-insensitive literals true or false.

All strings are enclosed in double or single quotes. Line breaks are not supported.

These types are treated as strings and should comply with the rules for string quoting. The format of the date, time and datetime types should comply with the ISO 8601 Date and Time format specification, which allow the basic or extended formats to be used. In the openEHR specification it is recommended to use the extended format for dates, times and datetimes. Complete or partial values are allowed.

Examples are as below:

AQL structure was briefly introduced in [_aql_example]. This section describes the syntax in more formal detail. An AQL query may include the following clauses which must occur in the order shown.

An AQL statement must at least contain the SELECT and FROM clauses.

The FROM clause is used to specify the subset of all the data available in a repository, that will be available for the rest of the clauses to filter and return specific data (WHERE, SELECT, etc). The data available should be defined by an information model, known here as the Reference Model (RM), that supports the use of archetype- and template-based constraint models, as described in the openEHR Architecture Overview and the Archetype Technology Overview.

All the classes referenced by the FROM clause should be defined by the RM. For instance, if the Reference Model is the openEHR Reference Model, the FROM clause should only include classes like EHR, COMPOSITION, OBSERVATION, EVALUATION, and so on.

Then, the expressions in the WHERE clause will filter data, but only from the subset defined by the FROM clause. And in the SELECT clause, a final projection is applied, selecting only the matched data that should be retrieved in the query result. In addition to the filtering done in the WHERE clause, the class expressions could hold predicates that also allow filtering data.

In summary:

An AQL WHERE clause is used to represent further criteria applied to the data items within the objects declared in the FROM clause. A WHERE clause expresses the query criteria that cannot be represented in other AQL clauses, such as criteria on archetype id, composition committal date/time, and the criteria on in which order the returned results should be listed.

A SELECT clause specifies what data is to be retrieved by the AQL query. The data can be any types from openEHR RM and any primitive data types. In addition, the SELECT clause uses TOP to indicate the number of result sets that should be returned and name alias to rename the retrieved data.

The SELECT syntax always starts with the keyword SELECT, followed by TOP (optional), and identified path(s) or plain variable name(s) defined in the FROM clause. Each variable name or identified path may have a name alias renaming the associated data.

Where a variable name is specified, the full object of the type associated with the variable is retrieved, such as a COMPOSITION, OBSERVATION etc. Where an identified path is specified, the data item(s) having that archetype path are returned. Multiple identifiers or identified paths are separated using a comma.

Some examples are shown below.

Example 1: retrieve all Compositions' name value, context start time and composer name from a specific EHR.

Example 2: Retrieve all Composition objects of a specific EHR.

The ORDER BY clause is used to sort the returned results. The keyword ORDER BY is followed by an identified path and the keyword DESC, DESCENDING, ASCE, or ASCENDING, e.g.