The Join Features tool transfers attributes from the features in one feed, layer, or table to other features in the same feed or to those of another feed or dataset based on spatial, temporal, and attribute relationships, or some combination of the three. Optionally, statistics can be calculated for the joined features.
- An analyst has data on crime incidents in a city. To analyze and study the impact of these crimes, it is necessary to understand the relationship the crime locations have with various city jurisdictions such as school districts, police boundaries, and neighborhoods. By using the Join Features tool, additional information about each location can be appended to each crime and the impact on various jurisdictions can be further studied and analyzed.
- When a shipping vessel from one feed enters a moving severe weather cell of another feed, enrich the vessel with attributes from the severe weather event feature.
- When joining features, you can join features based on a spatial relationship, a temporal relationship, an attribute relationship, or a combination of the three.If multiple features match the same target feature, you can determine if all the matching features will be joined (Join one to many) or if all the matching features will be summarized together (Join one to one) as follows:
The spatial relationship that determines if features are joined to each other. The available relationships depend on the geometry type (point, line, or area) of the layers being joined. Available spatial relationships include:
- near planar
- near geodesic
The temporal relationship that determines if features are joined to each other. The available relationships depend on the time type (instant or interval) of the layers being joined. Available temporal relationships include:
- met by
- overlapped by
- finished by
- started by
The attribute relationship that determines if features are joined to each other. Features are matched when the field values in the join layer are equal to field values in the target layer.
- Join one to one—This option summarizes all of the matching join features to each feature in the target layer. Only the target features that have a match will be included in the output. The count of joined features will be added, in addition to other statistics such as sum, minimum, maximum, range, mean, variance, and standard deviation. Real-time analytics support one to one joins only. Summary statistics can only be calculated if a Join one to one operation is specified.
- Join one to many—This option joins all the matching features in the join layer to the target layer. The resulting layer will contain multiple records of the target feature. Big data analytics support both one to one and one to many joins.
Examples of a one-to-many and one-to-one join. In this example, the one-to-one join only includes the count; additional statistics that can be calculated are shown below in How Join Features works - Calculations.
When the Join operation parameter is set to Join one to many, there can be more than one row in the output feature class for each target feature.
- When configuring the Join Features tool in a one-to-one join, you can decide to only retain features that are joined or retain all features regardless of join results.
- If only retaining features that are joined, features will only be present in the output that were able to successfully joined with a feature from the join dataset.
- If retaining all features regardless of join results, all features from the target dataset will exist in the output, regardless of whether or not there were any joined attributes.
- When retaining all features, if a feature is retained but there was no join for that feature, the COUNT value will be 0 and any summary field attribute values will be null.
- This option is only available for one-to-one joins and is not available for one-to-many joins.
- If target and join features are in different coordinate systems, the coordinate systems of the target feature will be used.
- If a join feature has a spatial relationship with multiple target features, it is counted as many times as it is matched against the target feature. For example, if a point is within three polygons, the point is counted three times, once for each polygon.
- When the selected Spatial relationship is Near geodesic or Near planar, the Join Features tool requires the Target layer be projected or the output coordinate system be set to a projected coordinate system.
- Optionally build an expression by which to join features. If you specify an expression, only features that meet the condition will be used. For example, you could only join target features from the field Magnitude if greater than the join feature with a field named Explosion, using the expression $target["Magnitude"] > $join["Explosion"]. Learn more about Arcade expressions with Join Features.
- When the selected Spatial relationship is enter or exit in a real-time analytic,
- The tool will operate in a stateful manner which enables it to compare sequential observations to one another to detect a change in state, for example, is the current condition different from that of the previous observation. With other spatial relationships in real-time analytics, the tool does not need to compare any observations with previous ones so it can run in a stateless manner which is less resource intensive.
- Checking First observation can trigger enter or First observation can trigger exit indicates the first target feature received satisfies the filter condition if it is inside any join feature in the case of enter or outside in the case of exit, despite having no prior target feature to which to compare the current target feature's location. The default is false (unchecked).
- The Target Time Window parameter in real-time analytics should be at least as long as the longest anticipated interval between observations for any one track. Observations older than this duration will be purged from memory in order to manage resources.
- If a feed is connected to the join port, distance calculations will be done dynamically based on the changing features in both the target and join feeds.
- In dynamic geofencing, the Join Time Window parameter must be set. If the join feed does not have a field tagged as END_TIME and the last known observation for a join feature is older than this window, it will be purged from the tool's memory and will not be included in the analysis. If the join feed has a field tagged as END_TIME, the feature will age out of the geofence store according to the value in the field tagged as END_TIME or at the close of the join time window, whichever comes first.
- Join feeds must have a TRACK_ID configured.
- Adding a join feed to a tool must be done in the model view. Analytics with tools using join feeds cannot be viewed or edited in the workflow view.
- Dynamic geofencing is in beta for most configurations. The only currently released configuration is for Join Features. Configurations leveraging beta capabilities should not be used in production workflows.
How Join Features works
Statistics are calculated for only those features that meet the specified spatial, temporal, or attribute relationship used in the Join one to one operation. You can calculate numeric and string statistics. Using the image above, numeric statistics for the Occupants field and string statistics for the Building_Name field (where Type equals Apartment) would be as follows:
The target layer containing the features to process.
The layer whose features will be joined to those of the target layer.
Specifies whether the join should be one-to-one or one-to-many.
Retain all features
Specifies whether to retain only the features in successful join(s) or to retain all features regardless of whether or not there was a successful join for those features. This option is only available for one to one joins.
For one-to-many joins, this option is not available and only features with successful join(s) are returned.
If all features are retained, for features where there was not a join, the COUNT will be 0 and any summary field values will be null.
Specifies the criteria used to spatially join features. This parameter is available if Spatial is checked.
Spatial near distance
Join features within this specified distance of a target feature to be considered for the spatial join. A spatial near distance is only valid when the spatial relationship is Near geodesic or Near planar.
Specifies the time criteria used to match features. This parameter is available if Temporal is checked. Different temporal criteria are available depending upon Instant or Interval time features.
Temporal near distance
Specifies the amount of time between events. Joins will occur between events that occur within the time window of each other. This parameter is available if Temporal relationship is set to Near.
Joins features based on values within an attribute field. Specify which attribute field from the target layer matches an attribute field from the join layer. This parameter is available if Attribute is checked.
Specifies the statistics to be calculated on specified fields from the join features. Statistics are calculated for one-to-one joins. Different statistics are available depending on whether the specified field is a string, numeric, or date field.
Applies a condition to specified fields. Only features with fields that meet these conditions will be joined.
For example, you could apply a join to features where the attribute HealthSpending in the join layer is greater than 20 percent of the attribute Income in the target layer. The join condition to apply this expression is: $join["HealthSpending"] > $target["Income"] * .2
First observation can trigger enter/exit
Specifies whether the first target feature received satisfies the spatial relationship condition if it is inside any join feature in the case of Enter or outside all join features in the case of Exit, despite having no prior target feature to which to compare the current target feature's location. The default is false (unchecked).
Target Time window
Specify a value at least as long as the longest anticipated interval between observations for any given track. Observations older than this duration will be purged from memory in order to manage resources.
This parameter is only valid when Spatial relationship is set to Enter or Exit.
Join Time Window
The time window for the join feed (dynamic geofences). If the last known observation for a join feature is older than the time window specified, it will be purged and will not be included in the analysis. If the join feed has a field marked as END_TIME, this parameter is optional.
Dynamic geofencing is currently in beta and should not be used in production workflows.
Considerations and limitations
- Summary statistics will only be calculated if the Join one to one operation is specified.
- The COUNT field name will be used to represent the number of joined features for a one-to-one join. If the COUNT field name already exists in the target schema, the field will be called join_COUNT. If performing multiple consecutive joins, the field names will be COUNT, join_COUNT, join_COUNT1, join_COUNT2, and so on to avoid field name conflicts.