wjones127 commented on code in PR #35453:
URL: https://github.com/apache/arrow/pull/35453#discussion_r1252391253
##########
python/pyarrow/_parquet.pyx:
##########
@@ -494,6 +495,212 @@ cdef class ColumnChunkMetaData(_Weakrefable):
return self.metadata.total_uncompressed_size()
+cdef class SortingColumn:
+ """
+ Sorting specification for a single column.
+
+ Returned by :meth:`RowGroupMetaData.sorting_columns` and used in
+ :class:`ParquetWriter` to specify the sort order of the data.
+
+ Parameters
+ ----------
+ column_index : int
+ Index of column data is sorted by.
+ descending : bool, default False
+ Whether column is sorted in descending order.
+ nulls_first : bool, default False
+ Whether null values appear before valid values.
+
+ Notes
+ -----
+
+ Column indices are zero-based, refer only to leaf fields, and are in
+ depth-first order. This may make the column indices for nested schemas
+ different from what you expect. In most cases, it will be easier to
+ specify the sort order using column names instead of column indices
+ and converting using the ``from_sort_order`` method.
+
+ Examples
+ --------
+
+ In other APIs, sort order is specified by names, such as:
+
+ >>> sort_order = [('id', 'ascending'), ('timestamp', 'descending')]
+
+ For Parquet, the column index must be used instead:
+
+ >>> import pyarrow.parquet as pq
+ >>> [pq.SortingColumn(0), pq.SortingColumn(1, descending=True)]
+ [SortingColumn(column_index=0, descending=False, nulls_first=False),
SortingColumn(column_index=1, descending=True, nulls_first=False)]
+
+ Convert the sort_order into the list of sorting columns with
+ ``from_sort_order`` (note that the schema must be provided as well):
+
+ >>> import pyarrow as pa
+ >>> schema = pa.schema([('id', pa.int64()), ('timestamp',
pa.timestamp('ms'))])
+ >>> sorting_columns = pq.SortingColumn.from_sort_order(schema, sort_order)
+ >>> sorting_columns
+ (SortingColumn(column_index=0, descending=False, nulls_first=False),
SortingColumn(column_index=1, descending=True, nulls_first=False))
+
+ Convert back to the sort order with ``to_sort_order``:
+
+ >>> pq.SortingColumn.to_sort_order(schema, sorting_columns)
+ ((('id', 'ascending'), ('timestamp', 'descending')), 'at_end')
+
+ See Also
+ --------
+ RowGroupMetaData.sorting_columns
+ """
+ cdef int column_index
+ cdef c_bool descending
+ cdef c_bool nulls_first
+
+ def __init__(self, int column_index, c_bool descending=False, c_bool
nulls_first=False):
+ self.column_index = column_index
+ self.descending = descending
+ self.nulls_first = nulls_first
+
+ @classmethod
+ def from_sort_order(cls, Schema schema, sort_keys,
null_placement='at_end'):
Review Comment:
Yeah, was aiming to make familiar to users of that API.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
