Keyed row selection
This guide shows you how to control what happens when a user selects a row in the Deephaven UI: whether the selection covers just that one row, or every row that shares its key. You control this by marking key columns on the table.
By default, a table carries no metadata that says which columns identify a row, so the UI can't tell when two rows represent the same real-world entity. Marking one or more columns as key columns closes that gap. The UI then tracks a selection by key value, so on a ticking table the selection stays with its rows even as updates move them to new positions in the grid. Key columns are metadata only: setting them doesn't change any data in the table.
Select every row with a matching key
Use with_keys when rows can legitimately share the same key value, such as several rows that belong to the same group, and you want selecting one of them to select all of them.
Key1 and Key2 together form the key, and the combination of their values repeats every six rows. Selecting any row in the Deephaven UI selects every row that shares its combination. Selecting row 0, for example, selects rows 0, 6, 12, and so on, which all have Key1 = 0 and Key2 = 0:
Both columns matter here. Key1 = 0 alone matches rows 0, 3, 6, 9, and so on, but rows 3 and 9 have Key2 = 1, so they aren't selected.
Because one key can cover many rows, the UI counts this selection in keys, not rows. The grid's screen-reader summary, for example, reads "1 key selected." for the selection shown above. When you copy the selection or download it with Download CSV, the UI includes every row that matches a selected key, not only the rows you can see.
with_keys stores the key columns in the keyColumns table attribute, a piece of metadata attached to the table. Print the attributes to see it:
See with_keys for the full syntax and parameter reference.
Select one row by its unique key
Your key columns form a true primary key when each combination of their values identifies exactly one row. For these keys, use with_unique_keys instead of with_keys. It sets the same keyColumns attribute and also sets uniqueKeys to True, which records that no two rows share a key. Selection still follows the key, but the UI now counts each selected key as one row. The Only Selected Rows option in Download CSV, for example, shows how many rows you selected.
Every row here has a distinct combination of Key1 and Key2, so selecting a row selects only that row:
Printing the attributes shows uniqueKeys set to True alongside keyColumns:
Note
with_unique_keys records that the key values are unique but doesn't check it. If two rows share a key, selecting one still selects both, but the UI counts them as one row. Row counts the UI shows for that selection, such as in the Download CSV dialog, are then too low.
See with_unique_keys for the full syntax and parameter reference.
Keep key columns through later operations
Key columns are table attributes, and each operation decides which attributes to carry forward. Operations that preserve key columns include where, sort, reverse, flatten, update_view, natural_join, exact_join, aj, and raj. The joins keep the left table's key columns. Most other operations, including select, update, join, and drop_columns, do not. For more operations that preserve key columns, see Preserved through table operations in the with_keys reference.
view does not preserve key columns, even though update_view does. The two names look alike, so this difference is easy to miss.
If an operation you need drops the key columns, call with_keys or with_unique_keys again on the result:
The first print shows both keyColumns and uniqueKeys. The second shows that select dropped them, and the third shows them restored.