UnionTable

A UnionTable stacks rows from multiple source tables. Field mappings declare which source-table fields feed each union-table field, since source schemas may differ.

Basic setup

Suppose orders are recorded in two separate tables — one for online orders, one for in-store orders — and we want a single table listing every order regardless of where it was placed. The example below unions OnlineOrders and StoreOrders into AllOrders:

from daitum_model import ModelBuilder, DataType

model = ModelBuilder()

online_orders = model.add_data_table("OnlineOrders")
online_orders.add_data_field("Order Id", DataType.STRING)
online_orders.add_data_field("Amount", DataType.DECIMAL)

store_orders = model.add_data_table("StoreOrders")
store_orders.add_data_field("Order Id", DataType.STRING)
store_orders.add_data_field("Total", DataType.DECIMAL)

all_orders = model.add_union_table("AllOrders", [online_orders, store_orders])
all_orders.add_field("Order Id", DataType.STRING)
all_orders.add_field("Amount", DataType.DECIMAL)

all_orders.direct_field_mapping()
all_orders.add_field_mapping(store_orders, "Amount", store_orders.get_field("Total"))

add_union_table creates AllOrders with OnlineOrders and StoreOrders as source tables, but the union table starts out with no fields or field mappings of its own — add_field declares the fields it will expose, and each source table’s rows must be mapped onto them field by field.

direct_field_mapping maps every union field to a source field of the same id, wherever one exists — here, that maps Order Id for both source tables, and also Amount for OnlineOrders, whose field happens to share that name. StoreOrders has no field called Amount, so its rows would otherwise have no value for that column; add_field_mapping fills the gap by mapping StoreOrders.Total onto AllOrders.Amount explicitly. A mapped source field must have the same data type as the union field it feeds.

API Reference

class UnionTable(id, source_tables)

Bases: Table

Represents a table that is derived by performing a union operation on multiple source tables.

A union operation combines rows from multiple tables into a single table. Unlike joins, a union does not merge columns based on key relationships but instead stacks rows from different tables on top of each other.

source_tables

The list of tables being combined into the UnionTable.

filter_field

An optional field ID that acts as a filter for selecting specific rows across the source tables.

set_filter_field(field)

Sets the filter field for this union table. Returns self.

Return type:

UnionTable

add_field(id, data_type, order_index=None, description=None)

Adds a new field to the UnionTable.

Parameters:

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

• data_type (BaseDataType) – The data type of the field.

• order_index (int | None) – (Optional) The order in which the field appears.

Returns:

The newly created DataField instance.

Return type:

DataField

add_field_mapping(source_table, field_name, source_field)

Maps a field from a source table to a field in the UnionTable.

Field mappings allow fields with different names in different tables to be treated as equivalent in the UnionTable.

Parameters:

• source_table (Table | UnionSource) – The source table containing the field, or a UnionSource describing the source table and the key to identify it if the same source is reused.

• field_name (str) – The name of the field in the UnionTable.

• source_field (Field) – The corresponding field in the source table.

Raises:

ValueError – If the source table is not part of the UnionTable.

direct_field_mapping(source_tables=None)

Automatically maps fields from the source tables that have matching field IDs.

If source_tables is not provided, it defaults to all source tables in the UnionTable.

Parameters:

source_tables (list[Table | UnionSource] | None) – (Optional) A list of source tables to perform direct field mapping on.

Raises:

ValueError – If a provided source table is not part of the UnionTable.

class FieldMapping(union_source)

Bases: Buildable

property source_table: Table

the source table for this field mapping.

Type:

Returns

property mapping_key: str

mapping_key for this field mapping.

Type:

Returns

add_map(field_name, source_field)

build()

Serialise this object to a JSON-compatible dict.

Converts public, non-None instance attributes to camelCase keys. Recursively builds nested Buildable objects, converts Enum values, and serialises date/time/datetime instances as lists of components.

Returns:

The serialised representation.

Return type:

dict[str, Any]

Raises:

TypeError – If an attribute value is of an unsupported type.

class UnionSource(source_table, mapping_key)

Bases: Buildable

A source table in a union. Multiple UnionSource instances in a UnionTable may reference the same underlying table, distinguished by mapping_key.

property source_table: Table