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 follows just that one row, or every row that shares its identity.
By default, Deephaven has no notion of which column or columns make a row unique, 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. Key columns are metadata: setting them doesn't change any data in the table, only how the UI interprets a row selection.
Select every row with a matching key
Use withKeys 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. Because the combination Key1=0, Key2=1 repeats across many rows, selecting any one of them in the Deephaven UI selects every row that shares that combination:
withKeys records the key columns as a table attribute; it doesn't change the table's data:
See withKeys for the full syntax and parameter reference.
Select a single row
If your key columns identify exactly one row apiece, a true primary key, use withUniqueKeys instead. It sets the same key-column metadata as withKeys, but also tells the UI that no two rows share a key, so selecting a row never pulls in any others.
Every row here has a distinct Key1 value, so selecting a row tracks only that row:
See withUniqueKeys for the full syntax and parameter reference.
Note
withUniqueKeys doesn't verify that the key values are actually unique; it only records that assumption. If two rows do end up sharing a key, the UI treats them the same way withKeys would.
Keep key columns through later operations
Key columns are just table attributes, so only specific operations carry them forward automatically. where, sort, reverse, flatten, updateView, naturalJoin, exactJoin, and wouldMatch all preserve them. Most other operations, including select, update, join, and dropColumns, do not.
view is an easy one to trip over: it looks like updateView's sibling, but it does not preserve key columns, while updateView does.
If an operation you need drops the key columns, call withKeys or withUniqueKeys again on the result:
See withKeys and withUniqueKeys for the exhaustive list of operations that preserve these attributes.