Query scope
Deephaven query strings let you express complex queries in a concise syntax. These query strings can implement formulas or filters that use Groovy variables. For example, the query string in this update uses the variable a from Groovy. Variables make queries easier to understand and reuse.
The query scope is the set of user-defined variables and functions that query strings can refer to. When Deephaven evaluates Y = a * X, it looks up a in the query scope. This guide walks you through how Deephaven resolves Groovy variables and functions in query strings. To learn how to use each kind of variable and function, see Groovy variables in query strings and Groovy closures in queries.
Note
Variable names and function names are case-sensitive.
Query scope in Groovy
In Groovy, query strings resolve variables through the QueryScope. In a Groovy session, the query scope is the script session's variable binding: the set of named variables the session holds. The following rules decide which variables the binding contains:
- Variables assigned at the top level of a Groovy script without
defor a type (for example,a = 2) are in the query scope without a call toaddParam. - Variables declared with
defor a type, even at the top level (for example,def a = 2orint a = 2), and variables local to a method or closure are not in the query scope. Add them withQueryScope.addParam(name, value). addParamwrites into the same binding as top-level variables. It overwrites any existing variable with that name, and the variable stays available after the method or closure returns.
When a query string uses a name, the engine resolves it in this order:
- A column, a column array such as
A_, or a built-in variable (i,ii,k). - A variable in the binding.
- A built-in constant. A variable named
MINUTEtherefore hides the built-inMINUTE.
A variable name that isn't found in any of these places fails with a Cannot find variable or class error.
Function calls resolve the other way around: a built-in function wins over a closure with the same name when one of its overloads accepts the arguments.
Deephaven's own built-in functions, constants, and variables are always available and don't come from the query scope.
Examples
Script-level scope
In the following example, globalVar is assigned at the top level without def, so the query string can use it directly.
A top-level variable declared with def is not in the binding, so a query string can't use it. The following query fails with a Cannot find variable or class factor error:
Assign the variable without def instead:
Script-level functions
A closure assigned to a top-level variable is in the binding, so a query string can call it. A script method, such as def myFunction(int a) { ... }, is not in the binding, and a query string can't call it. Assign a closure to a variable instead.
In the following example, the query string calls the top-level closure myFunction.
The (int) cast is needed because a closure called from a query string returns Object. For details, see Groovy closures in queries.
Local (function) scope
To use a variable defined in a method, closure, or any other local scope in a query string, you must add it to the query scope with QueryScope.addParam:
In the following example, processWithLocalVar defines a local variable, multiplier, and adds it to the query scope with QueryScope.addParam before the query string uses it.
A variable from an enclosing method or closure needs the same call. A closure can capture it, but the query string can't see it until you add it with QueryScope.addParam.
Columns take precedence over variables
A column with the same name as a variable wins. In the following example, a in the formula B = a + 1 refers to the column a, not the variable a, so B is 1, 3, and 5 rather than 101.
Encapsulated query logic in closures
Wrapping query logic in a closure is a common way to keep code clean and readable. Building on Local (function) scope, you can wrap a whole query in a closure and pass the values that change as parameters. Add each parameter to the query scope before the query string uses it.
In the following example, we want to know how much sales tax we'll pay in several states for a given purchase amount. The computeTax closure adds its salesPrice parameter to the query scope, because a closure parameter is not a top-level variable. Calling computeTax with a different amount changes the result without changing the query.
Built-in functions, constants, and variables
Deephaven provides built-in functions, constants, and variables that query strings can use without adding them to the query scope. The engine imports the functions and constants into the query language and recognizes the variables i, ii, and k by name.
The following query uses the built-in function sin, the built-in constant MINUTE, and the built-in variables i and ii. Some refreshing tables restrict the built-in variables. For details, see Built-in query language variables.
Related documentation
- Deephaven's table types
- Arrays
- Query language built-in constants
- Built-in query language variables
- Built-in query language functions
- Create static tables
- An overview of query strings
- Groovy variables in query strings
- Groovy closures in queries
- Formulas
- Filters
- Query scope reference
emptyTabledoubleColintColnewTablestringColupdateQueryScopeJavadoc