Skip To Content

Join Features

Summary

Joins attributes from one layer to another based on spatial, temporal, or attribute relationships, or a combination of those relationships.

Illustration

Join Features Tool
Join Features: both examples show a spatiotemporal join.

Usage

  • A spatial join involves matching features (rows) from the input features (named Target Layer and Join Layer) based on their spatial locations. A temporal join involves matching features (rows) from the input features based on their temporal relationships. An attribute join involves matching features based on values in fields.

  • If target and join features are in different coordinate systems, the coordinate systems of the target feature will be used. If an output coordinate system is specified, both features are projected to the output coordinate system and then joined.

  • When the Join Operation parameter is Join one to many, there can be more than one row in the output feature class for each target feature.

  • 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, Join Features requires that the Target Layer is projected or that the output coordinate system is set to a Projected Coordinate System

  • You can use an Arcade expression to create a Join Condition. Only features that meet the join condition will be used in the analysis. See Join Features expressions for more information.

  • This geoprocessing tool is powered by ArcGIS GeoAnalytics Server. Analysis is completed on your GeoAnalytics Server and results are stored in your content in ArcGIS Enterprise.

  • It is recommended that you use feature layers hosted on your ArcGIS Enterprise portal or use a big data file share data when running GeoAnalytics Tools in ArcGIS Pro. Other data sources may perform slowly when there are more than 1000 features.

    Learn more about sharing data to your portal

    Learn more about creating a big data file share through Server Manager

  • Similar analysis can also be completed using the Spatial Join tool in the Analysis toolbox.

Syntax

JoinFeatures_geoanalytics (target_layer, join_layer, output_name, join_operation, {spatial_relationship}, {spatial_near_distance}, {temporal_relationship}, {temporal_near_distance}, {attribute_relationship}, {summary_fields}, {join_condition}, {data_store})
ParameterExplanationData Type
target_layer

Attributes of the target features and the attributes from the joined features are transferred to the output.

Record Set
join_layer

The attributes from the join features are joined to the attributes of the target features. See the explanation of the Join Operation (join_operation for Python) parameter for details on how the aggregation of joined attributes are affected by the type of join operation.

Record Set
output_name

The name of the output feature service.

String
join_operation

Determines how joins between the target_layer and join_layer will be handled in the output feature if multiple join features are found that have the same spatial relationship with a single target feature.

  • JOIN_ONE_TO_ONE The attributes from the multiple join features will be aggregated. For example, if a point target feature is found within two separate polygon join features, the attributes from the two polygons will be aggregated before being transferred to the output point feature class. If one polygon has an attribute value of 3 and the other has a value of 7, and the summary statistic sum is specified for that field, the aggregated value in the output feature class will be 10. The default is that only the count statistics is returned. Join one to one is the default.
  • JOIN_ONE_TO_MANYThe output feature class will contain multiple copies (records) of the target feature. For example, if a single-point target feature is found within two separate polygon join features, the output feature class will contain two copies of the target feature: one record with the attributes of one polygon and another record with the attributes of the other polygon. There are no summary statistics available with this method.
String
spatial_relationship
(Optional)

Defines the criteria used to spatially join features.

  • INTERSECTSThe features in the join features will be matched if they intersect a target feature. This is the default.
  • EQUALSThe features in the join features will be matched if they are the same geometry as a target feature.
  • NEARThe features in the join features will be matched if they are within a specified distance of a target feature. Specify a distance in the spatial near distance parameter.
  • CONTAINSThe features in the join features will be matched if a target feature contains them. The target features must be polygons or polylines. The join features can only be polygons when the target features are also polygons. Polygon can contain any feature type. Polyline can contain only polyline and point. Point cannot contain any feature, not even a point. If the join feature is entirely on the boundary of the target feature (no part is properly inside or outside), the feature will not be matched.
  • WITHINThe features in the join features will be matched if a target feature is within them. It is the opposite of the contains relationship. For this option, the target features can only be polygons when the join features are also polygons. Point can be a join feature only if point is also a target feature. If the entirety of the feature in the join features is on the boundary of the target feature, the feature will not be matched.
  • TOUCHESThe features in the join features will be matched if they have a boundary that touches a target feature. When the target and join features are lines or polygons, the boundary of the join feature can only touch the boundary of the target feature and no part of the join feature can cross the boundary of the target feature.
  • CROSSESThe features in the join features will be matched if a target feature is crossed by their outline. The join and target features must be lines or polygons. If polygons are used for the join or target features, the polygon's boundary (line) will be used. Lines that cross at a point will be matched, but lines that share a line segment will not.
  • OVERLAPSThe features in the join features will be matched if they overlap a target feature.
String
spatial_near_distance
(Optional)

Join features within this distance of a target feature will be considered for the spatial join. A search radius is only valid when the spatial_relationship is NEAR.

Linear Unit
temporal_relationship
(Optional)

