modules.mergers

Classes

class modules.mergers.MergeMaterialTable

Merge the two material tables to a single material table.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeMaterialTable', auto_run: bool = True, material_table1: PortTypeHint.MaterialTable | None = None, material_table2: PortTypeHint.MaterialTable | None = None, merge_by: Literal[GProps.MaterialID, GProps.LayerNumber, GProps.MaterialName] = GProps.MaterialID) → None

Initialize a MergeMaterialTable object.

Parameters

material_table1PortTypeHint.MaterialTable | None, default: None: The main material table.
material_table2PortTypeHint.MaterialTable | None, default: None: The another material table. merge_by: Literal[GProps.MaterialID, GProps.LayerNumber, GProps.MaterialName], default: GProps.MaterialID The column name to merge the material tables by.

Notes

The matearial_table2 will be merged into the material_table1 which means the output material_table will have
the same rows as the material_table1.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.MaterialTable | None

Properties:

InputMaterialTable1

InputMaterialTable2

OutputMaterialTable

class modules.mergers.MergeBoresWithMaterialTable

Merge Bores (MultiProfile1D) with MaterialTable to a TableCollection.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeBoresWithMaterialTable', auto_run: bool = True, bores: PortTypeHint.MultiProfile1D | None = None, material_table: PortTypeHint.MaterialTable | None = None, additional_fields: list[Literal[GRes.LayerBottomElevation, GRes.LayerTopElevation, GRes.LayerThickness]] | None = None) → None

Initialize a MergeBoresWithMaterialTable object.

Parameters

boresPortTypeHint.MultiProfile1D | None, default: None: The bores to merge.
material_tablePortTypeHint.MaterialTable | None, default: None: The material table to merge. additional_fields: list[Literal[GRes.LayerBottomElevation, GRes.LayerTopElevation, GRes.LayerThickness]], default: None The additional fields to put into the output material table.

Notes

Each bore in the MultiProfile1D will merge with the material table.
A MaterialTableCollection will be returned and the keys are bore numbers.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.TableCollection | None

Properties:

InputBores

InputMaterialTable

OutputTables

class modules.mergers.ConcatenateTables

Concatenate several tables.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'ConcatenateTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | None = None, add_table_name_columns: str | None = None, add_table_title_columns: str | None = None) → None

Initialize a ConcatenateTables object.

Parameters

tablesPortTypeHint.TableCollection | None, default: None: The tables to concatenate.
add_table_name_columnsstr | None, default: None: If provided, adds a column with this name containing the table names.
add_table_title_columnsstr | None, default: None: If provided, adds a column with this name containing the table titles.

Notes

``NaN`` value will be filled for tables that do not the columns in their original data.

set_cal_params(reset: bool = True) → None

execute() → PortTypeHint.TableData | None

Properties:

InputTables

OutputTable

class modules.mergers.MergeTables

Merge multiple tables from a TableCollection or merge two TableData objects.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, join_key: str | None = None, tables_to_merge: list[str] | str | None = None, how: Literal[(left, right, outer, inner)] = 'inner', suffixes: tuple[(str, str)] = <ast.Tuple object at 0x0000017357272920>, sort: bool = False, copy: bool = True, indicator: bool = False, validate: Literal[(one_to_one, one_to_many, many_to_one, many_to_many)] | None = None, ignore_index: bool = False) → None

Initialize a MergeTables object.

Parameters

tablesPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The input tables to merge. Can be a TableCollection containing multiple tables or a single TableData object.
join_keystr | None, default: None: The column name or field title to use for merging tables. If None, uses the first common column that exists in all tables. Tables without this column will be skipped.
tables_to_mergelist[str] | str | None, default: None: The names or titles of tables to include in the merge. If None, all tables in the collection will be considered. If a single string, converts to list. how: Literal[“left”, “right”, “outer”, “inner”], default: “inner” Type of merge to be performed. Use “inner” when you only want complete records (no missing data) Use “left” when you want to preserve all records from your main dataset Use “right” rarely used, when you want all records from the second dataset Use “outer” when you want a comprehensive view including all possible records suffixes: tuple[str, str], default: (“_x”, “_y”) Suffix to apply to overlapping column names.
sortbool, default: False: Sort the result DataFrame by the join keys.
copybool, default: True: If False, avoid copying data when possible.
indicatorbool, default: False: Add a column to the output DataFrame indicating the source. validate: Literal[“one_to_one”, “one_to_many”, “many_to_one”, “many_to_many”] | None, default: None Validation check on the merge operation. Use “one_to_one” when: Merging master records (employee info + employee contact) Each ID should appear exactly once in both tables You want to ensure no data duplication Use “one_to_many” when: Merging dimension tables with fact tables One category has multiple items (department → employees) Left table is the “lookup” table Use “many_to_one” when: Merging fact tables with dimension tables Multiple records reference the same lookup value Right table is the “lookup” table Use “many_to_many” when: Complex relationships exist You expect duplicates in both tables Junction/bridge table scenarios Use None when: You’re not sure about the relationship Performance is critical (validation adds overhead) You’ll handle data quality issues separately
ignore_indexbool, default: False: If True, do not use the index values along the concatenation axis. The resulting axis will be labeled 0, 1, …, n - 1.

Notes

If tables is a TableData object, it will be returned as-is.
If tables is a TableCollection, tables will be merged sequentially using the join_key.
Tables that don't contain the join_key will be skipped with a warning.

update_ui_schema(reset: bool = False) → dict[str, UIAttributeSchema]

execute() → PortTypeHint.TableData | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

OutputTable: PortReference[PortTypeHint.TableData]

class modules.mergers.MergeGdimTables

Merge tables with tables with gdim_id column which is

useful for table data pre-processing before writing table data into GDIM.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeGdimTables', auto_run: bool = True, tables: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, gdim_tables: PortTypeHint.TableCollection | None = None, how: Literal[ignore, overwrite] = 'ignore', auto_map_columns: bool = False, join_key: str | list[str] | None = None) → None

Initialize a MergeGdimTables object.

Parameters

tablesPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None

The input tables to merge. Can be a TableCollection containing multiple tables or a single TableData object.

gdim_tablesPortTypeHint.TableCollection | None, default: None

The gdim tables to be merged with the input tables. how: Literal[“ignore”, “overwrite”], default: “ignore” How to handle keys that exist in both the input table and the GDIM table.

“ignore”: Leave existing GDIM rows untouched. Only unmatched input keys are

emitted as inserts (gdim_id=None).

“overwrite”: For 1:1 tables, copy gdim_id onto matched input rows (update).

For 1:N groups, emit tombstone rows (keep gdim_id, other columns empty) for matched GDIM rows and emit all input rows as inserts. GDIM keys that are not present in the input are never emitted and are not deleted.

auto_map_columnsbool, default: False

Whether to automatically map columns between input tables and gdim tables. If True, columns will be matched by field name or field title with cross-matching (input name → gdim title, input title → gdim name, etc.). More flexible but slower. If False, uses fast matching: exact name match OR exact title match only. Set to False when input table columns already match gdim columns by name or title.

join_keystr | list[str] | None, default: None

Column name(s) or title(s) used to match rows when the table has no usable primary key, or to override PK matching. If the key is unique on both the input table and the GDIM table, merge uses 1:1 main-table logic. If either side has duplicate key values, merge uses 1:N sub-table logic (replace the matched group). When None, main tables use their own PK (1:1) and sub-tables use the parent PK (1:N). If no key can be resolved, all rows are inserts (gdim_id=None). Ports

InputTablesPortTypeHint.TableCollection | PortTypeHint.TableData

The input tables to merge. Can be a TableCollection containing multiple tables or a single TableData object.

InputGdimTablesPortTypeHint.TableCollection

The gdim tables to be merged with the input tables.

OutputTablesPortTypeHint.TableCollection | PortTypeHint.TableData

The merged tables.

Notes

