SortOrderProvider

The SortOrderProvider class specifies the sort order to use when writing data to an Iceberg table from Deephaven. It allows users to select the sort order by sort order ID, use the default sort order of the table, specify unsorted data, or configure error handling for unmapped columns.

Deephaven sorts the data it writes by that sort order, but orders strings and floating-point values differently than the Iceberg specification does. So each new data file declares the sort order in the Iceberg metadata only when every field of the sort order is on a boolean, integer, date, time, or timestamp column and uses the identity transform. The last field may instead use any order-preserving transform, such as day. Otherwise, the data file declares no sort order. Either way, Deephaven also records the sort's leading column in its own metadata in each data file.

Constructors

A SortOrderProvider is constructed using one of the following class methods:

Methods

  • from_sort_id: Selects a sort order by its ID from the Iceberg table metadata.
  • use_table_default: Uses the table's default sort order.
  • unsorted: Specifies that data should be written without any sort order.
  • with_fail_on_unmapped: Determines if an existing SortOrderProvider will fail or not if any columns in the sort order are not present in the data to be written.
  • with_id: Returns a new sort order provider that uses the existing provider to determine the columns to sort on, but writes a provided sort order ID to the Iceberg table. The ID is written only when Deephaven can declare the sort order with that ID, and is still checked otherwise.

Parameters

ParameterTypeDescription
sort_order_idint

The ID of the sort order as defined in the Iceberg table's metadata.

fail_on_unmappedbool

If True, writing will fail if any columns required by the sort order are not present in the data. If False, missing columns are ignored.

Usage

A SortOrderProvider is used as an argument to TableParquetWriterOptions when writing Deephaven tables to Iceberg, allowing control over the sort order of the written data.

Examples

The following example creates a TableParquetWriterOptions that writes data using the table's default sort order:

To specify a particular sort order by ID and fail on unmapped columns:

To write data without any sort order: