The Join Features tool adds attributes from one layer or table to another based on specified spatial and attribute relationships. Optionally, statistics can be calculated for the joined features.
The output is a hosted feature layer or a hosted table layer, depending on whether the input target layer is a table.
Example
You have data stored in a table that you need to display spatially. The table counts the number of Primary Health Centres (PHCs) in each state or union territory in India. The Join Features tool can be used to join the table to a feature layer so the PHC data can be shown spatially.
Try the Join a table to a feature layer in ArcGIS Online tutorial for the complete workflow.
Usage notes
Join Features includes configurations for input features, join settings, and a result layer.
Input features
The Input features group includes the following parameters:
Target layer specifies the layer or table that will have records appended to it. You can choose a layer using the Layer button, or you can create a sketch layer to use as the input using the Draw input features button.
For feature inputs, a count of features is displayed below the layer name. The count includes all features in the layer, except features that have been removed using a filter. Environment settings, such as Processing extent, are not reflected in the feature count.Join layer specifies the layer or table whose records will be appended to the target layer.
For feature inputs, a count of features is displayed below the layer name. The count includes all features in the layer, except features that have been removed using a filter. Environment settings, such as Processing extent, are not reflected in the feature count.
Join settings
The Join settings group includes the following parameters:
- Use spatial relationship determines whether a spatial join is created. If Use spatial relationship is turned off, Use attribute relationship must be enabled. This option is not available if one or more of the inputs is a table layer.
- Spatial relationship determines how spatial features are joined to each other. The available relationships depend on the geometry type (point, line, or polygon) of the layers being joined. Spatial relationship is available when Use spatial relationship is enabled. The options are as follows:
- Intersects—The features in the target layer will be matched if they intersect features in the join layer.
- Within a distance—The features in the join layer will be matched if they are within a specified distance of features in the target layer.
- Identical to—The features in the target layer will be matched if they are identical to features in the join layer.
- Completely contains—The features will be matched if the features in the target layer completely contain features in the join layer.
- Completely within—The features will be matched if the features in the target layer are completely within features of the join layer.
- Distance determines how close features in the join layer must be to features in the target layer to be joined to each other. Distance is available when Within a distance is chosen for Spatial relationship.
- Units are the distance units that determine how close features in the join layer must be to features in the target layer to be joined to each other. Units is available when Within a distance is chosen for Spatial relationship.
- Use attribute relationship determines whether an attribute join is created. If Use attribute relationship is turned off, Use spatial relationship must be enabled. Use attribute relationship is the only option when one or more of the inputs is a table layer.
- Attribute relationships determines how attributes are joined to each other. Attribute relationships is available when Use attribute relationship is enabled. The following subparameters are available:
- Target field—The field from the target layer that will be used to create the attribute join.
- Join field—The field from the join layer that will be used to create the attribute join.
Target field and Join field must contain matching values to create a valid join.
Additional target fields and join fields can be added to the join by clicking the Add button. - Join operation determines how joins between the target and join layers will be handled if multiple features in the join layer have the same relationship to the target layer. The options are as follows:
- Join one to one—Join a single record in the join layer to each feature in the target layer. This can either be the first record or a summary of all matching records, as determined by the Multiple matching records parameter.
- Join one to many—Join all the matching features in the join layer to the target layer. The result layer will contain multiple records of the target feature.
- Multiple matching records determines which records from the join layer will be used in a one-to-one join. Multiple matching records is available if Join one to one is chosen for Join operation. The options are as follows:
- Only keep first matching record—Only one matching record from the join layer will be used for each target feature. The matching record is determined by the Sort by parameter.
- Calculate field statistics—Calculate summary statistics for a chosen field for all records that match each feature in the target layer. The count of the summarized records will also be added by default.
- Calculate count only—Calculates the count of matching features without returning any other summary statistics.
Sort by determines how the first matching record is chosen. Sort by is available if Only keep first matching record is selected for Multiple matching records.
Sort by includes the following subparameters:- Field—Determines which field from the join layer is used to choose which matching record is kept. By default, the ObjectID field is used to keep the first matching record in the dataset. If a field is selected, the values from that field will be used to select which record is kept based on the Sort order parameter. Numeric and date fields are supported.
- Sort order—Determines whether the field will be sorted ascending or descending when choosing the first matching record.
Field statistics determines which number fields from the join layer will be summarized. Supported summary statistics include sum, minimum, maximum, mean, and standard deviation. The statistics are calculated for each target feature. Field statistics is available if Summarize matching records is selected for Multiple matching records.
Learn more about summary statistics- Join type determines whether the output will include only matching features, or all features from the target layer. The options are as follows:
- Inner join—Only matching features between the target layer and the join layer will be returned in the result layer.
- Left join—All features in the target layer will be returned regardless of whether they match features in the join layer.
Result layer
The Result layer group includes the following parameters:
- Output name specifies the name of the layer that is created and displayed. The name must be unique. If a layer with the same name already exists in your organization, the tool will fail and you will be prompted to use a different name.
- Save in folder specifies the name of a folder in My content where the result will be saved.
Limitations
The following limitations apply to the tool:
- Join Features cannot create outputs as hosted feature layer views. For information on how to create a hosted feature layer view, see Create hosted feature layer views.
- Field statistics can only be calculated if a Join one to one operation is specified.
- Joins cannot be created using fields that have a field type of ObjectID. If the values from an ObjectID field must be used in a join, you can create an integer field and calculate the field based on the ObjectID value.
- Attachments from the target layer or join layer are not included in the output layer.
- The Draw input features button is not available in Scene Viewer.
Environments
Analysis environment settings are additional parameters that affect a tool's results. You can access the tool's analysis environment settings from the Environment settings parameter group.
This tool honors the following analysis environments:
- Output coordinate system
- Processing extent
Note:
The default processing extent is Full extent. This default is different from Map Viewer Classic in which Use current map extent is enabled by default.
Credits
This tool consumes credits.
Use Estimate credits to calculate the number of credits that will be required to run the tool. For more information, see Understand credits for spatial analysis.
Outputs
The tool output includes one layer containing the original records from the target layer with the matching records from the join layer appended. The geometry of the output layer is the same as the geometry of the target layer. If the target layer is a table, the output will be a table.
Note:
Join Features cannot create outputs as hosted feature layer views. For information on how to create a hosted feature layer view, see Create hosted feature layer views.
Licensing requirements
This tool requires the following user type and configurations:
- Creator, Professional, or Professional Plus user type
- Publisher, Facilitator, or Administrator role, or an equivalent custom role
Resources
Use the following resources to learn more:
- Summary statistics
- Join Features in ArcGIS REST API
- join_features in ArcGIS API for Python
- Spatial Join in ArcGIS Pro
- Add Join in ArcGIS Pro
- Summary Statistics in ArcGIS Pro