Append (Data Management)

Summary

Appends to, or optionally updates, an existing target dataset with multiple input datasets. Input datasets can be feature classes, tables, shapefiles, rasters, or annotation or dimension feature classes.

To combine input datasets into a new output dataset, use the Merge tool.

Illustration

Usage

• Use this tool to add new features or other data from multiple datasets to an existing dataset. This tool can append point, line, or polygon feature classes, tables, rasters, annotation feature classes, or dimension feature classes to an existing dataset of the same type. For example, several tables can be appended to an existing table, or several rasters can be appended to an existing raster dataset, but a line feature class cannot be appended to a point feature class.

• You can use the Field Map parameter to control how the attribute information from the input dataset fields is transferred to the target dataset. The Field Map parameter can only be used if Use the Field Map to reconcile schema differences is specified for the Schema Type parameter.

• To manage the fields in the output dataset and the contents of those fields, use the Field Map parameter.

  • The available merge rules are first, last, join, sum, mean, median, mode, minimum, maximum, standard deviation, and count.
  • When using the Join merge rule, you can specify a delimiter such as a space, comma, period, dash, and so on. To use a space, ensure that the pointer is at the start of the input box and press the Spacebar once.
  • You can specify the start and end positions of text fields using the format option.
  • Do not perform standard deviation on a single input because values cannot be divided by zero, so standard deviation is not a valid option for single inputs.

  Learn more about mapping fields in scripts

• This tool will not planarize features when they are added to the target dataset. All features from both the input feature class and the target feature class will remain intact after the append, even if the features overlap. To combine, or planarize, feature geometries, use the Union tool.

• If the Field Matching Type parameter is set to Input fields must match target fields, the schema of the input datasets must match that of the target dataset to append features.

  If the Field Matching Type parameter is set to Use the field map to reconcile field differences, the schema does not need to match. Fields from the input datasets that do not match the fields of the target dataset will not be mapped to the target dataset unless the mapping is set in the Field Map parameter. Fields in the target dataset that are not mapped to fields from the input datasets will contain null values.

  If the Field Matching Type parameter is set to Skip and warn if schema does not match, the schema of the input datasets must match that of the target dataset for features to be appended. If an input dataset contains fields that do not match fields in the target dataset, that input dataset will be omitted.

• Because the data of the input datasets is written to an existing target dataset that has a predefined schema , you can't use the Field Map parameter to add or remove fields from the target dataset.

• You can use this tool to insert new records and update existing records in a target dataset in the same operation (equivalent to an UPSERT database operation). Use the Matching Fields for Update parameter to specify the fields from the input dataset to match to the fields in the target dataset. For records with matching field values, any fields in the target record will be updated with values from fields with the same name in the input record. Geometry will be updated if the Update Geometry parameter is checked.

• If the spatial references of an input and target feature class do not match, the features in the input feature class will be projected to the coordinate system used by the target feature class.

• This tool does not perform edge matching; no adjustment to the geometry of features will be made.

• Map layers can be used as Input Datasets parameter values. If a layer has a selection, only the selected records (features or table rows) will be used.

• You can't use multiple input layers with the same name in this tool. Instead, use the tool dialog box browse button to browse to the full paths of each of the Input Datasets values.

• To use the Subtype parameter, the target dataset must have a defined subtype field and assigned subtype codes. In the Subtype parameter, provide a subtype description to assign that subtype to all new data that is appended to the target dataset.

• This tool can be used directly on the back-end data store, server, or database for web feature layers to ensure optimal performance. For feature services that reference a geodatabase, this tool can be used with a database connection to perform large data loading operations directly to the underlying database. For hosted services on ArcGIS Enterprise, you can use the append operation from the feature layer item page or ArcGIS REST API.

  For optimal performance with hosted services on ArcGIS Online, administrators and service owners can use this tool with the ArcGIS REST API when the supportAppend property is true. Feature service append capabilities must be enabled for nonadministrative users to use the Append tool with the ArcGIS REST API.

Parameters

Dialog

