feat: DH-21235: Column Restriction JS API

docs/groovy/how-to-guides/input-tables.md

@@ -172,6 +172,81 @@ result = AppendOnlyArrayBackedInputTable.make(definition)
 
 ![Manually adding a clickable link to an input table](../assets/how-to/groovy-input-table-link.gif)
 
+## Input table validators
+
+Input table validators allow you to add validation rules to input tables, ensuring that data entered (either programmatically or manually through the UI) meets specific criteria. Validators wrap an existing input table and check data before it's added, throwing validation exceptions if the data doesn't meet the requirements.
+
+Deephaven provides several built-in validators:
+
+- **RangeValidatingInputTable** - Validates that integer values fall within a specified range (min/max inclusive)
+- **DoubleRangeValidatingInputTable** - Validates that double values fall within a specified range (min/max inclusive)
+- **NotNullValidatingInputTable** - Validates that values in a column are not null
+- **NonEmptyValidatingInputTable** - Validates that string values are not empty
+- **StringListValidatingInputTable** - Validates that string values belong to a predefined set of allowed values
+
+### Creating validated input tables
+
+To create a validated input table, first create a base input table, then wrap it with one or more validators. Here's an example showing all available validators:
+
+```groovy order=intRangeValidator,doubleRangeValidator,notNullValidator,notNullValidatorInt,nonEmptyValidator,stringListValidator
+import io.deephaven.engine.table.impl.util.KeyedArrayBackedInputTable
+import io.deephaven.server.table.inputtables.RangeValidatingInputTable
+import io.deephaven.server.table.inputtables.DoubleRangeValidatingInputTable
+import io.deephaven.server.table.inputtables.NotNullValidatingInputTable
+import io.deephaven.server.table.inputtables.NonEmptyValidatingInputTable
+import io.deephaven.server.table.inputtables.StringListValidatingInputTable
+
+// Create source table with various column types
+_source = newTable(
+    stringCol("Key", "Apple", "Banana", "Carrot", "Date", "Eggplant"),
+    intCol("IntValue", 1, 2, 3, 50, 75),
+    doubleCol("DoubleValue", 1.5, 2.5, 3.5, 50.5, 75.5),
+    stringCol("Category", "Fruit", "Fruit", "Vegetable", "Fruit", "Vegetable"),
+    stringCol("Description", "Red", "Yellow", "Orange", "Sweet", "Purple")
+)
+
+// Example 1: Integer Range Validator (0-100)
+intRangeValidator = RangeValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "IntValue", 
+    0, 
+    100
+)
+
+// Example 2: Double Range Validator (0.0-100.0)
+doubleRangeValidator = DoubleRangeValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "DoubleValue", 
+    0.0, 
+    100.0
+)
+
+// Example 3: Not Null Validator on Category column
+notNullValidator = NotNullValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "Category"
+)
+
+// Example 3.1: Not Null Validator on IntValue column
+notNullValidatorInt = NotNullValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "IntValue"
+)
+
+// Example 4: Non-Empty Validator on Description column
+nonEmptyValidator = NonEmptyValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "Description"
+)
+
+// Example 5: String List Validator - Category must be "Fruit", "Vegetable", or "Grain"
+stringListValidator = StringListValidatingInputTable.make(
+    KeyedArrayBackedInputTable.make(_source, "Key"), 
+    "Category", 
+    "Fruit", "Vegetable", "Grain"
+)
+```
+
 ## Related documentation
 
 - [Input Table](../reference/table-operations/create/InputTable.md)

docs/groovy/snapshots/52261de3cea59a05c348dcdee2078741.json

