Sort table data

Sorting is a common operation in data analysis, and Deephaven makes it easy to sort data in a variety of ways. This guide shows how to sort table data programmatically by one or more columns and in different directions, and explains the order in which Deephaven sorts values. It also covers restrictSortTo, which limits the columns users can sort a table on.

Tip

You can also sort columns by right-clicking the column header in the UI.

Sort by one column

You can sort table data programmatically by using the sort and sortDescending methods:

Given a column name to order the data by, sort returns a new table with the data sorted in ascending (A-Z) order, and sortDescending returns a new table with the data sorted in descending (Z-A) order. In resultSort, the three A rows keep their original order (red, orange, pink) because the sort is stable.

Sorting works the same way on live data: when the source table ticks, the sorted result updates and stays in order.

Sort order rules

Deephaven sorts values by their natural order, which is the order the column's type defines:

  • Numbers sort in numeric order.
  • Date-times sort in chronological order.
  • Strings sort character by character, and the comparison is case-sensitive, so uppercase letters sort before lowercase letters.
  • Other Comparable values sort by their own compareTo method.

Deephaven's sort is also stable: rows with equal sort values keep their original relative order.

Natural order has special rules for nulls, floating-point values, and arrays:

  • Nulls: In ascending order, null values sort first. Descending sorts reverse this, so null values come last.
  • Floating-point values: NaN sorts after all other values in ascending order and first in descending order. Positive zero and negative zero are equal, so two rows whose values are 0.0 and -0.0 keep their original order.
  • Arrays and vectors: Deephaven sorts array and vector columns, such as the output of groupBy, lexicographically. It compares the first elements, then the second, and so on. An array that matches the start of a longer array sorts first. Deephaven registers comparators by default for columns whose type is exactly one of these array types: byte[], short[], int[], long[], char[], float[], double[], String[], BigInteger[], BigDecimal[], Comparable[], Instant[], ZonedDateTime[], LocalDate[], LocalDateTime[], LocalTime[], Date[], and Duration[]. Sorting a column of any other array type, such as Integer[], throws a NotSortableColumnException, even when the array's elements are Comparable.

To see the null and NaN rules in action, let's sort a column that holds a null, a NaN, and two ordinary values in both directions:

In resultRulesAsc, the order is null, -1.0, 2.0, NaN. In resultRulesDesc, the order is reversed: NaN, 2.0, -1.0, null.

Sort by multiple columns

Both sort and sortDescending can sort by multiple columns at once. Let's sort the source table from Sort by one column by the Letter column, then use the Number column to order rows that share a Letter value. sortDescending applies descending order to both columns.

Sort columns in different directions

To sort each column in its own direction, pass sort a list of SortColumn objects, one per column, in priority order:

Both methods take a ColumnName, which ColumnName.of creates from the column's name. Let's sort by Letter in ascending order, then by Number in descending order:

You can get the same result by chaining sort and sortDescending, but a list of SortColumn objects is simpler. In a chain, the last sort becomes the primary sort key, so the sorts go in reverse priority order. This works because each sort is stable: rows that tie on the last sort's column keep the order the earlier sort gave them. Here, Number is sorted first and Letter last:

Restrict which columns can be sorted

The restrictSortTo method restricts which columns users can sort the table on, both in the UI and in code. This is useful if you want to prevent yourself or other users from accidentally performing expensive sort operations as you interact with tables in the UI. For example, let's restrict sorting to the Letter column:

We can still sort by Letter:

However, sorting by Number throws an exception:

The call throws a NotSortableException whose message names the column you tried to sort on.

To remove the restriction, call clearSortingRestrictions on the table. It returns a table that can be sorted on any column.