Label | Explanation | Data Type |
Target Layer | Contains the target features. The attributes from the target features and the attributes from the joined features will be transferred to the output. | Table View |
Join Layer | Contains the join features. The attributes from the join features will be joined to the attributes of the target features. See the explanation for the Join Operation parameter for details about how the aggregation of joined attributes are affected by the type of join operation. | Table View |
Output Dataset | The new feature class containing the target layer features with joined features. | Feature Class;Table |
Join Operation | Specifies how joins between the Target Layer values and the Join Layer values will be handled in the output if multiple join features have the same spatial relationship with a single target feature.
| String |
Spatial Relationship (Optional) | Specifies the criteria that will be used to spatially join features.
| String |
Spatial Near Distance (Optional) |
The distance from a target feature within which join features will be considered for the spatial join. A search radius is only valid when the Spatial Relationship parameter value is Planar Near or Geodesic Near. | Linear Unit |
Temporal Relationship (Optional) | Specifies the time criteria that will be used to match features.
| String |
Temporal Near Distance (Optional) |
The distance in time from a target feature within which join features will be considered for the spatial join. A time is only valid when the Temporal Relationship parameter value is Near, Near Before, or Near After and both features are time enabled. | Time Unit |
Attribute Relationship (Optional) | Joins features based on values in an attribute field. Specify the attribute field from the target layer that matches an attribute field from the join layer.
| Value Table |
Summary Fields (Optional) | The statistics that will be calculated on specified fields. | 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 can apply a join condition to features in which the HealthSpending attribute in the join layer is more than 20 percent of the Income attribute in the target layer. Use an Arcade expression such as $join["HealthSpending"] > $target["Income"] * .2. | String |
Keep All Target Features (Optional) | Specifies whether all target features will be maintained in the output feature class (a left outer join) or only those that have the specified relationships with the join features (an inner join).
| Boolean |
Include Distance (Optional) | Specifies whether the spatial distance or the temporal difference will be included in the result. This parameter is active when the Join Operation parameter value is Join one to many and either of the following is true:
| Boolean |
Distance Unit (Optional) | Specifies the unit of measure that will be used for distance values in the output feature class.
| String |
Summary
Joins attributes from one layer to another based on spatial, temporal, or attribute relationships, or a combination of those relationships.
Illustration
Usage
A spatial join matches features (rows) from the input features (the Target Layer and Join Layer parameter values) based on their spatial locations. A temporal join matches features (rows) from the input features based on their temporal relationships. An attribute join matches features based on field values.
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 will determine 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 are as follows:
- Intersects
- Equals
- Planar Near—Uses planar distances
- Geodesic Near—Uses geodesic distances
- Contains
- Within
- Touches
- Crosses
- Overlaps
Learn more about spatial relationships in GeoAnalytics Desktop tools
Temporal Relationship
The temporal relationship that will determine 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 are as follows:
- Meets
- Met by
- Overlaps
- Overlapped by
- During
- Contains
- Equals
- Finishes
- Finished by
- Starts
- Started by
- Intersects
- Near
- Near Before
- Near After
Learn more about temporal relationships in GeoAnalytics Desktop tools
Attribute Relationship
The attribute relationship that will determine whether features are joined to each other. Features are matched when the field values in the join layer are equal to the field values in the target layer.
If target and join features are in different coordinate systems, the coordinate system of the target feature will be used. If an output coordinate system is specified, both features are projected to the output coordinate system and are then joined.
When the Spatial Relationship parameter value is Planar Near, the Target Layer parameter value must be projected or the output coordinate system must be set to a projected coordinate system.
If multiple features match the same target feature, you can decide whether all the matching features will be joined (a Join Operation value of Join one to many) or all the matching features will be summarized together (a Join Operation value of Join one to one) as follows:
- Join one to many—Joins all the matching features in the join layer to the target layer. The result layer will contain multiple records of the target feature.
- Join one to one—Summarizes all of the matching join features with each feature in the target layer. Only the features that have a match will be included in the summary and 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. By default, only those target features that have the specified relationships will be maintained in the output feature class (this is known as an inner join). If Keep All Target Features is checked, all input target features will be written to the output feature class (this is known as a left outer join).
You can build an expression to join features using the Join Condition parameter. If you specify an expression, only features that meet the condition will be used. For example, using the $target["Magnitude"] > $join["Explosion"] expression, you can only join target features from the Magnitude field if greater than the join feature with a field named Explosion. See Arcade expressions in GeoAnalytics Desktop tools for more information.
The following fields are included in the output features when running a one-to-many join:
- All fields from the target layers
- All fields from the joined layer
If the same field name exists in the target and join datasets, the joined field will start with the word join (for example join_fieldname).
Field name Description start_date
This field represents the start time and is created when the input has time set as an instant or interval.
end_date
This field represents the end time and is created when the input has time set as an interval.
In addition to all fields from the target layer, the following fields are included in the output features when running a one-to-one join:
Field name Description count
The count of features that have been joined.
statistic_fieldname
Specified statistics will each create an attribute field, named in the following format: statistic_fieldname. For example, the maximum and standard deviation of the id field is MAX_id and SD_id.
start_date
This field represents the start time and is created when the input has time set as an instant or interval.
end_date
This field represents the end time and is created when the input has time set as an interval.
If the Include Distance parameter is checked and the Join Operation parameter is set to Join one to many, the following fields may be included in the output features:
Field name Description distance
The distance between target and join features. This field is included if the Spatial Relationship parameter is Planar Near or Geodesic Near.
A distance of 0 indicates that the target and join geometries intersect. A null value indicates that the geometries are farther apart than the Spatial Near Distance parameter value. If the Spatial Relationship parameter value is Planar Near, the distance values will be planar; if the parameter value is Geodesic Near, the distance values will be geodesic. The values will be in the units specified by the Distance Unit parameter. The default distance unit is meters.
timegap
The temporal difference between the target and join features in milliseconds. This field is included if the Temporal Relationship parameter is Near, Near Before, or Near After.
A difference of 0 indicates that the target and join features temporally intersect. Positive values mean the target feature occurs before the join feature, and negative values mean the join feature occurs before the target feature. Null values indicate that the features did not meet the join condition. For example, the features are farther apart than the Temporal Near Distance parameter value.
You can improve performance of the Join Features tool by doing one or more of the following:
- Set the extent environment so that you only analyze data of interest.
- Make the join conditions as selective as possible. For example, a near join of 1 kilometer will perform better than a near join of 5 kilometers on the same data.
- Add more than one join condition. Additional join conditions make the join more selective. For example, a near join of 1 kilometer and 1 hour will perform better than a near join of 1 kilometer on the same data.
- Apply a join expression.
- Use data that is local to where the analysis is being run.
Similar analysis can also be completed using the Spatial Join tool in the Analysis toolbox.
This geoprocessing tool is powered by Spark. Analysis is completed on your desktop machine using multiple cores in parallel. See Considerations for GeoAnalytics Desktop tools to learn more about running analysis.
When running GeoAnalytics Desktop tools, the analysis is completed on your desktop machine. For optimal performance, data should be available on your desktop. If you are using a hosted feature layer, it is recommended that you use ArcGIS GeoAnalytics Server. If your data isn't local, it will take longer to run a tool. To use your ArcGIS GeoAnalytics Server to perform analysis, see GeoAnalytics Tools.
Parameters
arcpy.gapro.JoinFeatures(target_layer, join_layer, output, join_operation, {spatial_relationship}, {spatial_near_distance}, {temporal_relationship}, {temporal_near_distance}, {attribute_relationship}, {summary_fields}, {join_condition}, {keep_all_target_features}, {include_distance}, {distance_unit})
Name | Explanation | Data Type |
target_layer | Contains the target features. The attributes from the target features and the attributes from the joined features will be transferred to the output. | Table View |
join_layer | Contains the join features. The attributes from the join features will be joined to the attributes of the target features. See the explanation for the Join Operation parameter for details about how the aggregation of joined attributes are affected by the type of join operation. | Table View |
output | The new feature class containing the target layer features with joined features. | Feature Class;Table |
join_operation | Specifies how joins between the target_layer values and join_layer values will be handled in the output feature if multiple join features have the same spatial relationship with a single target feature.
| String |
spatial_relationship (Optional) | Specifies the criteria that will be used to spatially join features.
| String |
spatial_near_distance (Optional) |
The distance from a target feature within which join features will be considered for the spatial join. A search radius is only valid when the spatial_relationship parameter value is NEAR or NEAR_GEODESIC. | Linear Unit |
temporal_relationship (Optional) | Specifies the time criteria that will be used to match features.
| String |
temporal_near_distance (Optional) |
The distance in time from a target feature within which join features will be considered for the spatial join. A time is only valid when the temporal_relationship parameter value is NEAR, NEAR_BEFORE, or NEAR_AFTER and both feature are time enabled. | Time Unit |
attribute_relationship [attribute_relationship,...] (Optional) | Joins features based on values in an attribute field. Specify the attribute field from the target layer that matches an attribute field from the join layer.
| Value Table |
summary_fields [summary_fields,...] (Optional) | The statistics that will be calculated on specified fields.
| 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 can apply a join condition to features in which the HealthSpending attribute in the join layer is more than 20 percent of the Income attribute in the target layer. Use an Arcade expression such as $join["HealthSpending"] > $target["Income"] * .2. | String |
keep_all_target_features (Optional) | Specifies whether all target features will be maintained in the output feature class (a left outer join) or only those that have the specified relationships with the join features (an inner join).
| Boolean |
include_distance (Optional) | Specifies whether the spatial distance or the temporal difference will be included in the result. This parameter is active when the join_operation parameter value is JOIN_ONE_TO_MANY and either of the following is true:
| Boolean |
distance_unit (Optional) | Specifies the unit of measure that will be used for distance values in the output feature class.
| String |
Code sample
The following stand-alone script demonstrates how to use the JoinFeatures function.
# 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).
# Import system modules
import arcpy
arcpy.env.workspace = "C:/data/CityData.gdb"
# Enable time on the input features using an .lyrx file.
# To create the .lyrx file, add your layer to a map, open the layer properties
# and enable time. Then right-click the layer and select Share As Layer File.
inputLyrx = r'C:\data\ChicagoCrimes.lyrx'
# MakeFeatureLayer converts the .lyrx to features
chicagoCrimesLayer = arcpy.management.MakeFeatureLayer(inputLyrx, "Crimes_layer")
# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.management.ApplySymbologyFromLayer(chicagoCrimesLayer, inputLyrx)
# Set local variables
spatialOperation = "NEAR"
nearDistance = "1 Kilometers"
temporalOperation = "NEAR"
nearTime = "3 Hours"
out = "CloseCrimes"
# Run Join Features
arcpy.gapro.JoinFeatures(chicagoCrimesLayer, inFeatures, out, "JOIN_ONE_TO_ONE",
spatialOperation, nearDistance, temporalOperation,
nearTime)
Environments
Licensing information
- Basic: No
- Standard: No
- Advanced: Yes