The returned result has the same field structure as the gdim tables, not the input tables.
This ensures the output conforms to the GDIM database schema.

For columns that exist in gdim tables but are missing in input tables:
- 1:1 overwrite updates preserve original GDIM values on unmatched columns.
- Inserts and 1:N replacement rows fill those columns with None.
- Tombstone rows keep ``gdim_id`` and set every other column to None so the
  writer can delete those GDIM records.

Output behavior:
- 1:1 ignore: matched keys are omitted; only new keys are inserted.
- 1:1 overwrite: matched input rows keep ``gdim_id`` (update); new keys have
  ``gdim_id=None`` (insert).
- 1:N ignore: if a group key already exists in GDIM, the whole group is skipped.
- 1:N overwrite: matched GDIM rows become tombstones; all input rows are inserts.

If a table in ``InputTables`` has no corresponding table in ``InputGdimTables`` (no match by
name or title), the input table is returned unchanged:
- No ``gdim_id`` column is added
- The table structure remains unchanged
- No column mapping or transformation occurs
- The table is still included in the output collection

execute() → PortTypeHint.TableCollection | PortTypeHint.TableData | None

Attributes:

InputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

InputGdimTables: PortReference[PortTypeHint.TableCollection]

OutputTables: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

class modules.mergers.MergeSingleResult

Merge multiple SingleResult objects into a SingleResult.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeSingleResult', auto_run: bool = True, all_ports_required: bool = True, default_strategy: Literal[overwrite_first, overwrite_last, concat_list, concat_string] = 'overwrite_last', string_separator: str = ', ', key_strategies: dict[str, Literal[overwrite_first, overwrite_last, concat_list, concat_string]] | None = None) → None

Initialize a MergeSingleResult object.

Parameters

all_ports_requiredbool, default: True

If True, the execution will be blocked until all the dynamic ports are connected with valid data. default_strategy: Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”], default: “overwrite_last” The default strategy for handling conflicting keys:

“overwrite_first”: Keep the value from the first SingleResult (first has priority)
“overwrite_last”: Keep the value from the last SingleResult (last has priority)
“concat_list”: Concatenate all values into a list (handles existing lists properly)
“concat_string”: Concatenate all values into a string with separator

string_separator: str, default: “, ” The separator to use when concatenating values as strings (only used with “concat_string” strategy). key_strategies: dict[str, Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”]] | None, default: None A dictionary specifying strategies for specific keys (by result name or title). Keys not in this dictionary will use the default_strategy.

Notes

When merging SingleResult objects:
- For different keys (no conflict), they are simply combined like merging dictionaries
- For conflicting keys, the specified strategy is applied
- For "concat_list" strategy, if a value is already a list, its elements are added individually
- Key strategies can use either result names or titles for identification

execute() → PortTypeHint.SingleResult | None

Attributes:

OutputSingleResult: PortReference[PortTypeHint.SingleResult]

class modules.mergers.MergeResultModels

Merge multiple ResultModel and SingleResult objects into a single ResultModel.

Dynamic input ports accept either ``PortType.ResultModel`` or ``PortType.SingleResult``. Fields from all inputs are combined into one output ``ResultModel``. Conflicting field names (present in more than one input) are resolved with the same strategies available in :class:MergeSingleResult.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'MergeResultModels', auto_run: bool = True, all_ports_required: bool = True, default_strategy: Literal[overwrite_first, overwrite_last, concat_list, concat_string] = 'overwrite_last', string_separator: str = ', ', key_strategies: dict[str, Literal[overwrite_first, overwrite_last, concat_list, concat_string]] | None = None) → None

Initialize a MergeResultModels object.

Parameters

all_ports_requiredbool, default: True

If True, the execution will be blocked until all the dynamic ports are connected with valid data. default_strategy: Literal[“overwrite_first”, “overwrite_last”, “concat_list”, “concat_string”], default: “overwrite_last” The default strategy for handling conflicting field names:

