Formula validation configuration

When you work with Deephaven tables, you often create custom columns or filter data using expressions like:

  • myTable.update(myColumn = x + y * 2)
  • myTable.where("Double.isFinite(Price)")

These expressions get sent to the Deephaven server over gRPC and compiled into executable code. For security reasons, the server needs to validate that these expressions only call approved methods and functions. Script session code execution is not validated as the Deephaven engine does not parse script code. The console service can be disabled via configuration.

This guide explains how to configure formula validation using two main approaches:

  • Annotations (for your own code)
  • Pointcut expressions (for external libraries)

When does validation occur?

Formula validation happens when requests are sent over gRPC, such as those made by any of Deephaven's client APIs:

Validation does not apply to:

  • Code you write directly in the console/script editor.
  • Python functions or Groovy closures in your session scope (these are blocked when validation is enabled).

How validation works

When you write a formula, Deephaven:

  1. Parses your expression to find all method calls.
  2. Checks each method call against the configured rules.
  3. Either permits or denies the expression based on those rules.

Method 1: Annotations (for your own code)

Use this approach when you're writing your own Java classes and want to make specific methods available in Deephaven formulas.

Annotations are special markers you add to your Java code to indicate which methods should be allowed in formulas. The key annotation is @UserInvocationPermitted.

How annotations work

  1. Add the annotation to your class or individual methods.
  2. Give it a name using the value parameter (like a category name).
  3. Configure Deephaven to recognize that category name.
  4. Optionally specify scope to limit to static or instance methods only.

Annotate entire classes

When you annotate a class, all public methods in that class become available:

Limit annotations to static or instance methods

You can restrict which types of methods are allowed:

Annotate individual methods

For more precise control, annotate specific methods instead of entire classes:

Best practices for annotations

When designing your annotations, follow these recommendations:

  • Use descriptive annotation values that clearly indicate the method category (e.g., math_operations, string_utilities).
  • Group logically related methods together rather than creating separate annotations for each method.
  • Avoid creating too many small annotation categories, as this increases configuration complexity.
  • Consider the security implications - only annotate methods that are safe for user formulas.
  • Group related methods under the same annotation value to reduce configuration.

Configuration

After adding annotations to your code, you must tell Deephaven to recognize them by setting configuration properties.

Default configuration:

Deephaven comes with pre-configured annotations for built-in functionality:

Adding your own annotations:

  • The property name format is: ColumnExpressionValidator.annotationSets.<your_name>.
  • List all your annotation values separated by commas.

Method 2: Pointcut expressions (for external libraries)

Use this approach when you want to allow methods from libraries you don't control (like Java's built-in classes, third-party libraries, etc.).

Since you cannot add annotations to external code, you use pointcut expressions — patterns that match method signatures. The pattern syntax is adapted from AspectJ method patterns, and is a simple way to match one or more Java methods.

Understanding pointcut patterns

A pointcut expression has three parts. Separate the class name from the method name with a space or # (java.lang.String length() and java.lang.String#length() are the same).

  1. Class name: The full package and class name (e.g., java.util.Collections). A class in java.lang may omit its package (String is the same as java.lang.String). Write a nested class as java.util.Map.Entry or java.util.Map$Entry, and use *..* for every class. Only a name without dots or wildcards is taken to be in java.lang, so a nested java.lang class without its package must use $: Thread$State works, but Thread.State is taken as a fully qualified name and does not match java.lang.Thread.State (write that instead).
  2. Method name: The specific method, a name with * wildcards such as to*Case, <constructor> for a constructor, or * for any method or constructor.
  3. Parameters: The parameter types or (..) for any parameters. Write primitive types by their keyword (int, double). Other types must be fully qualified, except for types in java.lang such as String. Write an array parameter as T[] in any position, such as java.util.Arrays fill(int[], int). The last parameter may instead be written T..., which is the same as T[]; ... is rejected anywhere else.

Pattern matching symbols

  • * = A wildcard within a name. In a method name, or in one segment of a class or parameter type name, it matches any run of characters but never crosses a .: to*Case matches toUpperCase and toLowerCase, and java.lang.* matches every class in java.lang, but not arrays of them, which java.lang.*[] matches. In a class name, a segment also matches the binary name of a nested class, so java.util.* also matches java.util.Map$Entry. A parameter of only * matches any one parameter type, including primitive and array types, while a parameter of *..* matches any one type that is not an array (write *..*[] for a one-dimensional array), and a method name of only * matches constructors as well as methods.
  • .. = In a parameter list, match any number of parameters of any type; a parameter list may contain at most one ... In a class name, match any number of package or enclosing class names — java.util..* matches every class in java.util and its sub-packages, and java.util..Entry matches java.util.Map.Entry, while java.util.* does not include sub-packages.
  • ; = Separate multiple patterns in one property.

Inherited methods

A pattern also matches every instance method that overrides a matching method. For example, java.lang.Object toString() permits toString on any class, and java.lang.Number intValue() permits intValue on Integer, BigDecimal, and every other subclass of Number. Static methods match only the class that declares them.

A class pattern matches only the methods and constructors that the class itself declares, plus overrides of those methods in subclasses. It does not match methods the class inherits without overriding: java.lang.String *(..) does not permit getClass on a String, because Object declares it and String does not override it.

Common examples

Default Deephaven pointcut configuration

Deephaven comes pre-configured with safe methods from common Java classes:

Backwards compatibility (Deephaven 0.39.x and earlier)

For older versions only: Prior to Deephaven 0.40.0, validation used a simple method name allowlist instead of the sophisticated system described above.

To revert to the old behavior (not recommended for new deployments):

Note

The old system was less secure and flexible. The new annotation and pointcut system provides better security and control.