Introducing Query Parameters

In this lesson, we’ll learn how to make an AQL query reusable by using query parameters.

Previously, you might have hardcoded an archetype like openEHR-EHR-OBSERVATION.pulse.v2. That works, but it makes the query too specific.

What are query parameters?

Query parameters let you abstract parts of the query (like the archetype) so the same AQL can be reused for other archetypes just by changing the parameter value.

For example before the use of query parameters, your AQL looked like this:

SELECT o FROM EHR e CONTAINS OBSERVATION o[openEHR-EHR-OBSERVATION.pulse.v2]

Where it only works for that one archetype.

But when you use query parameters, your AQL becomes:

SELECT o FROM EHR e CONTAINS OBSERVATION o[$archetype]

And instead of hardcoding the archetype in the query, you pass it as a parameter as shown below:

{
 "q": "SELECT o from OBSERVATION o [$archetype]",
 "query_parameters": {
   "archetype": "openEHR-EHR-OBSERVATION.pulse.v2"
 }
}

With query parameters, you keep the same AQL and just change the archetype value in query_parameters. This makes the query easy to reuse and share.

Mini-exercise

In the Postman collection, select the query folder. Inside it, you’ll find the Ad-hoc query request (a POST API request):

POST {{openehrBaseUrl}}/query/aql

Now follow these steps to parameterize the archetype in your AQL:

1. Start with an AQL that currently uses a hardcoded archetype, for example: openEHR-EHR-OBSERVATION.pulse.v2
2. Replace the hardcoded archetype with a parameter reference (example: $archetype).
3. Add a query_parameters object and set the archetype value like this:

"query_parameters": {
  "archetype": "openEHR-EHR-OBSERVATION.pulse.v2"
}

Click Send and you should get back a 200 OK request, and you should get back the observations.

Lesson summary

In this lesson, you learned how to make AQL more reusable by using query parameters instead of hardcoding values. By replacing fixed values with a parameter reference like ‘$parameterName’, you can abstract those details out of the query itself.