Label	Explanation	Data Type
Input Datasets	The input datasets containing the data to be appended to the target dataset. Input datasets can be point, line, or polygon feature classes, tables, rasters, annotation feature classes, or dimensions feature classes. Tables and feature classes can be combined. If a feature class is appended to a table, attributes will be transferred; however, the features will be dropped. If a table is appended to a feature class, the rows from the input table will have null geometry.	Table View; Raster Layer
Target Dataset	The existing dataset where the data of the input datasets will be appended.	Table View; Raster Layer
Field Matching Type (Optional)	Specifies whether the fields of the input dataset must match the fields of the target dataset for data to be appended. Input fields must match target fields—Fields from the input dataset must match the fields of the target dataset. An error will be returned if the fields do not match. Use the field map to reconcile field differences—Fields from the input dataset do not need to match the fields of the target dataset. Fields from the input datasets that do not match the fields of the target dataset will not be mapped to the target dataset unless the mapping is explicitly set in the Field Map parameter. Skip and warn if schema does not match—Fields from the input dataset must match the fields of the target dataset. If any of the input datasets contain fields that do not match the target dataset, that input dataset will be omitted with a warning message.	String
Field Map (Optional)	Controls how the attribute fields from the input datasets will be transferred or mapped to the target dataset. This parameter can only be used if the Field Matching Type parameter is set to Use the field map to reconcile field differences. Because the input datasets are appended to an existing target dataset that has predefined fields, you cannot add, remove, or change the type of the fields in the field map. You can set merge rules for each output field. Merge rules allow you to specify how values from two or more input fields will be merged or combined into a single output value. The following merge rules can be used to determine how the output field will be populated with values: First—Use the input fields' first value. Last—Use the input fields' last value. Join—Concatenate (join) the input field values. Sum—Calculate the total of the input field values. Mean—Calculate the mean (average) of the input field values. Median—Calculate the median (middle) of the input field values. Mode—Use the value with the highest frequency. Min—Use the minimum value of all the input field values. Max—Use the maximum value of all the input field values. Standard deviation—Use the standard deviation classification method on all the input field values. Count—Find the number of records included in the calculation.	Field Mappings
Subtype (Optional)	The subtype description that will be assigned to all new data that is appended to the target dataset.	String
Expression (Optional)	The SQL expression that will be used to select a subset of the input datasets' records. If multiple input datasets are specified, they will all be evaluated using the expression. If no records match the expression for an input dataset, no records from that dataset will be appended to the target. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS.	SQL Expression
Matching Fields for Update (Optional)	The fields from the input dataset that will be used to match to the target dataset. If the values of these fields match, records from the input dataset will update the corresponding records of the target dataset.	Value Table
Update Geometry (Optional)	Specifies whether geometry in the target dataset will be updated with geometry from the input dataset if the Matching Fields for Update parameter field values match. Checked—Geometry in the target dataset will be updated if the Matching Fields for Update parameter field values match. Unchecked—Geometry will not be updated. This is the default.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Target Dataset	The updated target dataset.	Table View; Raster Layer

Python

arcpy.management.Append(inputs, target, {schema_type}, {field_mapping}, {subtype}, {expression}, {match_fields}, {update_geometry})

Name	Explanation	Data Type
inputs [inputs,...]	The input datasets containing the data to be appended to the target dataset. Input datasets can be point, line, or polygon feature classes, tables, rasters, annotation feature classes, or dimensions feature classes. Tables and feature classes can be combined. If a feature class is appended to a table, attributes will be transferred; however, the features will be dropped. If a table is appended to a feature class, the rows from the input table will have null geometry.	Table View; Raster Layer
target	The existing dataset where the data of the input datasets will be appended.	Table View; Raster Layer
schema_type (Optional)	Specifies whether the fields of the input dataset must match the fields of the target dataset for data to be appended. TEST—Fields from the input dataset must match the fields of the target dataset. An error will be returned if the fields do not match. NO_TEST—Fields from the input dataset do not need to match the fields of the target dataset. Fields from the input datasets that do not match the fields of the target dataset will not be mapped to the target dataset unless the mapping is explicitly set in the Field Map parameter. TEST_AND_SKIP—Fields from the input dataset must match the fields of the target dataset. If any of the input datasets contain fields that do not match the target dataset, that input dataset will be omitted with a warning message.	String
field_mapping (Optional)	Controls how the attribute fields from the input datasets will be transferred or mapped to the target dataset. This parameter can only be used if the schema_type parameter is NO_TEST. Because the input datasets are appended to an existing target dataset that has predefined fields, you cannot add, remove, or change the type of the fields in the field map. You can set merge rules for each output field. Merge rules allow you to specify how values from two or more input fields will be merged or combined into a single output value. The following merge rules can be used to determine how the output field will be populated with values: First—Use the input fields' first value. Last—Use the input fields' last value. Join—Concatenate (join) the input field values. Sum—Calculate the total of the input field values. Mean—Calculate the mean (average) of the input field values. Median—Calculate the median (middle) of the input field values. Mode—Use the value with the highest frequency. Min—Use the minimum value of all the input field values. Max—Use the maximum value of all the input field values. Standard deviation—Use the standard deviation classification method on all the input field values. Count—Find the number of records included in the calculation. In Python, you can use the FieldMappings class to define this parameter.	Field Mappings
subtype (Optional)	The subtype description that will be assigned to all new data that is appended to the target dataset.	String
expression (Optional)	The SQL expression that will be used to select a subset of the input datasets' records. If multiple input datasets are specified, they will all be evaluated using the expression. If no records match the expression for an input dataset, no records from that dataset will be appended to the target. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS.	SQL Expression
match_fields [match_fields,...] (Optional)	The fields from the input dataset that will be used to match to the target dataset. If the values of these fields match, records from the input dataset will update the corresponding records of the target dataset.	Value Table
update_geometry (Optional)	Specifies whether geometry in the target dataset will be updated with geometry from the input dataset if the match_fields parameter field values match. UPDATE_GEOMETRY—Geometry in the target dataset will be updated if the match_fields parameter field values match. NOT_UPDATE_GEOMETRY—Geometry will not be updated. This is the default.	Boolean

