Mapping
PLEASE NOTE: This documentation applies to an earlier version. For the most recent documentation, visit the Pentaho Enterprise Edition documentation site.
Description
When you want to re-use a certain sequence of steps, you can turn the repetitive part into a mapping.
A "mapping" as such is a regular transformation with the exception that it is possible to define mapping input and output steps as placeholders.
- Mapping input: the placeholder where the mapping expects input from the parent transformation
- Mapping output: the placeholder where the parent transformation is reading data from.
A mapping is also known as a sub-transformation.
Note: To differentiate log lines from a mapping, you can set the KETTLE_LOG_MARK_MAPPINGS variable to 'Y'. Set this variable to Y to precede log lines with the mapping step name and the mapping itself (available since PDI 5.1).
Options
Option | Description |
---|---|
Step name | Name of the step. Note: This name has to be unique in a single transformation. |
Mapping transformation | Use this section to specify the sub-transformation to execute. You have the following options to specify the sub-transformation:
|
Parameters | The Parameters tab allows you to define or pass Kettle variables down to the mapping.
|
Input tabs | Each of the input tabs (can be absent as well) correspond to one Mapping Input specification step in the mapping- or sub-transformation.
|
Output tabs | Each of the output tabs (can be absent as well) correspond to one Mapping Output specification step in the mapping- or sub-transformation.
|
Allow multiple 'Mapping Input' steps in the sub-transformation | When checked, the sub-transformation can have multiple Mapping input specification steps that receive data from the parent transformation. In this case, the Add Input button is enabled so you can add multiple Input tabs to specify the mapping for each Mapping input specification. When not checked, 1 Mapping input specification step (and hence, 1 Input tab) is presumed. |
Add input | Use this button to add a tab to specify an input mapping for the specified sub-transformation. This button will always be enabled when the "Allow multiple 'Mapping Input' steps in the sub-transformation" option is checked. When that option is not checked, the "Add Input" button will be enabled only in case there are no input tabs present. |
Allow multiple "Mapping Output' steps in the sub-transformation | When checked, the sub-transformation can have multiple Mapping output specification steps that send data to the parent transformation. In this case, the Add Output button is enabled so you can add multiple Output tabs to specify the mapping for each Mapping output specification. When not checked, 1 Mapping output specification step (and hence, 1 Output tab) is presumed. |
Add output | Use this button to add a tab to specify an output mapping for the specified sub-transformation. This button will always be enabled when the "Allow multiple 'Mapping Output' steps in the sub-transformation" option is checked. When that option is not checked, the "Add Output" button will be enabled only in case there are no output tabs present. |
Example
You can find the sample described below in your distribution over here:
samples/mapping/Mapping - simple mapping.ktr samples/mapping/Mapping - use simple mapping.ktr
Suppose we have a JavaScript step that we want to re-use over and over in several transformations (a simple concatenation to demonstrate the point) :
As you can see, the input fields that the script needs are: leftValue and rightValue, 2 Strings.
What we can then do is define those in a "Mapping Input" step:
The calculated value "res" is a field we want to pass to the parent transformations, so we add a "Mapping Output" step as well.
Remember, Mapping Input and Output are placeholders, there is no actual logic in them.
The resulting mapping looks like this:
Now that our mapping is done, let's try to use it...
In this example, there are 2 fields coming into the Mapping step "X=A+B": A and B.
That means that there is somehow a "mapping" to be made between
- "A" and "leftValue"
- "B" and "rightValue"
- "res" and "X" the result field
This can be achieved in the "Input" and "Output" tabs of the Mapping dialog. Here is a screen shot of the Input tab:
*NOTE:* In our sample, we only use one input and output mapping. It is possible however to use 0, 1 or more of either input or output mappings in a mapping transformation.
That means that we need to be able to specify which input or output we're addressing in the various tabs. That is where the various step name choices come from in the screenshot.
In our simple case, we simply checked the "Is this the main data path" option.
Here is a screen shot for the output tab: