ListBasedFeatureMerger
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.
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').
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.
When merging a Requestor and a Supplier, the attributes from the Supplier are merged onto the Requestor. 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.
Input Ports
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.
Output Ports
Requestors that have matching Suppliers for all of the keys in the specified Requestor List Attribute. In other words, only fully matched Requestors are output onto this port.
This port used to be labelled as Incomplete and has retained the semantics of that label. So, this port label is a shorthand for 'NotFullyMerged'. Partially matched Requestors are output onto this port, and all matching Suppliers are merged onto the output features if Incomplete Requestors is set to Merge Supplier Information. If a key in the Requestor List Attribute is null, that key will not match any Suppliers, and as a result, the Requestor feature will be output onto this port. For example, if the Requestor keys are:
list{0}.key = 1
list{1}.key = <null>
list{2}.key = 3
and furthermore there are Suppliers with 'supplierKey' values of 1, <null>, and 3, and Incomplete Requestors is set to Merge Supplier Information, then the Requestor will be output onto the UnmergedRequestor port, with Suppliers merged onto it whose 'supplierKey' is set to 1 or 3.
Suppliers that are merged onto at least one Requestor.
Suppliers that do not match any Requestors. If a Supplier Attribute key value is null or missing, that feature is output onto this port.
If Process Duplicate Suppliers is No, then duplicate suppliers will be rejected.
Parameters
Transformer
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.
Join Attributes
The list attribute on Requestor features whose keys will be matched against the Supplier Attribute on Supplier features.
The attribute on Supplier features that will be matched against the keys in the Requestor List Attribute for Requestor features.
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. If the numeric conversion fails, string comparison will be used.
Merge Parameters
To generate the completed feature, there will usually be a need to combine the all the supplier features that match the requestor. These choices are determined through the Feature Merge Type parameter:
- When the Feature Merge Type parameter is Attributes Only, then the Suppliers attributes will be joined to the attribution of the Requestor features using the specified Supplier List Name parameter.
- When the Feature 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 Feature 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. Attributes will be merged using the Supplier List Name Parameter.
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 <Rejected> 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.
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.
This parameter governs what happens to partially matched Requestors.
If this parameter is set to Merge Supplier Information, then the Suppliers that were found will be merged onto the Requestor and then output via the UnmergedRequestor port. The Suppliers used will be output via the UsedSuppliers port.
If this parameter is set to Do Not Merge Supplier Information, then the Requestor will be output untouched via the UnmergedRequestor port and the Suppliers will be output via the UnusedSupplier port.
Attribute Accumulation
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: 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.
Generate List
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.
Usage Notes
Relationship to InlineQuerier
The InlineQuerier is the powerful cousin of the ListBasedFeatureMerger. Whereas the ListBasedFeatureMerger joins two datasets and uses a simple, single attribute key to match features, the InlineQuerier allows any number of input datasets to be merged, using the full power of SQL across any number of tables and columns. Furthermore, the InlineQuerier allows its input data to be reused multiple times in a single transformer, whereas if multiple joins are to be done with a ListBasedFeatureMerger, multiple ListBasedFeatureMergers must be employed and copies of the features sent to each. On the other hand, there is some overhead for the InlineQuerier to load the underlying SQLite database. Using a single InlineQuerier instead of several ListBasedFeatureMergers also simplifies the workspace.
Unless only a single ListBasedFeatureMerger is needed in a workflow, the InlineQuerier may be a better choice. Older workspaces with multiple cascading ListBasedFeatureMergers may experience a performance improvement by replacing the ListBasedFeatureMergers 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 DatabaseJoiner
Relationship to FeatureMerger
This transformer 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, the FeatureMerger is the transformer of choice.
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.
Transformer Categories
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