Calculate (Feature Service/Layer)

URL:: https://<root>/<serviceName>/FeatureServer/<layerId>/calculate
Methods:: GET
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.

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

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 Use dark colors for code blocksCopy `1 2 3 4 5 6 where=POP2000 > 350000 where=CITY_NAME = 'Glendora' //Limit the records being updated to match 1 pm on February 9th, 2015 PST where=pacific_time_date_field = Date '2015-02-09 13:00:00'`
`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 Use dark colors for code blocksCopy `1 2 3 "calcExpression":[{"field": "Field_1", "sqlExpression": "Null"}] "calcExpression":[{"field": "Field_2", "value": Null}]` Syntax Use dark colors for code blocksCopy `1 "calcExpression":[{"field": <fieldname>, "value" \| "sqlExpression": <value> \| "expression"},...]` Note The `sqlExpression` property value is expected to be a string. Violation of this rule may result in the `calculate` operation failing. Examples Use dark colors for code blocksCopy `1 2 3 "calcExpression":[{"field": "Quality", "value": 3}] "calcExpression":[{"field": "A", "sqlExpression": "B*3"}]`
`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 Use dark colors for code blocksCopy `1 gdbVersion=<version>` Example Use dark colors for code blocksCopy `1 gdbVersion=SDE.DEFAULT`
`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 Use dark colors for code blocksCopy `1 sessionID=<sessionID>` Use dark colors for code blocksCopy `1 sessionID={E81C2E2D-C6A7-40CB-BF61-FB499E53DD1D}`
`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` Use dark colors for code blocksCopy `1 returnEditMoment=true`
`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 Use dark colors for code blocksCopy `1 async=false`
`f`	The response format. The default response format is `html` . Values: `html \| json`

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

Use dark colors for code blocksCopy
where=POP2000 > 350000

where=CITY_NAME = 'Glendora'

//Limit the records being updated to match 1 pm on February 9th, 2015 PST
where=pacific_time_date_field = Date '2015-02-09 13:00:00'

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

Use dark colors for code blocksCopy
"calcExpression":[{"field": "Field_1", "sqlExpression": "Null"}]

"calcExpression":[{"field": "Field_2", "value": Null}]

Syntax

Use dark colors for code blocksCopy
"calcExpression":[{"field": <fieldname>, "value" | "sqlExpression": <value> | "expression"},...]

Examples

Use dark colors for code blocksCopy
"calcExpression":[{"field": "Quality", "value": 3}]

"calcExpression":[{"field": "A", "sqlExpression": "B*3"}]

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 .

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

Use dark colors for code blocksCopy
gdbVersion=<version>

Example

Use dark colors for code blocksCopy
gdbVersion=SDE.DEFAULT

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

Use dark colors for code blocksCopy
sessionID=<sessionID>

Use dark colors for code blocksCopy
sessionID={E81C2E2D-C6A7-40CB-BF61-FB499E53DD1D}

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

Use dark colors for code blocksCopy
returnEditMoment=true

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 .

Values: true | false

Example

Use dark colors for code blocksCopy
async=false

f

The response format. The default response format is html .

Values: html | json

JSON Response syntax

When async is false :

Use dark colors for code blocksCopy
{
  "success": <true|false>,
  "updatedFeatureCount": <count>,
  "editMoment": <epochMilliseconds>
}

When async is true :

Use dark colors for code blocksCopy
{
  "statusUrl": "<statusURL>"
}

JSON Response examples

When async is false :

Use dark colors for code blocksCopy
{
   "success": true,
   "updatedFeatureCount": 51
}

When async is false , data is branch versioned, and returnEditMoment is true :

Use dark colors for code blocksCopy
{
  "success":true,
  "updatedFeatureCount":51,
  "editMoment": 1457994488000
}

When async is true :

Use dark colors for code blocksCopy
{
  "status": "Completed",
  "submissionTime": 1572816329000,
  "lastUpdatedTime": 1572816344000,
  "recordCount": 3140
}