Transformation Types Reference
Complete reference for the transformation types available in projection property mappings, including their parameters, conflict behaviour, and usage examples.
Every property-level mapping in a projection carries a TransformationDefinition that describes what happens to data as it moves from source to target. The transformation type determines which additional fields are relevant and how conflict detection behaves.
TransformationType Union
export type TransformationType =
| 'direct' // 1:1 pass-through (same name and type)
| 'rename' // 1:1 with name change
| 'type-cast' // 1:1 with type change
| 'aggregate' // Many:1 with aggregation function
| 'concatenate' // Many:1 string concatenation
| 'calculate' // Many:1 arithmetic expression
| 'derive' // 0:1 computed (no source, expression-based)
| 'split' // 1:many (one source to multiple targets)
| 'custom'; // Free-text notes onlyTransformationDefinition Interface
export interface TransformationDefinition {
type: TransformationType;
aggregateFunction?: AggregateFunction;
expression?: string;
separator?: string;
targetType?: string;
notes?: string;
}Transformation Type Details
direct
A 1:1 pass-through mapping where the source property is copied to the target with no changes to name or type. This is the default transformation type assigned when a source property is first connected to a target property.
| Aspect | Detail |
|---|---|
| Cardinality | 1 source to 1 target |
| Relevant fields | notes (optional) |
| Conflict detection | Type mismatches and constraint narrowing are detected. If source and target types differ, the mapping should be changed to type-cast. |
| Example | Source: customer.firstName (string) to Target: customer.firstName (string) |
rename
A 1:1 mapping where the source property name changes in the target but the type remains the same. Used when the target system has different naming conventions or business terminology.
| Aspect | Detail |
|---|---|
| Cardinality | 1 source to 1 target |
| Relevant fields | notes (optional) |
| Conflict detection | Same as direct - type and constraint conflicts are detected. |
| Example | Source: customer.firstName (string) to Target: customer.first_name (string) |
type-cast
A 1:1 mapping where the target property has a different type from the source. Conflict detection raises type conversion warnings or errors depending on the direction of the cast.
| Aspect | Detail |
|---|---|
| Cardinality | 1 source to 1 target |
| Relevant fields | targetType (the explicit target type override), expression (optional conversion expression), notes |
| Conflict detection | Safe widenings (integer to decimal, date to datetime, boolean to string, etc.) produce info-level notifications. Narrowing casts (float to integer, datetime to date, string to integer) produce warnings or errors with resolution options. |
| Example | Source: order.totalAmount (decimal) to Target: report.totalAmount (float) with targetType 'float' |
aggregate
A many-to-one mapping where multiple source values are reduced to a single target value using an aggregation function. Typically used when projecting from a detail level to a summary level.
| Aspect | Detail |
|---|---|
| Cardinality | Many source rows to 1 target value |
| Relevant fields | aggregateFunction (required), expression (optional filter/group expression), notes |
| Available functions | count, sum, avg, min, max, count_distinct, first, last, list, concat, exists, all, none |
| Conflict detection | Multi-input conflicts may apply. Type compatibility between source and aggregation result is checked. |
| Example | Source: orderLine.quantity (integer) to Target: orderSummary.totalItems (integer) with aggregateFunction 'sum' |
concatenate
A many-to-one mapping that joins multiple source property values into a single string target using a separator character.
| Aspect | Detail |
|---|---|
| Cardinality | Multiple sources to 1 string target |
| Relevant fields | separator (e.g. ' ', '_', ', '), notes |
| Conflict detection | Target must be string or text type. Multi-input conflicts prompt for separator selection. |
| Example | Source: customer.firstName + customer.lastName to Target: customer.fullName with separator ' ' |
calculate
A many-to-one mapping that evaluates an arithmetic or logical expression combining multiple source properties into a single target value.
| Aspect | Detail |
|---|---|
| Cardinality | Multiple sources to 1 target |
| Relevant fields | expression (required, e.g. '{price} * {quantity}'), notes |
| Expression syntax | Field references use curly braces: {fieldName}. Standard arithmetic operators (+, -, *, /, %) and SQL-style functions (ROUND, COALESCE, CAST) are supported. |
| Conflict detection | Expression return type is inferred and checked against the target type. |
| Example | Expression: '{unitPrice} * {quantity} * (1 - {discountRate})' to Target: orderLine.lineTotal (decimal) |
derive
A zero-source mapping where the target value is computed entirely from an expression. No source property is connected. Used for generated columns, computed defaults, and audit fields.
| Aspect | Detail |
|---|---|
| Cardinality | 0 sources to 1 target |
| Relevant fields | expression (required), notes |
| Conflict detection | No source-target conflicts (no source exists). Expression syntax is validated. |
| Example | Expression: 'CURRENT_TIMESTAMP' to Target: audit.createdAt (datetime) |
split
A one-to-many mapping where a single source property feeds multiple target properties. Each target extracts a different portion or aspect of the source value.
| Aspect | Detail |
|---|---|
| Cardinality | 1 source to multiple targets |
| Relevant fields | expression (extraction logic per target), notes |
| Conflict detection | Each target has independent type and constraint checking against the source. |
| Example | Source: address.fullAddress (string) split to Target: address.street, address.city, address.postCode using SPLIT_PART expressions |
custom
A free-text mapping where the architect documents the transformation logic in natural language. No automated expression evaluation or conflict detection is applied. Used for complex business rules that cannot be expressed in the built-in expression language.
| Aspect | Detail |
|---|---|
| Cardinality | Any (architect-defined) |
| Relevant fields | notes (required - the transformation description) |
| Conflict detection | None. The mapping is treated as documentation only. |
| Example | Notes: 'Apply business rule BR-042: if customer tier is Gold and order total exceeds 1000, apply 15% loyalty discount before tax calculation.' |
Aggregate Function Reference
The following aggregate functions are available when the transformation type is 'aggregate'.
| Function | Return Type | Description |
|---|---|---|
| count | integer | Count the number of values (including nulls) |
| sum | numeric (same as input) | Sum all numeric values |
| avg | decimal | Calculate the arithmetic mean |
| min | same as input | Return the smallest value |
| max | same as input | Return the largest value |
| count_distinct | integer | Count the number of unique values |
| first | same as input | Return the first value in order |
| last | same as input | Return the last value in order |
| list | array | Collect all values into an array |
| concat | string | Concatenate all values as a string |
| exists | boolean | Return true if any value exists (non-null) |
| all | boolean | Return true if all values satisfy the condition |
| none | boolean | Return true if no values satisfy the condition |