Join Features

Available in real-time and big data analytics.

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, you can calculate statistics for the joined features.

Workflow diagram

Examples

The following are example uses of the Join Features tool:

• 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. Using the Join Features tool, more 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.

Usage notes

Keep the following in mind when working with the Join Features tool:

• You can join features based on a spatial relationship, a temporal relationship, an attribute relationship, or a combination of the three.

  Option	Description
  Spatial relationship	The spatial relationship that determines whether 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 the following: Intersects Enter Equals Exit Near planar Near geodesic Contains Within Touches Crosses Overlaps Note: A target feature must satisfy its spatial relationship against all join features when exit has been specified and there is more than one join feature. For any other spatial relationship and where there is more than one join feature, a target feature can satisfy its spatial relationship to any individual join feature.
  Temporal relationship	The temporal relationship that determines whether 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 the following: Meets Met by Overlaps Overlapped by During Contains Equals Finishes Finished by Starts Started by Intersects Near
  Attribute relationship	The attribute relationship determines whether 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.

• If multiple features match the same target feature, you can determine whether all the matching features are joined (Join one to many) or whether all the matching features are summarized together (Join one to one) as follows:
  • Join one to one—This option summarizes all the matching join features to each feature in the target layer. Only the target features that have a match are included in the output. The count of joined features are added, as well as other statistics, such as sum, minimum, maximum, range, mean, variance, and standard deviation. 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 contains multiple records of the target feature.

    

    Examples of a one-to-many and one-to-one join are shown. In this example, the one-to-one join only includes the count; additional statistics that can be calculated are shown below.

    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 choose the only retain features that are joined or retain all features regardless of join results option.
  • If you choose only retain features that are joined, features that were able to successfully join with a feature from the join dataset are present in the output.
  • If you choose retain all features regardless of join results, all features from the target dataset exist in the output, regardless of whether 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 is zero and any summary field attribute values are null.
  • This option is only available for one-to-one joins.
• If target and join features are in different coordinate systems, the coordinate systems of the target feature are used.
• If a join feature has a spatial relationship with multiple target features, it is counted as many times as it is matched with the target feature. For example, if a point is within three polygons, the point is counted three times, once for each polygon.
• When Spatial relationship is set to Near geodesic or Near planar, the target layer must be projected or the output coordinate system mustbe set to a projected coordinate system.
• Optionally, build an expression to join features. If you specify an expression, only features that meet the condition are used. For example, you can only join target features from the Magnitude field if it is 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 Spatial relationship is set to enter or exit in a real-time analytic, the following are true:
  • The tool operates in a stateful manner, which enables it to compare sequential observations to one another to detect a change in state, for example, whether the current condition is 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 the previous observation, so it can run in a stateless manner, which is less resource intensive.
  • When operating in a stateful manner, the Join Features tool maintains a state store of the current observation for each track ID. When a new observation arrives, it is compared to the current observation of the same track ID, if present. If the new observation has a newer time stamp than the current observation in the state store, it replaces the current observation. If it has an identical time stamp to the current observation for the same track ID, the tool cannot distinguish between the two observations. This means the tool does not replace the current observation in the state store with the new observation, the new observation is not added to the state store, and future observations for this track ID are compared to the current observation that remained in the state store until a new observation arrives with a later time stamp. The tool logs a warning that this occurred.
  • Checking First observation can trigger enter or First observation can trigger exit indicates that 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 previous target feature to which to compare the current target feature's location. The default is false (not checked).
  • The Target Time Window parameter should be set to the longest anticipated interval between observations for any given track at a minimum. Observations older than this duration are deleted from memory to manage resources.
    • It is recommended that you set this value in excess, as a value that is too short can result in deleting records from the feature store before new observations arrive. This means the historical information is removed from the feature store and the next feature is treated as the initial observation. In other words, observations would never enter or exit the Join Features tool because the analytic would have no knowledge of the previous observation.
• 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 is deleted from the tool's memory and is not included in the analysis. If the join feed has a field tagged as END_TIME, the feature expires from the geofence store according to the value in the field tagged as END_TIME or when the join time window is closed, whichever comes first.
• 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.

Parameters

Keep the following in mind when working with the Join Features tool:

