Using the Scenario Service to manage parameterized queries
There are several ways to manage (create/edit/remove) parameterizations:
The Scenario Service is also used to read and manage instances of DataViews and MemoryStore.
To these tools, a query will appear with the fully qualified name declared in the .qry file prefixed with QRY_ to highlight that the entity being viewed is a query. For parameterized queries, instances can be created, edited or deleted. For unparameterized queries, a single instance will appear as soon as the query is injected. This instance cannot be edited nor deleted, nor new instances created.
When there is a request to create a parameterization, the Scenario Service tries to validate the supplied parameter values. If the values are valid, the result is as if a query with those values had just been injected.
End users have the ability to define conditions on parameter values when setting them in dashboards. Parameter values can be modified only by the Scenario Service. Updates by the Scenario Service do not occur atomically across all contexts if the query is running in multiple contexts. Consequently, it is possible to observe the effects of the old parameter values interleaved with the effects of the new parameter values. For example, consider a query that has a pattern such as the following:
find A as a -> wait(paramValue) as t
The wait period will be based on the value the parameter had when the wait period started. If the parameter value is edited after the A event enters the partition the wait still fires according to the old value. Such transitions are typically short. The actual time required depends on various factors such as machine load and memory.
Some important differences between parameterized queries and other strategies include:
Parameterized queries have input variables but not output variables. DataViews and MemoryStore have both input variables and output variables. All queries have an empty list of output variables.
Requests to create or update a parameterization with values that are invalid will be denied. Invalid values are values that would cause
wait,
within or
retain clauses to evaluate to less than or equal to zero, or would cause them to fail to evaluate, for example, by causing a runtime exception to be thrown.
For example, consider the following query:
query ParameterizationExample {
parameters {
integer intParam;
integer floatParam;
}
inputs {
A() key id retain (10/intParam);
B() key id within (5.0 - floatParam);
}
find A as a -> B as b -> wait(-1.0 * floatParam)
where (a.intField/intParam > 0) {
log "Found match" at INFO;
}
Suppose that there is a request to create a parameterization of this query. The request indicates that intParam is equal to 0 and floatParam is equal to 10.0. If the parameterization were created then every expression that contains a parameter value would immediately throw an exception or be invalid. In the inputs block, evaluation of the retain expression would result in a divide-by-zero exception. The within expression would evaluate to -5.0, which is not valid. Similarly, upon evaluating the elements in the find block the wait expression would be a negative value and the where clause would also result in a divide-by-zero exception. Since a parameterization such as this would lead to either invalid expressions or exceptions being thrown, these values are not allowed. If you try to pass disallowed values to the Scenario Service createInstance() method then the Scenario Service returns null. Similarly, if you try to pass invalid values to the Scenario Service editInstance() method, then the Scenario Service returns false, which indicates an error.