# tHMap Information noteNote: This component is not shipped with your Talend Studio by default. To use it, you need to install the Data Mapper > Talend Data Mapper feature using the Feature Manager. For more information, see [Installing features using the Feature Manager](https://help.qlik.com/talend/r/en-US/8.0/studio-user-guide/install-features-to-talend-studio). Executes transformations (called maps) between different sources and destinations by harnessing the capabilities of Talend Data Mapper, available in the Mapping perspective. tHMap transforms data from a wide range of sources to a wide range of destinations, including support for multiple inputs and multiple outputs. If you want to use multiple inputs, you must use Talend Data Mapper I/O functions. For more information, see [Input/Output expressions](https://help.qlik.com/talend/r/en-US/8.0/data-mapper-user-guide/input-output-expressions). ## tHMap Standard properties These properties are used to configure tHMap running in the Standard Job framework. The Standard tHMap component belongs to the Processing family. This component is available in Talend Data Management Platform, Talend Big Data Platform, Talend Real-Time Big Data Platform, Talend Data Services Platform and in Talend Data Fabric. ## Basic settings | Properties | Description | | --- | --- | | Open Map Editor | Click the [...] button
to open the Structure Generate/Select
wizard.

You can first select the type of map to create:

Standard Map: Map that perform mappings using functions based on xQuery
DSQL Map: Map that performs mappings using Data Shaping Query Language.

You can select the Don't ask me again check box
to save this preference. For more information about these map types, see
[Working with maps](https://help.qlik.com/talend/r/en-US/8.0/data-mapper-user-guide/working-with-maps).

Information noteNote: This option is available only if you have installed the
R2023-10 Studio monthly update or a later one delivered by Talend. For more information, check with your administrator.

Then you can either have the hierarchical mapper structure generated
automatically based on the schema, or select an existing hierarchical mapper
structure. You must do this for both the input and output sides of your Map.
The following lists the options for the output structure:

Generate hierarchical mapper structure based on the schema option: When you connect multiple output connections to the tHMap, the page displays a confirmation message that informs you that the mapper structures are generated based on the output connections.
Select an existing hierarchical mapper structure option: You can connect multiple outputs that are payload-based connections to the tHMap. If there is a single payload-type connection, you can select the Allow support for multiple output connections check box. The generated output map inherits from the existing payload structure.

If Talend Studio detects multiple output connections available, the window displays both
output structure options without the support for multiple output connections
check boxes.

If neither input nor output connection exists, the Structure Selection page
is displayed. | | Synchronize map with schema connections | Select this check box if you want to automatically regenerate
your map's input and output structures after one of the following changes:

Connection metadata change
Input or output connection added
Input or output connection removed

No changes are detected when a connection is activated or deactivated.

If this check box is selected, the map is automatically
synchronized when opened from the component after a change. If not, a dialog appears to
ask whether you want to synchronize.

Information noteNote: For structures with multiple
connections, the map can only be synchronized if the structures have the same form
as the ones generated by the component configuration wizard. For example, flattening
maps with multiple outputs cannot be synchronized automatically. | | Map Path | Specifies the map to be executed.

If the map was automatically created using the wizard described above,
this is path is set automatically.

If you want to use an existing map, click the [...] button next to the Map
Path field to open a dialog box in which you can select
the map you want to use, then click the [...] button next to Open Map
Editor to work with the map selected. Note that this map
must have previously been created in the
Mapping
perspective. | | Read Input As | Select the radio button which corresponds to how you want the input to
be read. Depending on your map, only some of the options may be
available.

Data Integration columns (default): Use this option if you are working with Talend Data Integration metadata.
Single column: Use this option if you are working with Talend Data Mapper metadata.

| | Write Output As | Select the radio button which corresponds to how you want
the output to be written. Depending on your map, only some of the
options may be available.

Data Integration columns (default): Use this option if you are working with Talend Data Integration metadata.
String (single column): Use this option if the data in the output column is to be a String.
Byte array (single column): Use this option if the data in the output column is to be a Byte array.
InputStream (single column): Use this option if you are working with Talend Data Mapper metadata and the input data is a stream.
Document (single column); Use this option if the output column is to be a Document.

| ## Advanced settings | Properties | Description | | --- | --- | | Map Variable | In this field, enter a context variable or a global variable
that contains a path to a map. For instance, if you enter *context.mymapfile*, then *mymapfile* can point to
different map files at runtime. This can be useful in cases where you want to
use multiple maps without creating a new Job each time.

The value of the variable must be a relative path. For
instance, assuming you have a map called *mapA* in the
folder *Maps/FolderA*, your variable should contain the
value *"FolderA/mapA.xml"*. You can write the path to the
file with or without the .xml extension.

Note that all maps that might be referenced by the variable
must be present in the same project. This way, when the Job is built, it will
contain all candidate maps and it will be possible to switch from one to
another at runtime.

For further information on working with context variables, see
[Using contexts and variables](https://help.qlik.com/talend/r/en-US/8.0/studio-user-guide/contexts-and-variables) in the
Talend Studio User Guide. | | Alternate contextual Map(s) | From the drop-down list, select a map or several maps that can be referenced by
the context variable added in the Map Variable at
runtime.

The alternate maps selected must have the same map type (standard or DSQL) as
the original map.

When the Job is built, it contains the selected alternate contextual map or
maps. For an example scenario on using Alternate contextual Map(s), see [Specifying a map variable and alternate map in tHMap](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/specifying-map-variable-and-alternate-map-in-thmap) | | Map each row (disable virtual
component) | Select this check box to have tHMap process the input as a single output row. This
prevents tHMap from buffering the
input rows before delivering them downstream.

This can be useful, for example, when you use the
tHMap component with
tSAPIDocReceiver as the input
component and any schema-aware component as the output component,
because telling the tSAPIDocReceiver component to keep listening forever
would otherwise lead to rows never being delivered.

If the tHMap is used with an input component that
can remain open to continuously receive inputs, such as the
tRestRequest, this option should be selected.
It allows the tHMap to directly process the input
received. | | Emit empty payload | Select this check box to send an empty row in the
output connection when there is no output data. This can happen if there is
no input or if the entire input is filtered out in the map. If this check
box is cleared, no rows are sent to the output connection.

This option is applied only when the Map each row check box is
cleared. | | Use old Eclipse runtime (deprecated) | Select this check box to include the old Eclipse runtime in
your Job.

Information noteNote: This option is available only if you have
installed the R2024-03 Talend Studio
monthly update or a later one delivered by Talend.
For more information, check with your administrator.

Information noteNote: From Talend Studio 8.0 R2025-04
onwards, the Use old Eclipse runtime (deprecated) parameter
has been removed. | | Exception Threshold | Talend Data Mapper returns an execution status with an severity
value which can be OK, Info, Warning, Error or Fatal. By setting the exception threshold, you can
specify the severity level at which an exception is thrown, thus
enabling downstream components to detect the error in cases other than
the default value of Fatal.

From the drop-down list, select the severity level at
which an exception may be thrown during the execution of a map.

Fatal (default): An exception is thrown when a fatal error occurs.
Error: An exception is thrown when an error (or higher) occurs.
Warning: An exception is thrown when a warning (or higher) occurs.

To help you diagnose problems with your map, when you test the
map in Talend Studio, any errors that occur which are at warning level or above will be printed
in the console window, regardless of the setting of the Exception Threshold. | | tStatCatcher Statistics | Select this check box to gather the Job processing
metadata at the Job level as well as at each component level. | ## Global Variables | Variables | Description | | --- | --- | | Global Variables | ERROR\_MESSAGE: the error message generated by the
component when an error occurs. This is an After variable and it returns a string. This
variable functions only if the Die on error checkbox is
cleared, if the component has this checkbox.

MapExecutionStatus: returns an object of the
org.talend.transform.runtime.common.MapExecutionStatus
class

EXECUTION\_SEVERITY: the *Overall
Severity* numeric value. This is an After variable and it returns an
integer.

A Flow variable functions during the execution of a component
while an After variable functions after the execution of the component.

To fill up a field or expression with a variable, press Ctrl+Space to access the variable list and choose the variable to use from
it.

For more information about variables, see [Using contexts and variables](https://help.qlik.com/talend/r/en-US/8.0/studio-user-guide/contexts-and-variables). | ## Usage | Usage guidance | Description | | --- | --- | | Usage rule | tHMap is used for Jobs that
require complex data mapping from a variety of different sources.

The input and output connections can use
Talend Data Mapper metadata, Talend Data Integration
metadata, or a combination of the two. Each connection is
independent.

When you open the Map Editor for the
first time for each connection, it either generates a Talend Data Mapper
structure definition based on the schema of the Talend Data Integration
component, or allows you to select an existing Talend Data Mapper
structure if you are using Talend Data Mapper metadata. It then creates a map
with the structure selected or generated.

This component can be used in several ways:

You can work with a Talend Data Mapper map and structures based on Talend Data Mapper metadata. In this case, the components (for instance, tFileInputRaw and tFileOutputRaw) pass the data in a single column in a single row.

For an example of this usage, see Using metadata.
You can work with Talend Data Integration metadata. In this case, you connect an input and output component to tHMap then open the Map Editor without specifying a map path.

For an example of this usage, see Using metadata.
You can work with a combination of Talend Data Mapper metadata and Talend Data Integration metadata.

For an example of this usage, see Transforming from a Data Integration schema to a complex content schema.
You can work with raw file inputs and schema-based input connections as inputs to tHMap.
For examples of this usage, see Generating the Output Using tHMap with Multiple Schema Inputs and Generating the Output using tHMap with Multiple Payload Inputs.
You can work with database tables created in Talend Studio and connect these tables as inputs to tHMap. If you have Jobs that use the deprecated DatabaseLookup feature, see Migrating from DatabaseLookup to tHMap for the steps on how to migrate to tHMap.
You have the option to connect tHMap to multiple database output connections. To migrate previously created Jobs using IO Database functions, see Migrating IO Database functions to tHMap Multi-Output Database Connections.
You can connect tHMap to multiple output connections using raw file, schema-based connections, and payload-based connections.
Handling errors shows how to handle error conditions using the tHMap component.
For a thMap with a single connection, the Wrap Structure option (Allow tHMap to support multiple inputs/outputs) is, by default, unchecked for these options: Generate from Schema (schema-based) and Select From Existing Structure (payload-type).

| | Advanced use case |

For the output Structure of the thMap, you can also use the WriteURL function in Talend Data Mapper . In case the output Structure of the tHMap includes both a connection to a Talend Data Integration metadata or component and a WriteURL function, the WriteURL value takes precedence. Talend Data Integration metadata or component does not receive any data from tHMap.
Using tHMap, you can test the generated Talend Data Mapper Map in Test Run mode.
To use the feature, ensure that you have a compatible input document of CSV format with these properties:
- The default delimiter is the (,) comma.
- The system default line separator is used as the newline.
- There is no header row in the input file.
- There will be no header row in the output file.
Specify your input document in Show Document > Select Sample Input Document > Select Resource/Import Document.

To execute the transformation, click Test Run. After execution, your generated output document is in CSV format, which you can save by clicking Save to File. To configure this feature, see Test preferences.

Information noteTip: If you have multiple inputs and outputs in your Map, specify an input document for each row or each ReadURL map element. To execute, use the Test Run to External Output option and specify a file URL for each WriteURL in the output structure of the Map.

| | Limitations |

If you created a tHMap with multiple input or output connections, you can only add new schema-based input or output connections.
When you add a new connection with a single column, you cannot associate it with a payload structure. The Map Regeneration mechanism only generates a single-element record for the new connection.
A Job containing a tHMap cannot be deployed as an OSGi bundle with the old Eclipse-based runtime.

| | Usage with Talend Runtime | If you want to deploy a Job or Route containing a data mapping component
with Talend Runtime, you first need to install the Talend Data Mapper feature. For more information, see [Using Talend Data Mapper with Talend Runtime](https://help.qlik.com/talend/r/en-US/8.0/data-mapper-user-guide/using-talend-data-mapper-with-talend-runtime). | Information noteNote: * For further information about performing transformations using Talend Data Mapper , see [this documentation](https://help.qlik.com/talend/r/en-US/8.0/data-mapper-user-guide/what-is-talend-data-mapper). * When using representations other than Map, CSV, Avro, XML, and Cobol, running this component with the old Eclipse-based Runtime may create temporary folders, which are not automatically removed after stopping the Runtime. If you frequently run Talend Data Mapper, these files may pile up and eventually lead to a disk full error. When the error occurs, the runtime fails. To avoid this, ensure that you perform periodical cleaning. For more information, see [Cleaning up temporary folders and files](https://help.qlik.com/talend/r/en-US/8.0/data-mapper-user-guide/cleaning-up-temporary-folders-and-files). **Related concepts** * [Generating the Output using tHMap with Multiple Payload Inputs](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-tfileinputraw-generating-output-using-thmap-with-multiple-payload-inputs-spark-batch-component "tHMap allows you to connect multiple payload inputs and generates the output in a single result. In this scenario, you will learn how to create a Job with a tHMap connected to a multiple inputs.") * [Generating the Output Using tHMap with Multiple Schema Inputs](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-trowgenerator-generating-output-using-thmap-with-multiple-schema-inputs-spark-batch-component "tHMap supports multiple inputs coming from either schema-based input connections or other raw file inputs. In this scenario, you can see how you can generate outputs using schema-based inputs with Main connections to the tHMap component.") * [Handling errors](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-tjava-tfixedflowinput-tjavarow-handling-errors-standard-component-enterprise-this) * [Transforming from a Data Integration schema to a complex content schema](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-trowgenerator-tfileoutputraw-tfileoutputraw-transforming-from-data-integration-schema-to-complex-content-schema-standard-component-enterprise-the) * [Using Talend Data Integration metadata](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-tfileinputdelimited-tfileoutputxml-tfileoutputxml-using-talend-data-integration-metadata-standard-component-enterprise-the) * [Using Talend Data Mapper metadata](https://help.qlik.com/talend/en-US/components/8.0/data-mapping/thmap-tfileinputraw-tfileoutputraw-tfileoutputraw-using-talend-data-mapper-metadata-standard-component-enterprise-the)