Append (Data Management Tools)

Summary

Appends to, and 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. The inputs can also be hosted feature services.

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

Illustration

Append 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.
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 field differences is specified for the Field Matching Type parameter.
Use the Field Map parameter to map or match the fields from the input datasets to fields in the target dataset.
- Use an action to determine how the values from one or multiple fields from the input dataset will be mapped to a single field from the target dataset.
- The available actions are First, Last, Concatenate, Sum, Mean, Median, Mode, Minimum, Maximum, Standard Deviation, and Count.
- When using the Concatenate action, you can specify a delimiter such as a comma or other characters. Click the start of the Delimiter text box to add the delimiter characters.
- Standard Deviation is not a valid option for single input values.
- Use the Export option to save a field map as a .fieldmap file.
- Use the Load option to load a .fieldmap file. The feature layer or dataset specified in the file must match the dataset used in the tool. Otherwise, the Field Map parameter will be reset.
- Use the Slice Text button on text source fields to choose which characters from an input value will be extracted to the target field. To access the Slice Text button, hover over a text field in the input fields list; then specify the start and end character positions.
- Fields can also be mapped in a Python script.
In Python, when using the FieldMappings object for the field_mapping parameter, add the fields from the target dataset first as shown in the code below. Input fields are mapped to the schema of the target fields. When the input fields are added first, the field map may reset or behave unexpectedly.
```
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(target)
fieldmappings.addTable(input)
```
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.
The number of appended rows are displayed in the tool messages and returned by the Appended Row Count output.
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. The number of updated rows with matched fields will be displayed in the tool messages and returned by the Updated Row Count output. Geometry will be updated if the Update Geometry parameter is checked.
The input and target datasets may have different spatial references. When this is the case, the tool projects the input features to the target's coordinate system. For best results, specify an appropriate geographic transformation using the Geographic Transformations environment. If the target dataset is a map layer, the tool may apply a default transformation. In Python, there is no default transformation.
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 browse button in the Geoprocessing pane to browse to the full paths of each of the Input Datasets values.
If an input dataset and the target dataset have the same name, the tool will have reduced performance.
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.
Use the Enforce Domains parameter to enforce attribute domains for fields in the target dataset. When this parameter is checked, the tool will honor the domain values defined in the target dataset. Data from the input fields that do not conform to these domain values will be inserted as Null values.
The following relate to updating the target dataset fields:
- 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.
- By default, for records that contain matching field values, fields in the target record will be updated with values from the input if they have the same field name. The number of updated rows with matched fields will be displayed in the tool messages and returned by the derived Updated Row Count parameter.
- The Candidate Fields parameter can be used to selectively update or insert fields in the target dataset. For example, for a target dataset that contains fields named f1, f2, f3, and f4, you can specify that only the f3 and f4 fields will be updated for target rows. For insert operations, only the f3 and f4 fields will be inserted.
- Geometry will be updated if the Update Geometry parameter is checked.
- To update only geometry and not attribute fields in the target dataset, ensure that that the Update Geometry parameter is checked and that the Shape field is the only field specified in the Candidate Fields parameter. If the target is a feature service, see further below in the Usage section.
- The Skip Options parameter has the following options to control the behavior of updated and inserted rows:
  - Do not skip updates or inserts—All rows with matching fields will be updated in the target, and all unmatched rows from the input will be inserted.
  - Skip inserts for unmatched rows (update only)—All rows with matching fields will be updated in the target. Unmatched rows from the input dataset will not be inserted.
  - Skip updates for matched rows (insert only)—No rows with matching fields will be updated in the target. Only unmatched rows from the input will be inserted.
The following relate to feature services:
- For optimal performance, use this tool directly on the back-end data store, server, or database for web feature layers. For feature services that reference a geodatabase, use a database connection to perform large data loading operations directly to the underlying database. For hosted services on ArcGIS Enterprise, use the append operation from the feature layer item page or ArcGIS REST API.
- For optimal performance with hosted services on ArcGIS Online and ArcGIS Enterprise, 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 users who are not administrators to use this tool with the ArcGIS REST API. For ArcGIS Enterprise hosted feature layers, the Uploads capability must be enabled.
- The Optimize performance for feature services parameter is only supported when the target dataset supports feature service append capabilities. When this parameter is checked, the tool will do the following:
  - The tool will use the ArcGIS REST API for optimal performance.
  - The Input Datasets parameter will be limited to one dataset.
  - The Expression and Enforce Domains parameters will not be supported.
  - The Matching Fields for Update parameter will be limited to one pair of matching fields.
  - All update and insert operations will be counted in the output Appended Row Count value.
