Copies and merges the attributes/geometry from one feature (or multiple features) onto another feature (or multiple features). Features that contain the desired attributes/geometry are connected through the Supplier port, and the features that will receive the attributes/geometry are connected through the Requestor port.
When a Requestor finds a Supplier, the attributes from the Supplier are merged with the Requestor. If the Requestor already had an attribute that the Supplier also had, the Requestor's original value for that attribute can be preserved or overridden, depending on parameter settings. A single Supplier may be used by many Requestors. Many Suppliers can be merged onto a single Requestor.
Any merged geometry preserves arcs, ellipses and text.
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.
Note: Version Notes: In FME 2013 and prior, Requestor attributes were always more dominant than Supplier attributes when they were merged, except for null attribute values (represented by missing attribute values), which were always less dominant.
Note: In FME 2014, Requestor attributes were always more dominant than Supplier attributes when they were merged, inclusive of null attribute values (null support was added in FME 2014). To make null values less dominant, the recommendation was to remove null values with the NullAttributeMapper.
Note: In FME 2015 and later, the user can now choose whether Requestor or Supplier attributes should be more dominant through the parameter Conflict Resolution. The user can now also choose whether null values are as dominant as other attribute values through the parameter Ignore Nulls.
Requestor features match Supplier features when every pair of keys (which support expressions) specified in the Join On table has the same value for both the Requestor and Supplier features.
Receives the new attributes/geometry from the features connected to the Supplier port.
The source of new attributes/geometry for features that enter through the Requestor port.
Note that by setting Process Duplicate Suppliers to Yes, more than one Supplier may be merged to each Requestor. These Suppliers potentially could come from different sources (such as different database tables). See the Relationship to Joiner section at the end of this document.
Requestors that match a Supplier (or possible multiple Suppliers, if Process Duplicate Suppliers is set to Yes).
Requestors that do not match any Suppliers. If a Join On key is null or missing on a Requestor feature, that feature is output onto this port.
Suppliers that are found by at least one Requestor.
Note: A Supplier may still be output through this port even though none of its attributes were merged. This can occur because all of the attributes were already present in the Requestor or were provided by earlier Suppliers.
Suppliers that do not match any Requestors. If a Join On key is null or missing on a Supplier feature, that feature is output onto this port.
Supplier features with the same Join On expression values as an earlier Supplier feature. Note that duplicate Suppliers will only be output if Process Duplicate Suppliers is set to No. If Process Duplicate Suppliers is set to Yes, then duplicate Suppliers will be output via the Referenced port.
The input features may be partitioned by the Group By parameter. If you choose any Group By attributes, then references between features will only be resolved if they share a common value for the selected attributes.
If you do not choose any Group By attributes, all features are processed together.
If you have more than one Reader, a typical use is to group by reader_id to ensure that references are resolved within the correct set of features.
When this option is enabled, the transformer will assume that all Suppliers will enter the transformer before any Requestors. Once the first Requestor arrives, it will process and output Requestors as they come in. The Suppliers will be output after all the Requestors have been processed.
Note: It is the user’s responsibility to make sure all the Suppliers arrive before the Requestors. The transformer will stop accepting Suppliers once it receives its first Requestor when this option is enabled.
Specify an expression from the Requestor feature to match with the Supplier feature expression. An expression can be a constant, attribute value, function or mixture. Leading and trailing space characters are trimmed from the evaluated expressions. Matches are made when the trimmed values of all the Requestor expressions equal the trimmed values of their corresponding Supplier expressions.
Normally the Suppliers all have expressions that result in a unique match with a requestor and any duplicate Suppliers are ignored by the transformer. However, if the Process Duplicate Suppliers parameter is set to Yes, then all Suppliers whose expressions match their corresponding requestor expressions will be combined onto that Requestor.
The Comparison Mode column specifies how to perform the comparison between Requestor and Supplier attribute values. If Automatic or Numeric is specified, an attempt will be made to convert attribute values to numbers before comparing them.
This parameter specifies what to merge onto the completed feature. The choices are:
- When the Merge Type parameter is Attributes Only, then the Suppliers attributes will be joined to the attributes of the Requestor features.
- When the Merge Type parameter is Geometry, then the Suppliers are the features that contain the geometry. Note that the Requestor will lose its former geometry.
- When the Merge Type parameter is Attributes and Geometry, then both the geometry and attributes from the Suppliers are joined to the Requestor features. Any geometry on the Requestor will be overwritten.
If more than one Supplier is found for a given Requestor, and Process Duplicate Suppliers is No, then every Supplier after the first is output via the DuplicateSupplier port and only the first of the Suppliers will be matched with a Requestor.
If set to Yes, then the duplicate Suppliers are all matched with the corresponding Requestor merging attributes based on the Attribute Accumulation mode, and optionally output as an attribute list of the Requestor, using the specified List Name. The Supplier geometry is merged using the specified Geometry Merge Type.
If this parameter is set to Yes, any requestor feature that contains a null or missing join key would be immediately output onto the NotMerged port. Similarly, any supplier feature that contains a null or missing join key would be immediately output onto the Unreferenced port.
If this parameter is set to No, null and missing keys are treated like empty strings.
Specifies how to merge duplicate Suppliers onto the Requestor. It is applicable only if Feature Merge Type specifies to merge geometry. The choices are:
- Build Polygons: If the Suppliers consist exclusively of polygon and donut polygon features, any common border segments will be removed. If the Suppliers contain at least one non-donut or non-polygon feature, then the transformer will form polygons and donuts from the Suppliers and will join connected line segments of the Supplier features before setting the geometry of the Requestor feature. In this case, the geometry may be an aggregate if several disjoint geometries were created.
- Build Aggregates: The transformer will create an aggregate of the geometries of the Supplier features. (If there is only one Supplier feature, then the Requestor geometry will be an aggregate with one element.)
- Build Lines from Points: The transformer will connect the points of the Supplier features into lines. Note that any non-point features that are referenced will be ignored when building lines.
When viewed in 2D (ignoring Z), a path (which may define the border of a polygon) may appear to be closed as shown in the left figure below. This same path, when viewed in 3D, may appear to be open as shown in the right figure below.
To specify how (and if) paths should be closed in 3D, select one of the listed modes.
|Extend||The Curve is extended so that all vertices are left at their original location.|
|Average||Subsequent vertices that are not connected, but share an x and a y value are combined into one vertex, whose Z value is the average of the original two.|
|First Wins||Subsequent vertices that are not connected, but share an x and a y value are combined into one vertex, whose Z value is taken from the first encountered vertex.|
|Last Wins||Subsequent vertices that are not connected, but share an x and a y value are combined into one vertex, whose Z value is taken from the last encountered vertex.|
|Ignore||Z values are ignored. No change is made to the way the nodes are connected.|
Defines an attribute which will store the number of suppliers matched to that requestor.
If attributes on the supplier and requestor feature share the same name, but are not geometry attributes that start with fme_, then they are deemed conflicted.
Merge Supplier: The requestor feature will retain all of its own un-conflicted attributes, and will additionally acquire any un-conflicted attributes that the supplier feature has. This mode will handle conflicted attributes based on the Conflict Resolution parameter.
Prefix Supplier: The requestor feature will retain all of its own attributes. In addition, the requestor will acquire attributes reflecting the supplier feature’s attributes, with the name prefixed with the Prefix parameter.
Only Use Supplier: The requestor feature will have all of its attributes removed, except geometry attributes that start with fme_. Then, all of the attributes from one (arbitrary) supplier feature will be placed onto the requestor.
Use Requestor: If a conflict occurs, the requestor values will be maintained.
Use Supplier: If a conflict occurs, the values of the supplier will be transferred onto the requestor.
No: Treat null attribute values like other attribute values.
Yes: Treat null attribute values as less important than other attribute values. Whenever a null value is merged with a non-null value, the non-null value shall prevail, regardless of what Conflict Resolution is set to.
Note: Note: Null and other attribute values are always more dominant than missing attribute values. That is, whenever an attribute value is merged with a missing attribute value, the attribute value shall prevail, regardless of the Ignore Nulls and Conflict Resolution settings.
To prevent a Supplier attribute from being ignored because the Requestor attribute already exists, you can optionally specify a prefix that will be applied to each Supplier attribute when it is added to the Requestor.
When there are multiple Supplier features for a Requestor feature, multiple Supplier attribute values are merged into the same prefixed attribute. When multiple Supplier features have the same attribute, generally the resulting attribute value is taken from the last of these features. However, this process is governed by the Ignore Nulls parameter.
If there are duplicate Suppliers and a List Name is specified, then any Suppliers that are combined with a Requestor will have their attributes added to the specified list on the Requestor.
Note: List attributes are not accessible from the output schema in Workbench unless they are first processed using a transformer that operates on them, such as ListExploder or ListConcatenator. All list attribute transformers are displayed in the Contents pane of the Transformer Help under Lists. Alternatively, AttributeExposer can be used.
Relationship to InlineQuerier
Unless only a single FeatureMerger is needed in a workflow, the InlineQuerier may be a better choice. Older workspaces with multiple cascading FeatureMergers may experience a performance improvement by replacing the FeatureMergers with a single properly configured InlineQuerier.
Relationship to SQLCreator/SQLExecutor
If all the data to be queried already exists in a SQL-capable data source, it is always more efficient to use the SQLCreator or SQLExecutor, because this allows the queries and filtering of the data to be executed directly by the database before it enters the FME environment.
Relationship to Joiner
The Joiner merges input features to features from a single other source. Since more than one connection can be made to the FeatureMerger’s Supplier port, Suppliers could come from different sources and have different attribution, and by setting Process Duplicate Suppliers to Yes, the FeatureMerger can essentially be used to perform a multiple table join.
The FeatureMerger is also able to perform certain geometric operations on incoming features using its Merge Type parameter. FeatureMerger does all joins in memory so it can be faster than the Joiner if you have more than one relationship on the same data.
Relationship to ListBasedFeatureMerger
The ListBasedFeatureMerger is a specified use case of the FeatureMerger. It should be used if you want to join on a list attribute of the Requestor.
Relationship to Matcher
Matcher, via its SingleMatched output port, is capable of doing multi-feature merging with geometry as the key. This complements FeatureMerger, which only accepts attributes, and not geometries, as keys.
Editing Transformer Parameters
Using a set of menu options, transformer parameters can be assigned by referencing other elements in the workspace. More advanced functions, such as an advanced editor and an arithmetic editor, are also available in some transformers. To access a menu of these options, click beside the applicable parameter. For more information, see Transformer Parameter Menu Options.
Search FME Knowledge Center
Search for samples and information about this transformer on the FME Knowledge Center.
Tags Keywords: concatenated foreign key tag cross-reference "cross reference" FeatureMerger ReferenceResolver