Defines the time criteria used to match features.

  • MEETSWhen a target time interval end is equal to the join time interval start, the target time meets the join time.
  • MET_BYWhen a target time interval start is equal to the join time interval end, the target time is met by the join time.
  • OVERLAPSWhen 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_BYWhen 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.
  • DURINGWhen a target time occurs between the start and end of the join time interval, the target time is during the join time.
  • CONTAINSWhen a join feature time occurs between the start and end of the target time interval, the target time contains the join time.
  • EQUALSTwo times are considered equal if their instants or intervals are identical.
  • FINISHESWhen 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_BYWhen 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.
  • STARTSWhen 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_BYWhen 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.
  • INTERSECTSWhen any part of a target time occurs at the same time as the join time, the target time intersects the join time.
  • NEARWhen a target time is within a specified range of time from the join time, the target time is near the join time.
  • NEAR_BEFOREWhen 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. This option is available with ArcGIS Enterprise 10.6 or later.
  • NEAR_AFTERWhen 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. This option is available with ArcGIS Enterprise 10.6 or later.
String
temporal_near_distance
(Optional)

Join features within this distance in time of a target feature will be considered for the spatial join. A time is only valid when the temporal_relationship is NEAR, NEAR_BEFORE, or NEAR_AFTER and both feature are time enabled.

Time unit
attribute_relationship
[attribute_relationship,...]
(Optional)

Join features based on values within an attribute field. You must specify which attribute field from the target layer matches an attribute field from the join layer.

  • 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.

Value Table
summary_fields
[summary_fields,...]
(Optional)

Statistics that will be calculated on specified fields.

  • COUNTCalculates the number of nonnull values. It can be used on numeric fields or strings. The count of [null, 0, 2] is 2.
  • SUMThe sum of numeric values in a field. The sum of [null, null, 3] is 3.
  • MEANThe mean of numeric values. The mean of [0, 2, null] is 1.
  • MINThe minimum value of a numeric field. The minimum of [0, 2, null] is 0.
  • MAXThe maximum value of a numeric field. The maximum value of [0, 2, null] is 2.
  • STDDEVThe standard deviation of a numeric field. The standard deviation of [1] is null. The standard deviation of [null, 1,1,1] is 1.
  • VARThe variance of a numeric field in a track. The variance of [1] is null. The variance of [null, 1, 1, 1] is 1.
  • RANGEThe range of a numeric field. This is calculated as the minimum values subtracted form the maximum value. The range of [0, null, 1] is 1. The range of [null, 4] is 0.
  • ANYThis is a sample string from a field of type string.
Value Table
join_condition
(Optional)

Applies a condition to specified fields. Only features with fields that meet these conditions will be joined.

For example, you could apply a join condition to features where the attribute HealthSpending in the join layer is greater than 20 percent of the attribute Income in the target layer. At 10.5 and 10.5.1, the join condition to apply this expression is join["HealthSpending"] > target["Income"] * .2. At 10.6 and later, use an Arcade expression such as $join["HealthSpending"] > $target["Income"] * .2.

String
data_store
(Optional)

Specifies the ArcGIS Data Store where the output will be saved. The default is SPATIOTEMPORAL_DATA_STORE. All results stored to the SPATIOTEMPORAL_DATA_STORE will be stored in WGS84. Results stored in a RELATIONAL_DATA_STORE will maintain their coordinate system.

  • SPATIOTEMPORAL_DATA_STOREOutput will be stored in a spatiotemporal big data store. This is the default.
  • RELATIONAL_DATA_STOREOutput will be stored in a relational data store.
String

Code sample

JoinFeatures example (Python window)

The following Python window script demonstrates how to use the JoinFeatures tool.

#-------------------------------------------------------------------------------
# Name: JoinFeatures.py
# Description: Join crime events that are close together in time and space, and return the count of nearby crimes 
# This example is a self join (joining the same layer to itself) 
# Requirements: ArcGIS GeoAnalytics Server 

# Import system modules 
import arcpy 

# Set local variables 
inFeatures = "https://MyGeoAnalyticsMachine.domain.com/geoanalytics/rest/services/DataStoreCatalogs/bigDataFileShares_Crimes/BigDataCatalogServer/Chicago"
spatialOperation = "NEAR" 
nearDistance = "1 Kilometers" 
temporalOperation = "NEAR" 
nearTime = "3 Hours" 
outFS = "CloseCrimes" 
dataStore = "SPATIOTEMPORAL_DATA_STORE" 

# Execute Join Features
arcpy.geoanalytics.JoinFeatures(inFeatures, inFeatures, outFS, "JOIN_ONE_TO_ONE", 
                                spatialOperation, nearDistance, temporalOperation, 
                                nearTime, None, None, None, dataStore)

Environments

Output Coordinate System

The coordinate system that will be used for analysis. Analysis will be completed on the input coordinate system unless specified by this parameter. For GeoAnalytics Tools, final results will be stored in the spatiotemporal data store in WGS84.

Licensing information

  • ArcGIS Desktop Basic: Requires ArcGIS GeoAnalytics Server
  • ArcGIS Desktop Standard: Requires ArcGIS GeoAnalytics Server
  • ArcGIS Desktop Advanced: Requires ArcGIS GeoAnalytics Server

Related topics