- When this tool is run in an existing edit session or the Enable Undo toggle button is turned on, the Optimize performance for feature services parameter will be ignored.
- If the Optimize performance for feature services parameter is checked and the Matching Fields for Update parameter values have a matching Global ID field, Global ID values will be preserved. If the Global ID fields are not included, all input rows will be inserted and assigned new Global ID values.
- To update only the geometry of the target dataset, check the Update Geometry parameter, and ensure that the Candidate Fields parameter contains only the name of the match field. For example, if the Matching Fields for Update parameter value uses the globalid field, then the Candidate Fields parameter should contain only the globalid field.

Label	Explanation	Data type
Input Datasets	The input datasets containing the data that will 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 datasets must match the fields of the target dataset for data to be appended. Input fields must match target fields—Fields of the input datasets must match the fields of the target dataset. An error will be returned if the fields do not match. This is the default. Use the field map to reconcile field differences—Fields of the input datasets do not need to match the fields of the target dataset. Fields of 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 of the input datasets 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)	The field map parameter controls the transfer or mapping of fields from the input datasets to the target dataset. It can only be used when 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 with predefined fields, you cannot add, remove, reorder, or change the properties of the fields in the field map. The field map can be used to combine values from one or more input fields into a single output field.	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 dataset. 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 datasets that will be used to match to the target dataset. If the values of these fields match, records from the input datasets will update the corresponding records of the target dataset. Value table columns: Target Fields—The fields from the target dataset that will be matched. Input Fields—The fields from the input dataset that will be matched.	Value Table
Update Geometry (Optional)	Specifies whether geometry in the target dataset will be updated with geometry from the input datasets if the `match_fields` parameter field values match. Checked—Geometry in the target dataset will be updated if the `match_fields` parameter field values match. Unchecked—Geometry will not be updated. This is the default.	Boolean
Enforce Domains (Optional)	Specifies whether the field domains of the target will be enforced. Checked—The field domains of the target will be enforced. If an input field value is outside a target field domain definition, the record will be inserted, but the input field will be null. If matching fields for update are specified, the target field will not be updated. The tool messages will include a warning message identifying the rows where the output field values cannot be written. Unchecked—The field domains of the target will not be enforced. This is the default.	Boolean
Optimize performance for feature services (Optional)	Specifies whether performance will be optimized when the target dataset is an ArcGIS Online or ArcGIS Enterprise feature service. This parameter is only active when the target dataset supports optimization. Checked—The performance of the tool will be optimized when the target dataset is a feature service with the Append capability enabled. This is the default when supported by the target feature service. Optimization uses server-side processing in which the input data is sent to the feature service Append API and loaded into the dataset asynchronously. When the parameter is checked, the Expression and Enforce Domains parameters are not supported, and use of the Matching Fields For Update parameter is limited to one input dataset and one pair of fields. Unchecked—The performance of the tool will not be optimized when the target is a feature service.	Boolean
Candidate Fields (Optional)	The fields that will be updated or inserted in the target dataset. Use this parameter if you want a subset of fields to be updated or inserted in the target dataset. When inserting new records, fields that are not included in this list will have Null values.	Field
Skip Options (Optional)	Specifies whether updates or inserts will be skipped when the Matching Fields for Update parameter is specified. Do not skip updates or inserts—Target rows containing matching fields will be updated and input rows that do not contain matches will be inserted in the target dataset. This is the default. Skip inserts for unmatched rows (update only)—Input rows that do not contain matching fields will not be inserted in the target dataset. This option will only update rows in the target dataset that contain matching fields Skip updates for matched rows (insert only)—Target rows that contain matching fields from input datasets will not be updated. This option will only insert new rows from the input dataset that do not contain matching fields.	String

Derived output

Label	Explanation	Data type
Updated Target Dataset	The updated target dataset.	Table View; Raster Layer
Appended Row Count	The number of rows appended to the target dataset. When the Optimize performance for feature services parameter is checked and the Matching Fields for Update parameter value is specified, all update and insert operations will be counted.	Long
Updated Row Count	The number of rows updated in the target dataset. An updated row count will not be provided for target feature service datasets when the Optimize performance for feature services parameter is checked.	Long

Label

Explanation

Data type

Updated Target Dataset

The updated target dataset.

Table View; Raster Layer

Appended Row Count

The number of rows appended to the target dataset.

When the Optimize performance for feature services parameter is checked and the Matching Fields for Update parameter value is specified, all update and insert operations will be counted.

Long

Updated Row Count

The number of rows updated in the target dataset.

An updated row count will not be provided for target feature service datasets when the Optimize performance for feature services parameter is checked.

Long

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

