Tables

A model holds rows of data in tables. Every table is a subclass of Table and exposes a fluent builder API for adding fields and validators.

The four concrete table types each address a different shape of data:

• DataTable — raw data and decision variables

• DerivedTable — grouped, sorted, filtered view of a source table

• JoinedTable — rows produced by joining two or more tables

• UnionTable — rows stacked from multiple source tables

class Table(id)

Bases: Buildable, _TableBase

The base class for all table types.

This class defines the core structure and behavior of a table, including field management and relationships with derived tables.

key_column_field: str | None

id_field: str | None

model_level: bool

field_definitions: dict[str, Field]

export_as_key_column: bool

property key_column: str | None

The key column field ID used for object references, or None if not set.

property validation_group: str | None

The validation group identifier, or None if not assigned to a group.

property display_name: str

The human-readable display name for this table. Defaults to the table ID.

set_key_column(key_column)

Sets the key column for this table. Returns self.

Return type:

Table

set_id_field(id_field)

Sets the id field for this table. Returns self.

Return type:

Table

set_model_level(model_level)

Sets whether this table is model-level. Returns self.

Return type:

Table

set_validation_group(group)

Sets the validation group for this table. Returns self.

Return type:

Table

set_display_name(name)

Sets the display name for this table. Returns self.

Return type:

Table

set_export_as_key_column(export_as_key=True)

Configures the table to export its key column instead of the row number when generating

reports. Returns self.

Parameters:

• export_as_key (bool) – If True, the table’s key column is exported.

• False (If)

• True. (the row number is exported instead. Defaults to)

Return type:

Table

initialise_field(id, data_type)

Registers a placeholder field with the given ID and data type.

Use this when a field must exist before its final definition is known — for example, when using PREV or NEXT, or to resolve circular dependencies in combo fields. The placeholder will be automatically replaced when add_calculated_field or add_combo_field is later called with the same id.

Parameters:

• id (str) – The unique ID of the field.

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

Returns:

The placeholder field, which can be referenced in formulas.

Return type:

DataField

add_data_field(id, data_type, tracking_group=None)

Adds a data field to the table.

This method should be implemented by subclasses and is not valid for the base Table class.

Raises:

NotImplementedError – Always raised since this method is not applicable to Table.

Return type:

DataField

add_object_reference_field(id, table, is_array=False, tracking_group=None)

Adds an object reference field to the table.

Parameters:

• id (str) – The ID of the new field.

• table (Table) – The table being referenced.

• is_array (bool) – Whether the object reference is an array.

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

Returns:

The created object reference field.

Return type:

DataField

add_map_field(id, data_type, table, tracking_group=None)

Adds a map field to the table.

Parameters:

• id (str) – The ID of the new field.

• data_type (DataType) – The underlying data type of the map values.

• table (Table) – The table field maps into.

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

Returns:

The created map field.

Return type:

DataField

add_calculated_field(id, formula, order_index=None, description=None, tracking_group=None)

Adds a CalculatedField to the table.

Parameters:

• id (str) – The ID of the calculated field.

• formula (Operand | float | int | bool | str) – The formula used to compute the field value.

• order_index (int | None) – The order index of the field.

• description (str | None) – Description of the field.

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

Returns:

The created CalculatedField object.

Return type:

CalculatedField

get_field(id)

Retrieves a field from the table.

Parameters:

id (str) – The ID of the field to retrieve.

Returns:

The field object matching the given ID.

Return type:

Field

Raises:

ValueError – If the field does not exist in the table.

get_fields()

Retrieves all fields in the table.

Returns:

A sequence of fields contained in the table.

Return type:

Sequence[Field]

get_validation_state()

Build a calculated field representing the maximum severity rank among all currently-invalid fields in this table.

For each field with validators, COUNT(table[field__invalid__severity], True) > 0 is used to check whether any row is invalid at that severity level. The result is a scalar formula — all rows will carry the same value — evaluating to the highest SEVERITY_RANK among failing fields, or 0 when nothing is invalid.

The result is registered in the table as a calculated field named __validation_state__. Subsequent calls return the already-registered field without rebuilding it.

Returns:

A calculated field whose value is the highest severity rank of any currently-invalid field in this table.

Return type:

Field | CalculatedField