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.

Basic setup

Filtered derived table

A filtered derived table keeps only the source rows where a BOOLEAN field is True. The example below builds an Orders table and a derived table, LargeOrders, that keeps only the orders with a quantity over 10:

from daitum_model import ModelBuilder, DataType

model = ModelBuilder()

orders = model.add_data_table("Orders")
orders.set_key_column("Order Id")
orders.add_data_field("Order Id", DataType.STRING)
quantity = orders.add_data_field("Quantity", DataType.INTEGER)
is_large = orders.add_calculated_field("Is Large", quantity > 10)

large_orders = model.add_derived_table("LargeOrders", orders, filter_field=is_large)
large_orders.add_source_fields()

filter_field must reference a BOOLEAN field on the source table. add_source_fields() with no arguments copies every field from Orders into LargeOrders.

Grouped derived table

A grouped derived table collapses source rows that share the same value for one or more fields, then summarises the remaining fields with an AggregationMethod. The example below groups Orders by Customer and sums the quantity ordered by each customer:

from daitum_model import ModelBuilder, DataType, AggregationMethod

model = ModelBuilder()

orders = model.add_data_table("Orders")
orders.set_key_column("Order Id")
orders.add_data_field("Order Id", DataType.STRING)
customer = orders.add_data_field("Customer", DataType.STRING)
quantity = orders.add_data_field("Quantity", DataType.INTEGER)

orders_by_customer = model.add_derived_table("OrdersByCustomer", orders, group_by=[customer])
orders_by_customer.add_source_fields()
orders_by_customer.add_aggregated_field("Total Quantity", quantity, AggregationMethod.SUM)

group_by lists the fields used to group rows — here, one row is produced per distinct Customer. add_source_fields() adds the group-by fields themselves, and add_aggregated_field adds a new field that aggregates a field from the source table across each group.

Sorted derived table

A sorted derived table orders its rows by one or more fields. The example below sorts Orders by Quantity from highest to lowest:

from daitum_model import ModelBuilder, DataType, SortDirection

model = ModelBuilder()

orders = model.add_data_table("Orders")
orders.set_key_column("Order Id")
orders.add_data_field("Order Id", DataType.STRING)
quantity = orders.add_data_field("Quantity", DataType.INTEGER)

orders_by_quantity = model.add_derived_table("OrdersByQuantity", orders)
orders_by_quantity.add_source_fields()
orders_by_quantity.add_sort_key(quantity, SortDirection.DESCENDING)

add_sort_key can be called more than once to sort by additional fields — each extra call breaks ties left over from the previous sort key.

API Reference

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)

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.

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.