Skip To Content

Add Join


Joins a layer to another layer or table based on a common field. Feature layers, table views, and raster layers with a raster attribute table are supported.

The records in the Join Table are matched to the records in the input Layer Name. A match is made when the input join field and output join field values are equal. This join is temporary.


Add Join


  • The input must be a feature layer, a table view, or a raster layer with an attribute table.

  • If the input is a feature class or dataset path, this tool will automatically create and return a new layer with the result of the tool applied.

  • Records from the Join Table can be matched to more than one record in the input layer or table view.

  • When joining tables, the default option is to keep all records. If a record in the target table doesn't have a match in the join table, that record is given null values for all the fields being appended into the target table from the join table.

    Example of keeping all records with a join

    With the keep only matching records option, if a record in the target table doesn't have a match in the join table, that record is removed from the resultant target table. If the target table is the attribute table of a layer, features that don't have data joined to them are not shown on the map.

    Example of keeping only matching records with a join

  • The input layer or table view must have an ObjectID field. The Join Table is not required to contain an ObjectID field.

  • Field properties, such as aliases, visibility, and number formatting, are maintained when a join is added or removed.

  • If a join with the same table name already exists—for example, if the layer A is joined to a table B—running the tool again to join table B will result in a warning that the join already exists.

  • The join lasts only for the duration of the session. To persist the join for use in another session, save the layer to a layer file using the Save Layer To File tool. This only applies to layers; table views cannot be saved in this manner.

  • In the resulting layer or table view, the fields from the input layer or table view will be prefixed with the input's name and a period (.), and all fields from the join table will be prefixed with the join table name plus a period as the default.

    • For example, joining landuse, which has fields A and B to lookup_tab, which has fields C and D, will result in a layer or table view with the following fields: landuse.A, landuse.B, lookup_tab.C, and lookup_tab.D.
    • For coverage feature classes and INFO tables, the table and field name separator is a colon (:) instead of a period.

  • To make a permanent join, consider using the Join Field tool. Another way to make the join permanent is to save the joined feature layer to a new feature class or the joined table view to a new table. When saving results to a new feature class or table, you can use the Qualified Field Names environment to control whether the joined output field names will be qualified with the name of the table the field came from.

  • Indexing the fields in the input layer or table view and Join Table on which the join will be based can improve performance. This can be done with the Add Attribute Index tool.

  • If the input layer or table view's fields were modified (renamed or hidden) using the Make Feature Layer or Make Table View tool Field Info parameter, these field modifications will not be carried forward to the output joined layer or table view.

  • The Join Table name cannot start with a numeric value.


AddJoin_management (in_layer_or_view, in_field, join_table, join_field, {join_type})
ParameterExplanationData Type

The layer or table view to which the join table will be joined.

Mosaic Layer; Raster Layer; Table View

The field in the input layer or table view on which the join will be based.


The table or table view to be joined to the input layer or table view.

Mosaic Layer; Raster Layer; Table View

The field in the join table that contains the values on which the join will be based.


Specifies what will be done with records in the input that match a record in the join table.

  • KEEP_ALLAll records in the input layer or table view will be included in the output—also known as an outer join. This is the default.
  • KEEP_COMMONOnly those records in the input that match a row in the join table will be present in the result—also known as an inner join.

Derived Output

NameExplanationData Type

The updated input dataset.

Table View; Raster Layer; Mosaic Layer

Code sample

AddJoin example 1 (Python window)

The following Python window script demonstrates how to use the AddJoin function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/Habitat_Analysis.gdb"
veg_joined_table = arcpy.AddJoin_management("vegetation", "HOLLAND95", 
                                            "vegtable", "HOLLAND95")
arcpy.CopyFeatures_management(veg_joined_table, "vegjoin")
AddJoin example 2 (stand-alone script)

This stand-alone script shows the AddJoin function as part of a workflow to join a table to a feature class, then extract desired features.

# Name:
# Purpose: Join a table to a featureclass and select the desired attributes

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data/Habitat_Analysis.gdb"
arcpy.env.qualifiedFieldNames = False
# Set local variables    
inFeatures = "vegtype"
joinTable = "vegtable"
joinField = "HOLLAND95"
expression = "vegtable.HABITAT = 1"
outFeature = "vegjoin"
# Join the feature layer to a table
veg_joined_table = arcpy.AddJoin_management(inFeatures, joinField, joinTable, 
# Select desired features from veg_layer
arcpy.SelectLayerByAttribute_management(veg_joined_table, "NEW_SELECTION", 
# Copy the layer to a new permanent feature class
arcpy.CopyFeatures_management(veg_joined_table, outFeature)

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics