parquet_sortkey Derived Type

type, public :: parquet_sortkey

A read-time sort specification: an ordered list of sort KEYS, each naming one column and the direction to order it by. Passed as parquet_open_reader(..., sort_by=), or applied to an already-open reader with parquet_reader_set_sort. Every column read afterwards comes back in that order.

One key per %add call, applied in the order added (first key is the primary one):

type(parquet_sortkey) :: srt
call srt%add("ra asc")
call srt%add("dec desc")
call srt%add("id", nulls_first=.true.)

Key text is " [asc|desc]" -- the direction is optional and defaults to ascending, is case-insensitive, and a leading "-" on the column name is shorthand for descending ("-dec" == "dec desc"). The column may be a dotted struct-leaf path, exactly as a filter clause's may.

Nulls sort LAST by default, per key; pass nulls_first=.true. on %add to put that key's null rows first instead. NaN sits between real values and nulls (so, by default: values, then NaNs, then nulls) and, like nulls, its placement is absolute -- ordering a key descending reverses the values, not where nulls and NaNs go. This reproduces Arrow's own sort ordering exactly, so a result cross-checked against pyarrow matches row for row.

Keys are unvalidated here -- the column must exist and be a sortable scalar column, which is checked once a reader actually applies the sort. See "Reading rows in sorted order with parquet_sortkey" in doc/pages/io/filter-sort-sample.md.

The type is named for what it holds (the keys), not for the operation; a sorted read is requested through parquet_open_reader/parquet_reader_set_sort.

%remap_column_names(from, to) rewrites the column each key orders by, in place, replacing from(k) with to(k); each key's direction and nulls_first setting are carried across unchanged. It is the sort twin of parquet_filter%remap_column_names and follows the same rules -- see that type's doc comment.


Components

Type Visibility Attributes Name Initial
character(len=:), public, allocatable :: keys(:)

Raw, unvalidated key text, one entry per %add call. Deferred-length, the same way parquet_filter%rules is: every entry shares the length of the longest key added so far.
logical, public, allocatable :: nulls_first(:)

Per key: .true. to place that key's null rows before its values instead of after. Same extent as keys(1:n).
integer, public :: n = 0

Number of keys actually in use.

Type-Bound Procedures

procedure, public :: add => parquet_sortkey_add

Appends one sort key, applied after those already added.

  • private subroutine parquet_sortkey_add(this, key, nulls_first)

    Appends one sort key; see parquet_sortkey's own doc comment for the key grammar and the null-placement rule. Unvalidated here -- the reader parses each key and checks the column when it actually applies the sort. The stored text is deferred-length, exactly as parquet_filter%add's is.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_sortkey), intent(inout) :: this

    sort spec gaining one key.
    character(len=*), intent(in) :: key

    " [asc|desc]" (max sortkey_max_key_len characters).
    logical, intent(in), optional :: nulls_first

    place this key's null rows first; defaults to .false. (nulls last).

procedure, public :: remap_column_names => parquet_sortkey_remap_column_names

Renames the column every key orders by, in place: from(k) becomes to(k).

  • interface

    private module subroutine parquet_sortkey_remap_column_names(this, from, to)

    Rewrites every sort key's column, replacing name from(k) with to(k). Backs parquet_sortkey%remap_column_names -- see that binding for what it is for. Each key's direction and its nulls_first setting are carried across unchanged.

    Arguments

    Type IntentOptional Attributes Name
    class(parquet_sortkey), intent(inout) :: this

    sort spec whose keys are rewritten in place.
    character(len=*), intent(in) :: from(:)

    names to replace; same size as to.
    character(len=*), intent(in) :: to(:)

    replacement for each entry of from.

Source Code

    type parquet_sortkey
        !> Raw, unvalidated key text, one entry per %add call. Deferred-length, the same way
        !! parquet_filter%rules is: every entry shares the length of the longest key added so far.
        character(len=:), allocatable :: keys(:)
        !> Per key: .true. to place that key's null rows before its values instead of after.
        !! Same extent as keys(1:n).
        logical, allocatable :: nulls_first(:)
        integer :: n = 0 !! Number of keys actually in use.
    contains
        procedure :: add => parquet_sortkey_add !! Appends one sort key, applied after those already added.
        !> Renames the column every key orders by, in place: `from(k)` becomes `to(k)`.
        procedure :: remap_column_names => parquet_sortkey_remap_column_names
    end type parquet_sortkey