stupidb.aggregation

Algorithms for aggregation.

Functions

make_key_func(order_func, nulls)

Make a function usable with the key argument to sorting functions.

row_key_compare(order_func, null_ordering, ...)

Compare left_row and right_row using order_by.

Classes

AggregateSpecification(aggregate_type, *getters)

Specification for computing a (non-windowed) aggregation.

FrameClause(order_by, partition_by, ...)

Class for computing frame boundaries.

Nulls(value)

An enumeration indicating how to handle null values when sorting.

RangeMode(order_by, partition_by, preceding, ...)

A frame clause implementation for window function RANGE mode.

RowsMode(order_by, partition_by, preceding, ...)

A frame clause implementation for window function ROWS mode.

StartStop(start, stop)

A class to hold start and stop values for a range of rows.

Window()

A namespace class providing the user-facing API for windowing modes.

WindowAggregateSpecification(aggregate_type, ...)

A specification for a window aggregate.
class stupidb.aggregation.AggregateSpecification(aggregate_type, *getters)[source]

Specification for computing a (non-windowed) aggregation.

aggregate_type

The aggregate class to use for aggregation.

getters

A tuple of callables used to produce the arguments for the aggregation.

See also

WindowAggregateSpecification

class stupidb.aggregation.FrameClause(order_by, partition_by, preceding, following, nulls)[source]

Class for computing frame boundaries.

compute_window_frame(possible_peers, current_row, row_id_in_partition, order_by_columns)[source]

Compute the bounds of the window frame.

Parameters

  • possible_peers (Sequence[AbstractRow]) – The sequence of possible rows of which the window could consist.

  • current_row (AbstractRow) – The row relative to which we are computing the window.

  • row_id_in_partition (int) – The zero-based index of current_row in possible_peers.

  • order_by_columns (Sequence[str]) – The columns by which we have ordered our window, if any.

Returns

The start and stop of the window frame.

Return type

StartStop

abstract find_partition_begin(current_row, row_id_in_partition, current_row_order_by_value, order_by_values)[source]

Find the beginning of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The start point of the window in the current partition

Return type

int

abstract find_partition_end(current_row, row_id_in_partition, current_row_order_by_value, order_by_values)[source]

Find the end of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The end point of the window in the current partition

Return type

int

abstract setup_window(possible_peers, current_row, order_by_columns)[source]

Compute the current row’s ordering keys.

class stupidb.aggregation.Nulls(value)[source]

An enumeration indicating how to handle null values when sorting.

class stupidb.aggregation.RangeMode(order_by, partition_by, preceding, following, nulls)[source]

A frame clause implementation for window function RANGE mode.

RANGE mode computes the window frame relative to the difference between preceding and following and the current row’s ordering key.

See also

RowsMode

find_partition_begin(current_row, row_id_in_partition, current_row_order_by_values, order_by_values)[source]

Find the beginning of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The start point of the window in the current partition

Return type

int

find_partition_end(current_row, row_id_in_partition, current_row_order_by_values, order_by_values)[source]

Find the end of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The end point of the window in the current partition

Return type

int

setup_window(possible_peers, current_row, order_by_columns)[source]

Compute the current row’s ordering keys.

class stupidb.aggregation.RowsMode(order_by, partition_by, preceding, following, nulls)[source]

A frame clause implementation for window function ROWS mode.

ROWS mode computes the window frame relative to the difference between the row index of the current row and what is given by preceding and following.

See also

RangeMode

find_partition_begin(current_row, row_id_in_partition, current_row_order_by_value, order_by_values)[source]

Find the beginning of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The start point of the window in the current partition

Return type

int

find_partition_end(current_row, row_id_in_partition, current_row_order_by_value, order_by_values)[source]

Find the end of a window in a partition.

Parameters

  • current_row – The row relative to which we are computing the window.

  • row_id_in_partition – The zero-based index of current_row in possible_peers.

  • current_row_order_by_value – The value of the ORDER BY key in the current row.

  • order_by_values – The order by values for the current partition.

Returns

The end point of the window in the current partition

Return type

int

setup_window(possible_peers, current_row, order_by_columns)[source]

Compute the current row’s ordering keys.

class stupidb.aggregation.StartStop(start: int, stop: int)[source]

A class to hold start and stop values for a range of rows.

start: int

Alias for field number 0

stop: int

Alias for field number 1

class stupidb.aggregation.Window[source]

A namespace class providing the user-facing API for windowing modes.

static range(order_by=(), partition_by=(), preceding=None, following=None, nulls=Nulls.FIRST)[source]

Construct a RANGE mode frame clause.

RANGE windows can be used to compute over windows whose bounds are not easily determined by row number such as time based windows.

See also

Window.rows

static rows(order_by=(), partition_by=(), preceding=None, following=None, nulls=Nulls.FIRST)[source]

Construct a ROWS mode frame clause.

ROWS windows are useful for computing over windows that can be determined by relative row index alone.

See also

Window.range

class stupidb.aggregation.WindowAggregateSpecification(aggregate_type, getters, frame_clause)[source]

A specification for a window aggregate.

aggregate_type

The class of ConcreteAggregate to use for aggregation.

getters

A tuple of functions that produce single column values given an instance of AbstractRow.

frame_clause

A thin struct encapsulating the details of the window such as ORDER BY (stupidb.aggregation.FrameClause.order_by), PARTITION BY (stupidb.aggregation.FrameClause.partition_by) and preceding and following.

See also

stupidb.aggregation.FrameClause

compute(rows)[source]

Aggregate rows over a window, producing an iterator of results.

Parameters

rows – An Iterable of rows.

stupidb.aggregation.make_key_func(order_func, nulls)[source]

Make a function usable with the key argument to sorting functions.

This return value of this function can be passed to sorted()/list.sort().

Parameters

order_by_columns – A sequence of str instances referring to the keys of an AbstractRow.

stupidb.aggregation.row_key_compare(order_func, null_ordering, left_row, right_row)[source]

Compare left_row and right_row using order_by.

Notes

NULL ordering is handled using null_ordering.