- URL:https://<featurelayer-url>/calculate
- Required Capability:Update
- Version Introduced:10.4
Description
The calculate operation is performed on a feature service layer resource. It updates the values of one or more fields in an existing feature service layer based on SQL expressions or scalar values.
A layer is capable of supporting the calculate operation if the supportsCalculate property is true. If the property is false, or not present, the layer is not capable of supporting this operation. When the property is true, a client can use the calculate operation as long as the Update capability is set on the feature service, or if the user is logged in as the service owner, view owner, or organization administrator.
If supportsCalculate is true and isDataVersioned is also true, the gdbVersion parameter is supported. If supportsCalculate is true and isDataBranchVersioned is also true, the sessionID and returnEditMoment parameters are supported.
Note:
To support calculate with versioned data, the feature service must be published from ArcGIS Pro referencing a registered data source.
Neither the Shape field nor system fields can be updated using the calculate operation. System fields include ObjectId and GlobalId.
See Calculate a field for more information on supported expressions.
Request parameters
| Parameter | Details |
|---|---|
| where (Optional) | A where clause can be used to limit the updated records. Any legal SQL where clause operating on the fields in the layer is allowed. If this parameter is not included in the request, the operation will apply to all records. The dateFieldsTimezoneID property of the feature service identifies the time zone all dates are stored in. If your where clause is referencing a date type field and you have dateFieldsTimezoneID set to a specific time zone, make sure your where clause issues the time in that specific time zone. You can set the dateFieldsTimezoneID property in the ArcGIS Server Manager. In Server Manager, navigate to the service you wish to edit and update the time zone information in the Parameters tab. In the Server Manager, navigate to service you wish to edit and click on the Parameters tab to update the time zone information. If you don't have dateFieldsTimezoneID set, be sure your WHERE clause issues the time you are querying in UTC. The dateFieldsTimezoneID property does not apply to fields that were time enabled through the Configure Parameters tab in the Publish Map Service pane in ArcGIS Pro at the time of publishing. Examples |
| calcExpression | The array of field/value info objects that contain the field or fields to update and their scalar values or SQL expression. For more information on how to build expressions, see Calculate a field. If you are updating records in a date type field, be sure to issue the new date or time value in UTC. This is the case even if you have the dateFieldsTimezoneID property set and issue local time in your where clause. Note:As of 10.6.1, calcExpression can take null values. Examples Syntax Note:The sqlExpression property value is expected to be a string. Violation of this rule may result in the calculate operation failing. Examples |
| sqlFormat | The SQL format for the calcExpression. The expression can take one of two formats. It can be either standard SQL92 (standard), or it can use the native SQL of the underlying data store (native). The default is standard. Values for date type fields must always be specified in UTC. The supportedSqlFormatsInCalculate layer property (under advancedEditingCapabilities) indicates which of these sqlFormat values are supported. If only standard is listed, standard is the only value that can be used, even when useStandardizedQuery is set to false.
Note:The SQL format native is supported only for admin users and when useStandardizedQuery=false.Values: standard | native |
| gdbVersion | The geodatabase version to apply the edits. This parameter applies only if the isDataVersioned property of the layer is true. This can be either a traditional version or a branch version. If the gdbVersion parameter is not specified, edits are made to the published map's version. Syntax Example |
| sessionID (Optional) | Set by a client during long transaction editing on a branch version. The sessionID is a GUID value that clients establish at the beginning and use throughout the edit session. The sessonID ensures isolation during the edit session. This parameter applies only if the isDataBranchVersioned property of the layer is true. Syntax |
| returnEditMoment (Optional) | Specifies whether the response will report the time edits were applied. If returnEditMoment = true, the server will return the time edits were applied in the response's editMoment key. This parameter applies only if the isDataBranchVersioned property of the layer is true. Values: true | false |
| async | Indicates whether to process the calculate operation in synchronous or asynchronous mode. This parameter can only be set to true if the supportsAsyncCalculate property in the layer metadata is set to true. The default value is false. If possible, it's recommended that you set the async parameter to true for longer-running operations that would otherwise time out as synchronous operations. When async is set to true, the operation will return a status URL that can be requests upon to get a status. When the operation is complete, the status response property will return as Completed. Note:When setting this parameter to true, the requests upon the status URL return submissionTime and lastUpdatedTime to indicate when and how long the operation has been running. For some services, these properties are not supported. In those cases, a null value may be returned. Values: true | false Example |
| f | The response format. The default response format is html. Values: html | json |
JSON Response syntax
When async is false:
{
"success": <true|false>,
"updatedFeatureCount": <count>,
"editMoment": <epochMilliseconds>
}When async is true:
{
"statusUrl": "<statusURL>"
}JSON Response examples
When async is false:
{
"success": true,
"updatedFeatureCount": 51
}When async is false, data is branch versioned, and returnEditMoment is true:
{
"success":true,
"updatedFeatureCount":51,
"editMoment": 1457994488000
}When async is true:
{
"status": "Completed",
"submissionTime": 1572816329000,
"lastUpdatedTime": 1572816344000,
"recordCount": 3140
}