Parameter	Description	Data type
Target layer	The target layer containing the features to process.	Features
Join layer	The layer whose features are joined to those of the target layer.	Features
Join operation	Specifies whether the join is one-to-one or one-to-many. Join one to one—Joins always return the same number of results as the target features or fewer, if there are target features that do not match any join features. Attributes of the join features are summarized as specified in the Summary fields parameter. Join one to many—Joins return a record for each match between the target and join features. Attributes of the join features are not summarized.	String
Retain all features	Specifies whether only the features in successful joins are retained or all features are retained regardless of whether 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 joins are returned. If all features are retained, for features with no join, the count is zero and any summary field values are null.	String
Spatial relationship	Specifies the criteria used to spatially join features. Different Spatial criteria are available if this parameter is checked. Contains—The target feature entirely contains the join feature. Equals—The target feature equals the join feature. Intersects—The target feature shares any portion of its geometry with the join feature. Near geodesic—The distances between the target feature and join feature on a curved surface as opposed to their distance on a flat surface. Near planar—The distance between the target feature and join feature in a two-dimensional Cartesian plane. Within—The target feature is contained entirely within the join feature.	String
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 set to Near geodesic or Near planar.	Linear Unit
Temporal relationship	Specifies the time criteria used to match features. This parameter is available if Temporal is checked. Different temporal criteria are available depending on Instant or Interval time features. Meets—When a target time interval end is equal to the join time interval start, the target time meets the join time. Met by—When a target time interval start is equal to the join time interval end, the target time is met by the join time. Overlaps—When a target time interval starts and ends before the start and end of the join time interval, the target time overlaps the join time. Overlapped by—When a target time interval starts and ends after the start and end time of the join time interval, the target time is overlapped by the join time. During—When a target time occurs between the start and end of the join time interval, the target time is during the join time. Contains—When a join feature time occurs between the start and end of the target time interval, the target time contains the join time. Equals—Two times are considered equal if their instants or intervals are identical. Finishes—When a target time ends at the same time as a join time, and the target time started after the join time, the target time finishes the join time. Finished by—When a join feature time ends at the same time as a target time, and the join time started after the target time, the target time is finished by the join time. Starts—When a target time starts at the same time as the join time interval start, and ends before the join time interval ends, the target time starts the join time. Started by—When a target interval time starts at the same time as the join time and ends after the join time, the target time is started by the join time. Intersects—When any part of a target time occurs at the same time as the join time, the target time intersects the join time. Near—When a target time is within a specified range of time from the join time, the target time is near the join time. Near before—When a target time is before the join time but within a specified range of time from the join time, the target time is near before the join time. Near after—When a target time is after the join time but within a specified range of time from the join time, the target time is near after the join time.	String
Temporal near distance	The amount of time between events. Joins occur between events that occur within the time window of each other. This parameter is available if Temporal relationship is set to Near.	Time Unit
Attribute relationship	Joins features based on values in 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. Target field—An attribute field from the target layer containing values to match. Join field—An attribute field from the join layer containing values to match.	String
Summary fields	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. Any—A sample string from a string field type. Count—Calculates the number of non-null values. It can be used on numeric fields or strings. The count of [null, 0, 2] is 2. Count (distinct)—Calculates the number of distinct, non-null values. It can be used on numeric fields or strings. The count distinct result of [null, 4, 3, 4] is 2. Sum—The sum of numeric values in a field. The sum of [null, 1, 3] is 4. Square sum—The sum, over all observations, of the squared differences of each observation from the overall mean. The sum of squares of [null, 2.2, 3.1, 4.7] is 3.206. Min—The minimum value of a numeric field. The minimum of [0, 2, null] is 0. Max—The maximum value of a numeric field. The maximum value of [0, 2, null] is 2. Mean—The mean of numeric values. The mean of [0,2, null] is 1. Range—The range of a numeric field. This is calculated as the minimum value subtracted from the maximum value. The range of [0, null, 1] is 1. The range of [null, 4] is 0. Variance—The variance of a numeric field in a track. The variance of [1] is null. The variance of [null, 1,1,1] is 1. Standard Deviation—The standard deviation of a numeric field. The standard deviation of [1] is null. The standard deviation of [null, 1,1,1] is 1.	String
Join condition	Applies a condition to specified fields. Only features with fields that meet these conditions are joined. For example, you can apply a join to features in which the HealthSpending attribute in the join layer is greater than 20 percent of the Income attribute in the target layer. The join condition to apply this expression is $join["HealthSpending"] > $target["Income"] * .2.	String
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 previous target feature to which to compare the current target feature's location. The default is false (not checked).	Boolean
Change geometry of target feature to geometry of join feature	Changes the geometry of the target feature to the geometry of the join feature. For example, if the target feature is a point and the join feature it is joined with is a polygon, the target feature assumes the polygon geometry of the join feature. The default is false. If the target feature does not have a geometry, it assumes the geometry of the join feature it is joined with. If the target feature has a geometry and the join feature it is joined with does not have a geometry, the target feature loses its geometry and becomes tabular. Note: This parameter is not valid when Retain all features is set to true. Output features cannot have different geometries.	Boolean
Target Time window	This parameter should be set to the longest anticipated interval between observations for any given track at a minimum. Observations older than this duration are deleted from the memory to manage resources. This parameter is only valid when Spatial relationship is set to enter or exit.	String
Join Time window	The time window for the join feed (dynamic geofencing). If the last known observation for a join feature is older than the time window specified, it is deleted and is not included in the analysis. If the join feed has a field tagged as END_TIME, this parameter is optional.	String

Considerations and limitations

The following are the considerations and limitations to keep in mind when using the Join Features tool:

• Summary statistics are only calculated if the Join one to one operation is specified.
• The COUNT field name represents the number of joined features for a one-to-one join. If the COUNT field name exists in the target schema, the field is called join_COUNT. If you're performing multiple consecutive joins, the field names are COUNT, join_COUNT, join_COUNT1, join_COUNT2, and so on to avoid field name conflicts.