“overwrite_first”: Keep the value from the first input (first has priority).
“overwrite_last”: Keep the value from the last input (last has priority).
“concat_list”: Concatenate all values into a list (flattens existing lists).
“concat_string”: Concatenate all values into a string with string_separator.

string_separator: str, default: “, ” The separator used when concatenating values as strings. Only used with the “concat_string” strategy. key_strategies: dict[str, Literal[…]] | None, default: None Per-field override strategies. Keys are field names (or, for ``SingleResult`` inputs, ``UnitResult.title`` values). Fields not present in this dict fall back to default_strategy.

Notes

- ````SingleResult```` inputs are expanded field-by-field using
  ````UnitResult.name```` as the field name and ````UnitResult.value```` as the
  value.  The ````UnitResult.title```` is used for ````key_strategies```` lookup.
- ````ResultModel```` inputs are expanded with ````model_dump()````.  The
  ````Field(title=...)```` metadata (if present) is used for
  ````key_strategies```` lookup.
- The output model is a dynamically created Pydantic ````BaseModel````
  whose field names are the union of all input field names.

execute() → PortTypeHint.ResultModel | None

Attributes:

OutputResultModel: PortReference[PortTypeHint.ResultModel]

class modules.mergers.AddTables

Add tables to a TableCollection or seed from a TableData.

Inherits from:: PipeModule

Methods:

__init__(mname: str = 'AddTables', auto_run: bool = True, tables_to_add: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, tables_added_to: PortTypeHint.TableCollection | PortTypeHint.TableData | None = None, main_table_name: str | None = None, sub_table_names: list[str] | dict[str, list[str]] | None = None, primary_key: str | None = None, collection_metadata: TableMetadata | dict | Literal[tables_to_add, tables_added_to, combined] = 'tables_added_to', combine_sep: str = '\n') → None

Initialize the AddTables object.

Parameters

tables_to_addPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The tables to add to the collection.
tables_added_toPortTypeHint.TableCollection | PortTypeHint.TableData | None, default: None: The collection or base TableData to merge into. A lone TableData is wrapped in a new TableCollection.
main_table_namestr | None, default: None: Table name or title to treat as an additional main table (merged into existing main_table, which may be str or list[str]). sub_table_names: list[str] | dict[str, list[str]] | None, default: None Sub-tables as names or titles. If a list, entries are merged into sub_tables (list or dict[str, list[str]]). If a dict, keys are main names or titles and values are lists of sub names or titles (see TableCollection.sub_tables).
primary_keystr | None, default: None: Primary key field name or title (resolved per main table). Merged into existing primary_key (str or dict[str, str]). collection_metadata: TableMetadata | dict | Literal[“tables_to_add”, “tables_added_to”, “combined”], default: “tables_added_to” If TableMetadata or dict, it will be used to override the output TableCollection metadata. If “tables_to_add”, InputTablesToAdd metadata will be used for the output TableCollection metadata. if “tables_added_to”, InputTablesAddedTo metadata will be used for the output TableCollection metadata. if “combined”, InputTablesToAdd and InputTablesAddedTo metadata will be combined with combine_sep.
combine_sepstr, default: `”: “` Separator used when combining metadata field values from multiple input sources. Only used when collection_metadata is “combined”. Ports —–
InputTablesToAddPortTypeHint.TableCollection | PortTypeHint.TableData: The tables to add.
InputTablesAddedToPortTypeHint.TableCollection | PortTypeHint.TableData: The collection or base table to add into.
OutputTablesPortTypeHint.TableCollection: The resulting table collection after adding tables.

Notes

----
        If either ``InputTablesToAdd`` or ``InputTablesAddedTo`` is unset, execution yields
        ``None`` on ``OutputTables``. Relationship parameters merge into existing structure
        instead of replacing it.

execute() → PortTypeHint.TableCollection | None

Attributes:

InputTablesToAdd: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

InputTablesAddedTo: PortReference[PortTypeHint.TableCollection | PortTypeHint.TableData]

OutputTables: PortReference[PortTypeHint.TableCollection]