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 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. 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:
with_keys records the key columns as a table attribute; it doesn't change the table's data:
See with_keys for the full syntax and parameter reference.
Select a single row
Your key columns form a true primary key when each combination of their values identifies exactly one row. Use with_unique_keys for these keys instead of with_keys. It sets the same key-column metadata, 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 with_unique_keys for the full syntax and parameter reference.
Note
with_unique_keys 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 with_keys would.
Keep key columns through later operations
Key columns are just table attributes, so only specific operations carry them forward automatically — among them where, sort, reverse, flatten, update_view, natural_join, and exact_join. Most other operations, including select, update, join, and drop_columns, do not.
view is an easy one to trip over: it looks like update_view's sibling, but it does not preserve key columns, while update_view does.
If an operation you need drops the key columns, call with_keys or with_unique_keys again on the result:
See with_keys and with_unique_keys for the exhaustive list of operations that preserve these attributes.