@@ -0,0 +1 @@
+{"file":"how-to-guides/input-tables.md","objects":{"_source":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"intRangeValidator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"doubleRangeValidator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"notNullValidator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"notNullValidatorInt":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"nonEmptyValidator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"stringListValidator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}}}}

docs/python/how-to-guides/input-tables.md

@@ -222,6 +222,91 @@ result = input_table(col_defs=my_col_defs)
 
 ![Manually adding a clickable link to an input table](../assets/how-to/ui/clickable_link_gif.gif)
 
+## Input table validators
+
+Input table validators allow you to add validation rules to input tables, ensuring that data entered (either programmatically or manually through the UI) meets specific criteria. Validators wrap an existing input table and check data before it's added, throwing validation exceptions if the data doesn't meet the requirements.
+
+Deephaven provides several built-in validators:
+
+- **RangeValidatingInputTable** - Validates that integer values fall within a specified range (min/max inclusive)
+- **DoubleRangeValidatingInputTable** - Validates that double values fall within a specified range (min/max inclusive)
+- **NotNullValidatingInputTable** - Validates that values in a column are not null
+- **NonEmptyValidatingInputTable** - Validates that string values are not empty
+- **StringListValidatingInputTable** - Validates that string values belong to a predefined set of allowed values
+
+### Creating validated input tables
+
+To create a validated input table, first create a base input table, then wrap it with one or more validators. Here's an example showing all available validators:
+
+```python order=int_range_validator,double_range_validator,not_null_validator,not_null_validator_int,non_empty_validator,string_list_validator
+from deephaven import new_table, input_table
+from deephaven.column import string_col, int_col, double_col
+
+# Create source table with various column types
+source = new_table(
+    [
+        string_col("Key", ["Apple", "Banana", "Carrot", "Date", "Eggplant"]),
+        int_col("IntValue", [1, 2, 3, 50, 75]),
+        double_col("DoubleValue", [1.5, 2.5, 3.5, 50.5, 75.5]),
+        string_col("Category", ["Fruit", "Fruit", "Vegetable", "Fruit", "Vegetable"]),
+        string_col("Description", ["Red", "Yellow", "Orange", "Sweet", "Purple"]),
+    ]
+)
+
+# Import Java classes for validators (not available in Python API yet)
+import jpy
+
+range_validating_input_table = jpy.get_type(
+    "io.deephaven.server.table.inputtables.RangeValidatingInputTable"
+)
+double_range_validating_input_table = jpy.get_type(
+    "io.deephaven.server.table.inputtables.DoubleRangeValidatingInputTable"
+)
+not_null_validating_input_table = jpy.get_type(
+    "io.deephaven.server.table.inputtables.NotNullValidatingInputTable"
+)
+non_empty_validating_input_table = jpy.get_type(
+    "io.deephaven.server.table.inputtables.NonEmptyValidatingInputTable"
+)
+string_list_validating_input_table = jpy.get_type(
+    "io.deephaven.server.table.inputtables.StringListValidatingInputTable"
+)
+
+# Example 1: Integer Range Validator (0-100)
+int_range_validator = range_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table, "IntValue", 0, 100
+)
+
+# Example 2: Double Range Validator (0.0-100.0)
+double_range_validator = double_range_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table, "DoubleValue", 0.0, 100.0
+)
+
+# Example 3: Not Null Validator on Category column
+not_null_validator = not_null_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table, "Category"
+)
+
+# Example 3.1: Not Null Validator on IntValue column
+not_null_validator_int = not_null_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table, "IntValue"
+)
+
+# Example 4: Non-Empty Validator on Description column
+non_empty_validator = non_empty_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table, "Description"
+)
+
+# Example 5: String List Validator - Category must be "Fruit" or "Vegetable"
+string_list_validator = string_list_validating_input_table.make(
+    input_table(init_table=source, key_cols="Key").j_table,
+    "Category",
+    "Fruit",
+    "Vegetable",
+    "Grain",
+)
+```
+
 ## Related documentation
 
 - [`input_table`](../reference/table-operations/create/input-table.md)

docs/python/snapshots/1c93fc2136637c6bbc241e13ab956466.json

@@ -0,0 +1 @@
+{"file":"how-to-guides/input-tables.md","objects":{"source":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"int_range_validator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"double_range_validator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"not_null_validator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"not_null_validator_int":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"non_empty_validator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}},"string_list_validator":{"type":"Table","data":{"columns":[{"name":"Key","type":"java.lang.String"},{"name":"IntValue","type":"int"},{"name":"DoubleValue","type":"double"},{"name":"Category","type":"java.lang.String"},{"name":"Description","type":"java.lang.String"}],"rows":[[{"value":"Apple"},{"value":"1"},{"value":"1.5000"},{"value":"Fruit"},{"value":"Red"}],[{"value":"Banana"},{"value":"2"},{"value":"2.5000"},{"value":"Fruit"},{"value":"Yellow"}],[{"value":"Carrot"},{"value":"3"},{"value":"3.5000"},{"value":"Vegetable"},{"value":"Orange"}],[{"value":"Date"},{"value":"50"},{"value":"50.5000"},{"value":"Fruit"},{"value":"Sweet"}],[{"value":"Eggplant"},{"value":"75"},{"value":"75.5000"},{"value":"Vegetable"},{"value":"Purple"}]]}}}}

engine/table/src/main/java/io/deephaven/engine/util/input/InputTableUpdater.java

@@ -57,12 +57,17 @@ default List<String> getValueNames() {
     }
 
     /**
-     * If there are client-side defined restrictions on this column; return them as a JSON string to be interpreted by
-     * the client for properly displaying the edit field.
+     * If there are client-side defined restrictions on this column, return them as a list of protobuf Any messages.
+     * These restrictions are used by the client for properly displaying and validating the edit field.
+     *
+     * <p>
+     * The restrictions are packed as {@code google.protobuf.Any} messages, which allows for different restriction types
+     * (e.g., {@code IntegerRangeRestriction}, {@code DoubleRangeRestriction}, {@code StringListRestriction}, etc.) to
+     * be sent to the client. The client is responsible for unpacking and interpreting these restrictions.
      *
      * @param columnName the column name to query
-     * @return a string representing the restrictions for this column, or null if no client-side restrictions are
-     *         supplied for this column
+     * @return a list of protobuf Any messages representing the restrictions for this column, or null if no client-side
+     *         restrictions are supplied for this column
      */
     @Nullable
     default List<Any> getColumnRestrictions(final String columnName) {