- URL:
- https://<root>/<serviceName>/FeatureServer/append
- Methods:
POST
Description
ArcGIS Online and ArcGIS Enterprise hosted feature services support the append
operation, a high-performance API capable of handling large volumes of data that has the ability to upsert data.
Upsert
Upsert is a combination of insert and update, driven by the feature
. Upsert is used to add new features and update existing features at the same time. If a feature in the source data matches an existing feature in the destination layer, the existing feature is updated with the values from the source. If there is no match, a new feature is created based on the values from the source.
The append
operation currently supports feature
of type Object
and Global
. The target layer must have a destination field of one of these types.
Unique index on source data feature Id
The destination object
or global
fields do not need to be mapped to source fields of the same type. The source feature
can come from different field types as long as the values are acceptable destination values for feature
. For example, a destination global
can be mapped to the Global
, Guid
, and string
field types, and the object
can be mapped to the short
or long
field types.
Enable and disable append capabilities
Feature service Append
capabilities must be enabled for the append operation to be used by nonadministrative users. Organization administrators or the service owner can use the append
operation without adding the Append
capability to the feature service. The Append
capability needs to be added to the service capabilities
property only if the service owner or organization administrators needs to allow a nonadministrator user to append data to a feature service. Organization administrators or the service owner can enable or disable the Append
capability on an existing feature service using the feature service update
API as shown in the example below. For more information on how to add the Append capabilities to a feature service, see Update Definition (Feature Service).
The Append
capability does not require any editing capabilities to be enabled. Features will be inserted or updated when upsert
is set as true through the append
operation without the administrator adding either the Create
or Update
capabilities to the feature service.
Supports append
A feature service returns the supports
metadata property. When this property is absent or is returned as false
, the Append
capability cannot be added to the feature service and the feature service does not support the Append
operation, even for the organization administrators or feature service owner.
Append sources
The source of the append operation can be one of three parameters: edits
, append
, or append
. edits
is a literal feature collection string. append
references the item
of a file or hosted feature service currently stored in the portal or geowarehouse. append
references the item
of a file uploaded to the server through the uploads operation. The item
of a file in the portal or geowarehouse is completely independent from the item
of a file stored in the server uploads. Unless a file is needed in the portal or geowarehouse, using the uploads API is recommended. For ArcGIS Enterprise, append
is supported at 10.9 and later.
ArcGIS Enterprise 11.3 introduces support for appending directly to a hosted feature service from another hosted feature service within the same Enterprise organization (not from a different Enterprise organization or from a source reference feature service). Both relational and spatiotemporal data stores can be used as the target of this operation, only relational can be used as a source at present.
Supported append formats
A feature service that supports append returns the supported
metadata property. This property lists the supported append
values for this operation.
The append formats are:
sqlite
: sqlite databasegpkg
: geopackageshapefile
: shapefilefilegdb
: file geodatabasefeature
: feature collectionCollection geojson
: GeoJSONcsv
: Comma separated valuesexcel
: Microsoft Excel formatfeature
: a hosted feature serviceService
Sync and Change Tracking
The Append
capability is not currently supported if the feature service has sync
or change
capabilities enabled. When either sync
or change
is enabled on the feature service, Append
is blocked for the following reasons:
- The Esri
sync
engines might not be able to support syncing the changes from theappend
operation. Theappend
operation might be using a very low-level database API that might prevent the use of triggers to track the changes from theappend
operation. ArcGIS Online feature servicesync
engines rely on triggers to track the edit changes. - The volume of changes from
append
might be quite large for the syncing process and it will be better for the client to re-create the replica afterappend
.
Attempting to set the upsert
parameter to true will return an error if sync or change tracking are enabled.
Feature service layer views
The Append
capability can be enabled on feature service layer views.
Preserve feature Id
The source feature
(Object
or Global
) are only preserved when upsert
is set to true
. When upsert
is false
, all rows created will have new Object
or Global
values allocated by the system.
Feature service metadata
The feature service metadata is updated after adding or updating data using the append
operation. The last
of the feature service will be updated. The extent
will also be updated for ArcGIS Online feature services.
Geocoding (ArcGIS Online)
The append
operation supports geocoding geometry from CSV and Excel data. The cost and billing of geocoding is the same cost and billing of geocoding during publishing data as a feature service.
Editor tracking and ownership-based access control (OBAC)
Editor tracking is currently supported with feature service append
API. The Creation
, Edit
, Editor
, and Creator
are populated based on the user who is calling append
. Editor tracking fields are set when inserting or updating existing features. The creator and the editor fields will be set to the append
user. Service owners and administrators will bypass any OBAC set on the feature service. For nonowners, if "allows
is set to false
on the feature service, the append
user can only update their features or features owned by anonymous users.
Appending multipatch data (ArcGIS Online)
Appending/upserting data to a multipatch feature service is supported. In ArcGIS Online, the client can turn on Append
capability on a multipatch feature service using the feature service update
operation. Similar to a nonmultipatch feature service, Object
, Global
, or any other fields with unique index can be used to upsert data to a multipatch feature service. The append
operation will return an error when a client tries to append nonmultipatch geometry data into a feature service that stores multipatch geometries.
New at 11.1
The updates and enhancements below have been added to hosted feature services running on a relational data store in ArcGIS Enterprise:
- The Append capability can now be set for qualifying hosted feature services to allow non-service owners and non-organization administrators with access to the feature service to run this operation. In prior releases, the Append capability could not be set for hosted feature services, limiting the scope of those who could use this operation on a given hosted feature service.
- The
esri
field type is now supported.Field Type Blob - A field's default value is now applied when a row is added with no provided value when using either this operation or Apply Edits.
Request parameters
Parameter | Details |
---|---|
| The list of layers and table to upload. Syntax
Example
|
| This is needed only if the source is a feature service or contains more than one table or if you need to specify field mapping for the destination layer. It is used to map source data to a destination layer. Only one source can be mapped to a layer. The Syntax
Example, shapefile
Example, featureService
|
| A literal feature collection JSON string to be used as the source data. Example, formatted for readability
|
(Optional) | Used to specify whether the edits need to be applied as updates if the features already exist. The default value is Values: |
(Optional) | Specifies whether Values: |
| The Example
|
| The Example
|
| Filters features from the source file. Source formats that support filtering can be determined by inspecting the service's Syntax
Example
|
| The Values: |
(Optional) | Specifies whether the Value: |
| The response format. The default value is Value: |
Example usage
Example one: append a shapefile
The following is a sample POST request that demonstrates appending data from a shapefile to a feature service:
POST /webadaptor/rest/services/USA/FeatureServer/append HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
layers=0&upsert=false&useGlobalIds=false&appendItemId=0c6b928f590f49ebac04761bab413e49&rollbackonFailure=true&f=pjson
The above request generates the following response:
{
"status": "processing",
"statusMessage": "Job Status for jobId: b62e9db7-507c-443d-3473-8a1f7a7e9fac",
"itemId": "cc7ddbc1e33440688d3110c885fa0b30"
}
The job
from the response can be used to check the job status by making a request of the following form:
https://machine.domain.com/webadaptor/rest/services/USA/FeatureServer/append/jobs/b62e9db7-507c-443d-3473-8a1f7a7e9fac?f=pjson
If the job is successful, and complete, the above request will return the following response:
{
"layerName": "CITIES",
"submissionTime": 1520876908117,
"lastUpdatedTime": 1520876913647,
"recordCount": 2,
"status": "Completed"
}
Example two: append a file geodatabase
The following is a sample POST request that demonstrates appending data from a file geodatabase:
POST /webadaptor/rest/services/USA/FeatureServer/append HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []
layers=0&layerMappings=[{"id":0,"sourceTableName":"USA"}]&upsert=false&userGlobalIds=false&appendUploadId=0c6b928f590f49ebac04761bab413e49&appendUploadformat=filegdb&rollbackonFailure=true&f=pjson
The above request generates the following response:
{
"status": "processing",
"statusMessage": "Job Status for jobId: feeahh1e-e32c-45bf-680c-f4ed70569081",
"itemId": "aa7gdww1e55200527d3110c634fa0b30"
}