aql-authoring

AQL Authoring

The inline syntax below is a quick crib. The aql/syntax guide loaded in Step 1 is authoritative — if they ever disagree, follow the guide.

Step 1: Load Guides (MANDATORY)

Before writing or reviewing any AQL query, load the authoritative guides:

guide_get("openehr://guides/aql/principles")
guide_get("openehr://guides/aql/syntax")
guide_get("openehr://guides/aql/idioms-cheatsheet")

Consult worked examples (when applicable)

When the user asks for a query to adapt, or when the clinical question matches a common pattern (cohort selection, pagination with total count, time-window filtering, cross-composition joins, terminology value-set matching, "latest per EHR", ISM-state filtering), try examples_search(kind="aql") before drafting. The curated AQL examples are under openehr://examples/aql/{name} and include pattern metadata and related-spec links — reuse and adapt rather than invent. Skip this step if the question is clearly novel or the user already provided the skeleton.

Step 2: Understand the Data Model

AQL queries operate on archetypes. Before writing a query:

1. State assumptions about deployed templates/archetypes — verify path endpoints and RM types against the deployed template, not display labels; when a deployed template is named, fetch it (ckm_template_search → ckm_template_get) rather than guessing paths
2. Identify which archetypes contain the required data (ckm_archetype_search when the archetype id is not yet known)
3. Load the archetype to understand its path structure:

   ckm_archetype_get("<archetype-id>")
   

4. Use type_specification_get to clarify RM type details when needed

Step 3: AQL Syntax

Basic Structure

SELECT <paths>
FROM EHR e
  CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.<name>.v1]
    CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.<name>.v1]
WHERE <conditions>
ORDER BY <paths>

Containment

Define the archetype hierarchy using CONTAINS:

FROM EHR e
  CONTAINS COMPOSITION c
    CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v2]