Refining queries with parameters
This content progresses from beginner to advanced user knowledge.
A hardcoded query always returns the same data regardless of context. In practice, you almost always need to filter results dynamically, for example to return data for the current patient, or only records within a specific date range. Query parameters make this possible.
What query parameters are and when to use them
A query parameter is a named placeholder in your AQL query that is filled with a real value at runtime. Instead of hardcoding a patient identifier, you define a parameter and pass the value in when the query runs — whether from the parameter input section in the AQL builder, or programmatically from a form or application.
Parameters are appropriate when:
- The query needs to filter by a value that changes per user, session, or patient context.
- You want a single query or view to serve multiple scenarios with different filter conditions.
- You are building a view that a data connector will call with form-supplied values.
Adding parameters to a query
Parameters use colon prefix syntax — a : followed by a descriptive name:
SELECT
o/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic,
o/data[at0001]/events[at0006]/data[at0003]/items[at0005]/value/magnitude AS diastolic
FROM EHR e
CONTAINS COMPOSITION c
CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.blood_pressure.v2]
WHERE e/ehr_id/value = :ehrId
AND c/context/start_time/value >= :startDate
In this example, :ehrId and :startDate are parameters. Use descriptive names that make the query readable without additional context. You can add as many parameters as a query requires. Each becomes a field in the parameter input section and a variable in the data connector configuration.
Parameter names are case-sensitive and must be unique within the query.
Testing parameters in the AQL builder interface
When the AQL builder detects parameters in your query, it automatically displays a parameter input section on the right side of the interface. Enter a test value for each parameter, then select Execute query to send the query to the EHR server.
Enter realistic values! For example: The EHR ID of a patient in your test environment and a date range you know will return records. Verify that the filter conditions work correctly before saving the query as a view.
Parameterised queries execute against the live EHR server connected to your project. Use a test or staging environment when building and refining queries to avoid affecting production data.
Parameter notation: : vs $
Both :param and $param notation appear in AQL documentation and external tooling. The openEHR specification defines $ as the standard notation, but Better Studio introduced an improved AQL implementation prior to the finalisation of the specification, where : is the default. If you prefer to use $ notation, you can enable it on the Better Platform. Once enabled, the AQL builder recognises both : and $ as parameter markers.
Frequently asked questions (FAQs)
Can I use the same parameter name more than once in a query?
Yes. If the same parameter name appears in multiple conditions, the AQL builder prompts for its value once and applies it everywhere it appears in the query.
What data types can a parameter accept?
Parameters accept any value valid for the condition they appear in: strings, numbers, dates, and datetimes. Type validation happens on the EHR server when the query runs, not in the parameter input panel.
What is the correct format for a date parameter?
openEHR uses ISO 8601 format. An example is 2026-01-15 for a date or 2026-01-15T09:30:00Z for a datetime with timezone. Use this format in the parameter input panel when testing.
My query works with a hardcoded value but fails with a parameter. What should I check?
First, confirm the parameter name in the query exactly matches what you are entering in the input panel — names are case-sensitive. Second, check that the value format matches the data type expected by the WHERE condition — for example, ISO 8601 for dates, not a localised display format.
Can a parameter be optional?
AQL does not natively support optional parameters. If a parameter is present in the query but receives no value, the query fails. If you need conditional filtering, create separate queries for different scenarios or use a JavaScript view to build the condition dynamically. See JavaScript views.
How do I pass a parameter value from a form to a view at runtime?
In the data connector configuration in Form builder, map the form field or session variable to the view's parameter. The value flows automatically when the data connector is triggered. See Working with views and Connecting data.