DerivedTable

A DerivedTable is built from another table with optional grouping, filtering and sorting. When grouping is configured, fields can be added with an AggregationMethod to summarise the source rows.

class DerivedTable(id, source_table, group_by=None, filter_field=None)

Bases: Table

Represents a derived table that is based on another source table and supports grouping, sorting, and filtering.

source_table_id: str

sort_keys: list[_SortKey]

grouping_configuration: _GroupingConfiguration | None

filter_field: str | None

add_source_fields(source_fields=None, include_validators=False)

Adds fields to the current object from the source table or grouping configuration.

This method checks whether the source_fields parameter is provided. If source_fields is None, it adds all fields from the source table or grouped fields (depending on whether the grouping configuration is present). If source_fields is provided, it validates that each field is present in the available fields before adding it.

Parameters:

• source_fields (list[Field] | None) – A list of Field objects to be added. Defaults to None, for which case all available fields will be added.

• include_validators (bool) – Whether to propagate validators from source fields to the derived table. Defaults to False.

Raises:

ValueError – If Any field in source_fields is not found in the available fields.

Note

If _grouping_configuration is None, fields are taken from self.source_table._fields. If _grouping_configuration is not None, fields are taken from self.grouping_configuration.group_by_fields.

add_sort_key(field, direction)

Adds a sort key to the derived table.

Parameters:

• field (Field) – The field to sort by.

• direction (SortDirection) – The direction in which to sort.

add_aggregated_field(id, source_field, aggregation_method, tracking_group=None)

Adds an aggregated field to the table.

Parameters:

• id (str) – The unique identifier for the aggregated field.

• source_field (Field) – The source field that will be aggregated.

• aggregation_method (AggregationMethod) – The method used to aggregate the source_field.

• tracking_group (str | None) – Group identifier for change tracking.

Raises:

• ValueError – If no grouped fields are present in the table.

• ValueError – If the aggregation method is not valid for the source field’s data type.

Return type:

DataField

class SortDirection(*values)

Enumeration representing the possible sorting options for a SortKey in a DerivedTable.

ASCENDING = 'ASCENDING'

Ascending sort direction.

DESCENDING = 'DESCENDING'

Descending sort direction.

class AggregationMethod(*values)

Enumeration listing the possible aggregation methods for aggregated fields.

BLANK = 'BLANK'

Returns a typed null for the target field without aggregating values. Allowed DataTypes: any type. Return DataTypes: same as the allowed type.

COUNT = 'COUNT'

Counts the number of non-null input items and returns that count. Result type is INTEGER irrespective of the source item type. Allowed DataTypes: any type. Return DataTypes: INTEGER.

SUM = 'SUM'

Sums numeric inputs. For array targets, performs element-wise sum across arrays. Allowed DataTypes: INTEGER, DECIMAL, INTEGER_ARRAY, DECIMAL_ARRAY. Return DataTypes: same as the allowed type.

MIN = 'MIN'

Returns the minimum (by natural ordering) of the inputs. Allowed DataTypes: any comparable scalar type (INTEGER, DECIMAL, STRING, BOOLEAN, DATE, TIME, DATETIME) and other comparable values. Not intended for arrays. Return DataTypes: same as the allowed type.

MAX = 'MAX'

Returns the maximum (by natural ordering) of the inputs. Allowed DataTypes: any comparable scalar type (INTEGER, DECIMAL, STRING, BOOLEAN, DATE, TIME, DATETIME) and other comparable values. Not intended for arrays. Return DataTypes: same as the allowed type.

AVERAGE = 'AVERAGE'

Calculates the arithmetic mean of numeric inputs and returns a DECIMAL value. Allowed DataTypes: INTEGER, DECIMAL. Return DataTypes: DECIMAL.

FIRST = 'FIRST'

Returns the first input value encountered (typed), or null if none. Allowed DataTypes: any type. Return DataTypes: same as the allowed type.

LAST = 'LAST'

Returns the last input value encountered (typed), or null if none. Allowed DataTypes: any type. Return DataTypes: same as the allowed type.

EQUAL = 'EQUAL'

If all input values are equal, returns that value; otherwise returns typed null. Allowed DataTypes: any type. Return DataTypes: same as the allowed type.

AND = 'AND'

Logical AND over boolean inputs. Nulls are treated as false by booleanValue() conversion. Allowed DataTypes: BOOLEAN. Return DataTypes: same as the allowed type.

OR = 'OR'

Logical OR over boolean inputs. Nulls are treated as false by booleanValue() conversion. Allowed DataTypes: BOOLEAN. Return DataTypes: same as the allowed type.

ARRAY = 'ARRAY'

Collects input items into an array of the target element type, preserving order. Allowed DataTypes: any non-array types except MapDataType (e.g., INTEGER, DECIMAL, STRING, BOOLEAN, DATE, TIME, DATETIME, OBJECT) Return DataTypes: the corresponding array type of the allowed type. (e.g., INTEGER_ARRAY, DECIMAL_ARRAY, STRING_ARRAY, BOOLEAN_ARRAY, DATE_ARRAY, TIME_ARRAY, DATETIME_ARRAY, OBJECT_ARRAY)

REFERENCE = 'REFERENCE'

Creates an OBJECT_ARRAY of references from row ids provided by the evaluation engine. Allowed DataTypes: any type. Return DataTypes: OBJECT_ARRAY for a specific table.

INTERSECTION = 'INTERSECTION'

Computes the set intersection across array inputs and returns an array result. Allowed DataTypes: any scalar or array type. Return DataTypes: the array of the scalar type when scalar target is provided, or the same array type when the target is already an array.

UNION = 'UNION'

Computes the set union of inputs. If inputs are arrays, unions their elements; if inputs are scalars, unions individual values.. Allowed DataTypes: any scalar or array type. Return DataTypes: the array of the scalar type when scalar target is provided, or the same array type when the target is already an array.