Turning clinical data into insight should start with a question, not a query. Text2AQL makes that possible by translating natural-language clinical questions into valid, executable AQL for openEHR data, shifting the focus from writing complex queries to understanding clinical meaning.
openEHR has become a prominent standard for long-term healthcare data persistence and interoperability, facilitating structured clinical data management. Retrieving data from openEHR repositories requires the use of Archetype Query Language (AQL), a powerful yet complex querying language. Mastery of AQL involves understanding its syntax, grammar, and the underlying openEHR clinical models, which creates significant usability challenges. Typically, AQL queries are manually crafted, a process demanding substantial time, expertise and familiarity with clinical archetypes. Although semi-automated approaches with autocomplete functionality exist, they only partially alleviate the complexities associated with query formulation. Text2AQL addresses this gap.
From clinical intent to executable AQL
AQL is expressive and powerful, reflecting the richness of openEHR’s clinical models through archetypes, templates, and strict containment semantics. This expressiveness is exactly what makes openEHR valuable, but it also raises the bar for correctly querying data.
Users often spend time constructing, refining, and debugging queries before they can be executed. Small mistakes in paths, containment, or time constraints can render a query unsuitable. As a result, access to clinical data is frequently limited to a group of AQL experts, while clinicians and analysts wait for support.
Text2AQL shifts this dynamic. Instead of focusing on how to write AQL, users can focus on what they want to know.
A question such as “Show the average systolic blood pressure for patients in the last year” is translated into an AQL query that:
- selects the correct openEHR archetypes,
- references valid element paths,
- applies appropriate time constraints,
- follows AQL grammar and containment rules.
The result is an executable query, ready to run without manual correction.
Clinicians routinely seek answers to clinical questions like “How long has the patient X been taking Levaquin?” or “Does patient X have an allergy to penicillin?” By enabling users to effortlessly input such queries in everyday language, we aim to significantly accelerate clinical data retrieval, democratizing data access for clinicians, healthcare professionals and even patients.
Text2AQL inside Better Studio
Text2AQL is the AI service that powers the Query Assistant feature within the AQL Builder, one of the building blocks of Better Studio. There, users can generate executable AQL from natural language questions, receive explanations of what a query does and how it is structured, analyse and improve existing AQL queries, identify and fix errors, and refine queries by adding, modifying, or removing parts.
This creates a guided workflow that combines AI-assistedassisted generation with validation, transparency, and user control, all in the same environment where modelling, development, and analysis already happen.
Why general-purpose AI struggles with AQL
Translating natural language into queries is not a new problem. “Text-to-SQL” has been explored for years and remains challenging even for relational databases. The challenge becomes significantly harder with openEHR and AQL.
Although AQL may look similar to SQL, it is fundamentally different. It does not operate on tables and columns, but on archetypes, templates, and deeply nested clinical structures with strict containment rules.
To learn more about AQL, explore our new course on Hive, our learning platform.
General purpose language models are typically trained on large volumes of SQLpurpose language models are typically trained on large volumes of SQLlikelike patterns. When applied to AQL, they often default to SQL assumptions, producing queries that look plausible but fail at execution.
Common failure patterns include:
- using SELECT *, which is invalid in AQL,
- treating archetypes as database tables,
- ignoring containment semantics,
- mishandling time constraints,
- checking for missing elements incorrectly,
- inventing element paths or archetype codes that do not exist.
In healthcare, queries that fail at execution are more than an inconvenience. They break trust and cannot be safely reused in analytical or clinical workflows.
A controlled approach to reliable AQL
Text2AQL was designed specifically to address these limitations. Instead of attempting to solve everything in a single generation step, it follows a structured pipeline that reflects how AQL queries are actually built.
The process includes:
- Extraction of clinical concepts – identifying key clinical concepts from the user’s question.
- Archetype and path discovery – mapping those concepts to real openEHR archetypes and element paths.
- Intermediate representation – defining the structure of the query (SELECT, FROM, WHERE, containment).
- AQL generation – producing the final query according to AQL grammar and rules.
- AQL validation – checking syntax, archetypes, paths, and common error patterns before execution.
Validation is treated as a first-class step. In practice, a query either runs or it does not, and only executable queries are useful in production healthcare environments.
This approach was first described in research presented at EHRCON25 and continues to evolve as part of Better Studio’s ongoing development.
Reliability that matters in practice
In internal evaluations using nearly 1,300 real-worldworld AQL prompts, the difference between generic AI models and Text2AQL is clear.
While general purpose models frequently produce queries that fail at execution, Text2AQL delivers syntactically valid, executable AQL in almost all cases (99.8%). This reliability establishes a foundation on which semantic optimisation and refinement can meaningfully build.
With Better Studio, Text2AQL also shows a significant improvement in semantic accuracy, driven by more reliable archetype selection, validated element paths, and a deeper understanding of containment logic.
Who benefits from Text2AQL
Text2AQL supports a range of users working with openEHR data:
- clinicians who need answers without learning AQL,
- analysts working with openEHR repositories,
- solution engineers building dashboards and analytics,
- developers implementing business logic, data views, and ETL pipelines,
- organisations aiming to broaden safe access to clinical data.
By lowering the technical barrier while preserving structure, transparency, and control, Text2AQL helps teams work with openEHR data more confidently and efficiently.
Thoughtful AI, embedded in real workflows
Text2AQL reflects the approach by Better towards AI in healthcare: purposeful, explainable, and grounded in real world use. It does not replace clinical or technical world use. It does not replace clinical or technical expertise, it supports it, making complex systems easier to work with without compromising safety or standards.
Available directly in Better Studio through the Query Assistant, Text2AQL bridges the gap between clinical questions and structured data, helping teams focus on insight and care, rather than the mechanics of query languages.
If you haven’t tried it yet, we encourage you to test it out and see how it performs on your own real-world use cases.