Derived Output

Name	Explanation	Data Type
output	The updated target dataset.	Table View; Raster Layer

Code sample

Append example 1 (Python window)

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

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.management.Append(["north.shp", "south.shp", "east.shp", "west.shp"], 
                        "wholecity.shp", "TEST")

Append example 2 (Python window)

The following Python window script demonstrates how to use the Append function with the match_fields and update_geometry parameters in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/zoning.gdb"
arcpy.management.Append("Zoning_update_2040", "Zoning_2020", "TEST", 
                        match_fields=[["ZONEID", "ZONEID"]], update_geometry="UPDATE_GEOMETRY")

Append example 3 (stand-alone script)

The following script demonstrates how to use the Append function.

# Name: Append.py
# Description: Use the Append tool to combine several polygon feature classes

# Import system modules 
import arcpy
import os

# Set environment settings
arcpy.env.workspace = "C:/data/towns.gdb"

# Set local variables
outLocation = "C:/data/output.gdb"
outName = "MA_towns.shp"
schemaType = "NO_TEST"
fieldMappings = ""
subtype = ""

# Process: Append to an existing "amherst" polygon feature class
target = os.path.join(outLocation, "amherst")

# All polygon FCs in the workspace are MA town FCs, you want to append these
# to the target FC. The list will resemble ["amherst", "hadley", "pelham",
# "coldspring"]

fcList = arcpy.ListFeatureClasses("", "POLYGON")

# Create FieldMappings object to manage merge output fields
fieldMappings = arcpy.FieldMappings()

# Add the target table to the field mappings class to set the schema
fieldMappings.addTable(target)

# Add input fields for the town name to TOWNNAME field that matches the 
# target dataset since each input dataset has a different field name for 
# this info
fldMap = arcpy.FieldMap()
fldMap.addInputField("amherst","TOWNNAME")
fldMap.addInputField("hadley","NAME")
fldMap.addInputField("pelham","TOWN_NAME")
fldMap.addInputField("coldspring","TOWN")

# Set name of new output field "TOWNNAME"
townName = fldMap.outputField
townName.name, townName.aliasName, townName.type = "TOWNNAME", "TOWNNAME", "TEXT"
fldMap.outputField = townName

# Add output field to field mappings object
fieldMappings.addFieldMap(fldMap)

# Do the same thing for the POPULATION field
fldMap = arcpy.FieldMap()
fldMap.addInputField("amherst","POPULATION")
fldMap.addInputField("hadley","POP")
fldMap.addInputField("pelham","POP_2010")
fldMap.addInputField("coldspring","POP")

# Set name of new output field "POPULATION"
pop = fldMap.outputField
pop.name, pop.aliasName, pop.type = "POPULATION", "POPULATION", "LONG"
fldMap.outputField = pop

# Add output field to field mappings object
fieldMappings.addFieldMap(fldMap)

# Process: Append the feature classes to the target feature class
arcpy.management.Append(fcList, os.path.join(outLocation, "amherst"), schemaType, 
                        fieldMappings, subtype)

Environments

Extent, Current Workspace, Preserve Global IDs, Maintain Attachments

Special cases

Preserve Global IDs

For the Append tool, this environment only applies to enterprise geodatabase data and will only work on data that has a Global ID field with a unique index. If the Global ID field does not have a unique index, the tool may fail. To add a unique index to a Global ID field, you can use the Add Attribute Index tool.

Licensing information

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