FME Transformers: 2024.1

Filters and Joins
Related Transformers


Merges the attributes and/or geometry of one set of features onto another set of features, based on matching list attribute values with key attribute values and expressions.

Jump to Configuration

Typical Uses

  • Combining attributes and/or geometry from two different streams of features, based on a common key attribute value or expression, where the key of the receiving feature (Requestor) is stored as a list attribute.
  • Referencing a lookup table to a list attribute

How does it work?

The ListBasedFeatureMerger joins two feature streams based on a common key attribute or expression, where one of the key values is a list attribute. Every value in the list (on every feature) is considered for matching, as the transformer tests each list element in turn for a match.

It receives two the streams of features via its input ports.

Requestor:the features that will receive new attributes and/or geometry. The Requestor must have a list attribute that will be used as a key to join the Supplier(s).

Supplier: provide attributes and/or geometry to be merged onto the Requestors.

Matches between Requestor and Supplier are identified according to the Join Attributes configuration in the parameters dialog. A Requestor feature matches a Supplier feature when a key in the specified Requestor List Attribute (for example, list{}.key) matches the specified Supplier Attribute parameter (for example, supplierKey).

When a Requestor finds a matching Supplier, the attributes and/or geometry from the Supplier are merged with the Requestor.

The Incomplete Requestors parameter specifies whether or not to merge Suppliers onto partially matching Requestors when there are keys in the Requestor List Attribute that have no matching Suppliers. A Requestor feature is considered fully matched if every key in the Requestor List Attribute matches one or more Supplier features.

  • If the Requestor already has an attribute that the Supplier also has, the Requestor's original value for that attribute can be preserved or overridden.
  • A single Supplier may be used by many Requestors.
  • Many Suppliers can be merged onto a single Requestor.
  • When attribute names conflict, you can choose whether Requestor or Supplier attribute values are maintained by using the Conflict Resolution parameter, and whether null values follow the same behavior by using the Ignore Nulls parameter.


Usage Notes

  • The ListBasedFeatureMerger is a very specific instance of the FeatureMerger dealing with the case where the Requestor attribute is a list. If the requestor attribute is NOT a list, use the FeatureMerger or another joining method.

Choosing a Feature Joining Method

Many transformers can perform data joining based on matching attributes, expressions and/or geometry. When choosing one for a specific joining task, considerations include the complexity of the join, data format, indexing, conflict handling, and desired results. Some transformers use SQL syntax, and some access external databases directly. They may or may not support list attribute reading and creation.

Generally, choosing the one that is most specific to the task you need to accomplish will provide the optimal performance results. If there is more than one way to do it (which is frequently the case), time spent on performance testing alternate methods may be worthwhile. Performance may vary greatly depending on the existence of key indexes when reading external tables (as opposed to features already in the workspace).


Input Ports

Output Ports


Editing Transformer Parameters

Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.

For more information, see Transformer Parameter Menu Options.


Processing Behavior


Feature Holding


Dependencies None


FME Community

The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.

Search for all results about the ListBasedFeatureMerger on the FME Community.


Examples may contain information licensed under the Open Government Licence – Vancouver, Open Government Licence - British Columbia, and/or Open Government Licence – Canada.