Query scope
Deephaven query strings let you express complex queries in a concise syntax. These query strings can implement formulas or filters that use Python variables. For example, the query string in this update uses the variable a from Python. Variables make queries easier to understand and reuse.
The query scope is the set of user-defined variables and functions that a query string 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 Python variables and Python functions in query strings. To learn how to use each kind of variable and function, see Python variables in query strings and Python functions in query strings.
Note
Variable names and function names are case-sensitive.
Query scope in Python
When the Deephaven engine compiles a query string, it must resolve every variable and function the string uses. Python's LEGB rule looks up a name in the local, enclosing, global, and built-in scopes, in that order. The Deephaven query scope follows similar rules, with some important distinctions.
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 local (function) scope.
- A variable in the global (module) scope.
- 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 Python function with the same name when one of its overloads accepts the arguments.
Deephaven does not search the enclosing (nonlocal) scope directly. A query string can use an enclosing function's variable only if the inner function's own code also refers to it, for example by declaring it nonlocal.
Deephaven also doesn't search Python's built-in namespace. To use a Python built-in such as sorted in a query string, assign it to a variable in the local or global scope.
Some query strings can't use a function's local variables at all. They see only the global scope of the main script. The following query strings work this way:
- Formulas passed to the
with_update_viewmethod of a rollup table. - Filters and formulas in node operations. You record these with the recorder that
node_operation_recorderreturns, then apply them withwith_node_operations.
Deephaven's own built-in functions, constants, and variables are always available and don't come from the query scope.
Examples
Local (function) scope
Variables defined in the local scope of a function or lambda expression are usable only from within that function or lambda. In the following example, use_local_and_global_vars builds a table from a local variable and a global variable, then returns it to the outermost scope as result.
The local scope is the scope of the function that calls the table operation itself. If a helper function calls update for you, the query string sees the helper's local variables, not the caller's.
Global (module) scope
Variables and functions defined at the outermost scope of a script are usable from any query string in that script unless a local variable with the same name takes precedence. The following query creates two variables and a function in the outermost scope, then creates tables that use them.
Enclosing (nonlocal) scope
The enclosing scope is a special case. Query strings do not see variables in an enclosing function's scope unless the inner function's own code refers to them. The following example declares the variable nonlocal so that the inner function refers to it, then uses it to update a table.
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 functions
Wrapping query logic in a function is a common way to keep code clean and readable. Building on Local (function) scope, you can wrap a whole query in a function and pass the values that change as parameters. Function parameters are in the function's local scope, so query strings inside the function can use them directly.
In the following example, we want to know how much sales tax we'll pay in several states for a given purchase amount. The query string in compute_tax uses the function's sales_price parameter, so calling compute_tax 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 defining them in Python. They are not Python variables. 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
- Python variables in query strings
- Python functions in query strings
- Formulas
- Filters
- Create and use partitioned tables
- Create a hierarchical rollup table programmatically
- Create a hierarchical tree table
empty_tablenew_tabledouble_colstring_colupdateupdate_byrolling_formula_tickfilterrolluptreedeephaven.columnPydoc