Going over the section of 3.5 of the spec, based on Pablo’s comments re the need to clarify how quotes are to be applied, I realised that we need to do more than that.
Reading Section 3.5.3 (where and how parameters are resolved), I can see that the spec is implying that some parameters can be recognised by the backends by default and their value would be provided during query execution. One such example is ehrUid.
I suggest we remove this particular feature of parameters. The example of an ehrUID is particularly problematic: how would a server know which ehr uid to set during query execution? This could only work via use of a mechanism such as a session?
In the past, Ocean’s CDR had support for sessions. We’d open a session, then use the session token so that the CDR could set various data during execution. Without such a session/token mechanism, it is impossible for a CDR to know what ehrUid parameter should be set to. We walked away from this approach for various reasons, mainly the same reasons for server side computing moving to more stateless designs.
If we keep this definition of parameters, then we’re implying the need for use of a session mechanism, which is an implementation detail, which we’d rather not push into specs. If we don’t suggest sessions, then we’re specifying a vague behaviour, which would require an approach that we came to conclude to be hard to scale. Other vendors are welcome to share their experiences of course, this is Ocean’s.
I would be keen to hear use cases other vendors may have for having a list of pre-allocated server side parameter references/names. Unless we have some convincing arguments, we’d better remove this particular aspect of parameters.
Another reason for doing so is the REST API for Aql assuming that parameter values are provided along with the execution request for AQL queries. Whether or not the query is stored on the server side doesn’t matter. This use of parameters is similar to parameterised SQL queries used in JDBC, ADO.NET and other data access layers. This is indeed the most common way of using parameters in Ocean. Again, other vendors are most welcome to share their experiences and used cases.
Based on the above, and Pablo’s point about clarifying the quoting behaviour of parameters, I’d suggest the following content for section 3.5 (Parameters). I’ll write this in more detail if I can get some high level feedback
Parameters can be used at any place in an AQL query where value of a primitive RM type is expressed. The primitive types (base/org/openehr/base/foundation_types/primitive_types) for which a parameter can be used are:
Boolean Character Double Integer Integer64 Octet Real String Uri
When a parameter is used to refer to a value of Character, String or an Uri type, values provided to the parameter are automatically enclosed in single quotes by the AQL implementation. Parameter’s used for values of remaining basic types are replaced without modification in the query text.
The actual values of parameters are provided to the execution context of AQL query using the particular AQL implementation’s APIs. Users of AQL’s should consult vendor documentation to find out how to pass actual values of parameters to a query. For example, openEHR REST specification provides one such API definition for invoking AQL queries, supported by vendors who implement the REST API.
The use of parameters in AQL queries allow input sanitation (against malicious input values similar to SQL injection attacks), caching (when same query is invoked multiple times with same parameter values) and ease of solution development (reusing a stored query definition by passing only parameters.)