Name	Explanation	Data type
inputs [inputs,...]	The input datasets containing the data that will 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 datasets must match the fields of the target dataset for data to be appended. `TEST`—Fields of the input datasets must match the fields of the target dataset. An error will be returned if the fields do not match. This is the default. `NO_TEST`—Fields of the input datasets do not need to match the fields of the target dataset. Fields of 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 of the input datasets 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)	The field map parameter controls the transfer or mapping of fields from the input datasets to the target dataset. It can only be used when the `schema_type` parameter is set to `NO_TEST`. Because the input datasets are appended to an existing target dataset with predefined fields, you cannot add, remove, reorder, or change the properties of the fields in the field map. The field map can be used to combine values from one or more input fields into a single output field. In Python, 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 dataset. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS.	SQL Expression
match_fields [[target_field, input_field],...] (Optional)	The fields from the input datasets that will be used to match to the target dataset. If the values of these fields match, records from the input datasets will update the corresponding records of the target dataset. Value table columns: `Target Fields`—The fields from the target dataset that will be matched. `Source Fields`—The fields from the input dataset that will be matched.	Value Table
update_geometry (Optional)	Specifies whether geometry in the target dataset will be updated with geometry from the input datasets 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
enforce_domains (Optional)	Specifies whether the field domains of the target will be enforced. `ENFORCE_DOMAINS`—The field domains of the target will be enforced. If an input field value is outside a target field domain definition, the record will be inserted, but the input field will be null. If matching fields for update are specified, the target field will not be updated. The tool messages will include a warning message identifying the rows where the output field values cannot be written. `NO_ENFORCE_DOMAINS`—The field domains of the target will not be enforced. This is the default.	Boolean
feature_service_mode (Optional)	Specifies whether performance will be optimized when the target dataset is an ArcGIS Online or ArcGIS Enterprise feature service. This parameter is only active when the target dataset supports optimization. `USE_FEATURE_SERVICE_MODE`—The performance of the tool will be optimized when the target dataset is a feature service with the Append capability enabled. This is the default. Optimization uses server-side processing in which the input data is sent to the feature service Append API and loaded into the dataset asynchronously. When the parameter value is `USE_FEATURE_SERVICE_MODE`, the `expression` and `enforce_domains` parameters are not supported, and use of the `match_fields` parameter is limited to one input dataset and one pair of fields. `NO_FEATURE_SERVICE_MODE`—The performance of the tool will not be optimized when the target is a feature service.	Boolean
candidate_fields [candidate_fields,...] (Optional)	The fields that will be updated or inserted in the target dataset. Use this parameter if you want a subset of fields to be updated or inserted in the target dataset. When inserting new records, fields that are not included in this list will have Null values.	Field
skip_options [skip_options,...] (Optional)	Specifies whether updates or inserts will be skipped when the `match_fields` parameter is specified. `NO_SKIP`—Target rows containing matching fields will be updated and input rows that do not contain matches will be inserted in the target dataset. This is the default. `SKIP_INSERT_IF_UNMATCHED`—Input rows that do not contain matching fields will not be inserted in the target dataset. This option will only update rows in the target dataset that contain matching fields `SKIP_UPDATE_IF_MATCHED`—Target rows that contain matching fields from input datasets will not be updated. This option will only insert new rows from the input dataset that do not contain matching fields.	String

Derived output

Name Explanation Data type

Name	Explanation	Data type
output	The updated target dataset.	Table View; Raster Layer
appended_row_count	The number of rows appended to the target dataset. When the `feature_service_mode` parameter value is `USE_FEATURE_SERVICE_MODE` and the `match_fields` parameter value is specified, all update and insert operations will be counted.	Long
updated_row_count	The number of rows updated in the target dataset. An updated row count will not be provided for target feature service datasets when the `feature_service_mode` parameter value is `USE_FEATURE_SERVICE_MODE`.	Long

output

The updated target dataset.

Table View; Raster Layer

appended_row_count

The number of rows appended to the target dataset.

When the feature_service_mode parameter value is USE_FEATURE_SERVICE_MODE and the match_fields parameter value is specified, all update and insert operations will be counted.

Long

updated_row_count

The number of rows updated in the target dataset.

An updated row count will not be provided for target feature service datasets when the feature_service_mode parameter value is USE_FEATURE_SERVICE_MODE.

Long

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 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, Geographic Transformations

Special cases

Preserve Global IDs

For the Append tool, this environment will only preserve Global ID values from the input dataset if the target Global ID field has a unique index. If the target Global ID field does not have a unique index, the tool may fail. To add a unique index to a Global ID field, use the Add Attribute Index tool.

If the target dataset contains a Global ID field and the input data does not, running the Append tool with this environment set to True will automatically generate new Global ID values for inserted rows.

This environment is ignored for target feature services. To preserve Global IDs for feature services that support optimization, check the Optimize performance for feature services parameter and specify GlobalID as the match fields in the Matching Fields for Update parameter.

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes

Append (Data Management Tools)

Summary

Illustration

Usage

Parameters

Derived output

Environments

Special cases

Licensing information

Related topics