The Calculate Field tool uses Arcade expressions to determine field values. You can perform simple and advanced calculations that are applied to all records. This calculation is applied to each feature. The sections below include examples of using a calculated field expression. Calculations are performed when analysis is run on your ArcGIS GeoAnalytics Server and will always create a new layer.
At ArcGIS Enterprise 10.6 and later, expressions are formatted using Arcade. Using Arcade, field names are formatted as $feature["field name"] or $feature.fieldname. The first option, $feature["field name"], is required when a field name includes a space. All examples below use this option.
Learn more about Arcade expressions
Arcade expressions are used in GeoAnalytics Server by the following tools:
- Buffer expressions in Reconstruct Tracks
- Buffer expressions in Create Buffers
- Join expressions in Join Features
- Detect incidents using start and end expressions in Detect Incidents
Mathematical operation and function examples
Expressions are able to mathematically process numbers. The following table shows a sample of available operations.
Learn more about mathematical operations and functions available in Arcade
Operator | Explanation | Example |
---|---|---|
a + b | Returns the sum of a plus b. | fieldname contains a value of 1.5 $feature["fieldname"] + 2.5 4.0 |
a - b | Returns the difference of a minus b. | fieldname contains a value of 3.3 $feature["fieldname"]- 2.2 1.1 |
a * b | Returns the product of a times b. | fieldname contains a value of 2.0 $feature["fieldname"] * 2.2 4.4 |
a / b | Returns the quotient of a divided by b. | fieldname contains a value of 4.0 $feature["fieldname"] / 1.25 3.2 |
abs( a ) | Returns the absolute (positive) value of a. | fieldname contains a value of -1.5 abs($feature["fieldname"]) 1.5 |
log ( a ) | Returns the natural logarithm (base E) of a. | fieldname contains a value of 1 log($feature["fieldname"]) 0 |
sin ( a ) | Returns the trigonometric sine of a. The input is assumed to be an angle in radians. | fieldname contains a value of 1.5707 sin($feature["fieldname"]) 1 |
cos( a ) | Returns the trigonometric cosine of a. The input is assumed to be an angle in radians. | fieldname contains a value of 0 cos($feature["fieldname"]) 1 |
tan( a ) | Returns the tangent of a. The input is assumed to be an angle in radians. | fieldname contains a value of 0 tan($feature["fieldname"]) 0 |
sqrt( a ) | Returns the square root of a. | fieldname contains a value of 9 sqrt($feature["fieldname"]) 3 |
min( a, b ) | Returns the lowest valued number between a and b. | fieldname contains a value of 1.5, and a value of -3 min($feature["fieldname"], -3) -3 |
max( a, b ) | Returns the highest valued number between a and b. | fieldname1 contains a value of 1.5, and fieldname2 contains a value of -3 max($feature["fieldname1"], $feature["fieldname2"]) 1.5 |
constrain(<value>,<low>,<high>) | Returns the input value if it's within the constraining bounds. If the value is less than the low value, it returns the low value. If the value is greater than the high value, it returns the high value. | Example 1: constrain( $feature["distance"], 0, 10) Returns 0 if distance is less than 0, 10 if distance is greater than 10, and distance otherwise. Example 2: constrain($feature['Store dist'], 6, distance) Returns 6 if Store dist is less than 6, distance if Store dist is greater than distance, and Store dist otherwise. |
Text function examples
Calculate Field expressions are able to process text. The following table shows a sample of available operations. Learn more about text functions available in Arcade.
Operator | Explanation | Example | Result |
---|---|---|---|
concatenate( <values>, <separator>) | Concatenates values together and returns a string.
| fieldname contains a value of GeoAnalytics Concatenate ([$features["fieldname"], "is", "great!"], ' ') | GeoAnalytics is great! |
find(<searchText>, <text>, <startPos>) | Finds a string within a string. Wildcards are not supported.
| fieldname1 contains a value of 14NorthStreet and fieldname2 contains a value of North find($feature["fieldname2"], $feature["fieldname1"]) | 2 |
lower(<value>) | Makes a string lowercase.
| fieldname contains a value of GEOANALYTICS lower($feature["fieldname"]) | geoanalytics |
Text example using find and lower.
find(("north"), lower("146NorthStreet"))
Date function examples
Calculate Field expressions are able to process dates. The following table shows a sample of available operations. In Arcade, month values range from 0 (January) to 11 (December), days from the 1st to the 31st, hours from 0 (12:00 am) to 23 (11:00 pm), minutes and seconds from 0 to 59, and milliseconds from 0 to 999. Arcade dates return time values in the location of your GeoAnalytics Server.
Learn more about date functions available in Arcade
Operator | Explanation | Example | Result |
---|---|---|---|
date( <value>, <month>, <day>, <hour>, <minute>) | Parses a value or set of values into a date string.
| fieldname contains a value of 1476987783555 Example 1: Date($features["fieldname"]) Example 2: Date(2017,0,14,0) Example 3: Date() | Example 1: 20 Oct 2016 11:23:03 am Example 2: 14 Jan 2017 12:00:00 am Example 3: Returns the current time |
DateDiff(<date1>, <date2>, <units>) | Subtracts two dates and returns the difference in the specified units.
| Example 1: DateDiff(Date(2017,1,14,0), Date()) Example 2: DateDiff(Date(2017,1,14,0), Date(), "Years") | Result will vary depending on when you run this command. Example 1: -20532129137 Example 2: -0.6546783768647119 |
Year(<dateValue>) | Returns the year of the given date.
| Example 1: fieldname is a field of type Date with a value of 09 Oct 2017 04:30:43 pm Year($feature["fieldname"]) Example 2: fieldname is a string field formatted as an ISO 8601 string with a value of 2012-09-27 | Example 1: 2017 Example 2: 2012 |
Logical function examples
In addition to simple mathematical expressions, more advanced functions can be used to apply buffer expressions.
Function | Explanation | Example | Result |
---|---|---|---|
iif(<condition>,<true value>,<false value>) | Returns one value if a condition evaluates to true and returns another value if that condition evaluates to false. <true value> and <false value> can be the following:
| iif($feature["field1"] > $feature["field2"], $feature["field1"], 0) iif($feature["field1"] > $feature["field2"], iif($feature["field2"] = 0, $feature["field3"], $feature["field4"]), 0) | Returns field1 if field1 is greater than field2, and 0 otherwise. Returns the result of the second iif function if field1 is greater than field2, and 0 otherwise. |
when(<expression1> , <result1> , <expression2> , <result2> , ... , <expressionN> , <resultN>, <default>) | Evaluates a series of expressions in order until one evaluates to true.
| when(($feature["field1"] + 10) > 1, 1,($feature["field2"] + 10) > 2 , 2, $feature["field3"]) | If field1 + 10 is greater than 1, returns 1. If not, checks if field2 + 10 is greater than 2. If yes, it returns 2. If not, it returns field3. |
decode(<conditional val> , <case1> , <result1>, <case2>, <result2>, ... <caseN>, <resultN>, <defaultValue> ) | Evaluates an expression and compares its value with subsequent parameters. If the expression matches, it returns the next parameter value. If none match, there is the option for the last parameter to be a default return value.
| decode($feature["field1"] + 3 , $feature["field1"], 1, $feature["field2"], 2, 0) | Compares equality between the conditional val field1 + 3 and case1 field1. If true, it returns 1. If false, it compares the equality between field1 + 3 and field2. If true, it returns 2; otherwise, it returns 0. |
Conditional operators
Conditional statements can use the following operators:
Operator | Explanation | Example | Results |
---|---|---|---|
a > b a < b | a is greater than b a is less than b | 10 > 2 | False |
a >= b a <= b | a is greater than or equal to b a is less than or equal to b | abs(-10) >= 10 | True |
a != b | a is not equal to b | abs(-3) != -3 | True |
a == b | a is equal to b | abs(-5) == 5 | True |
<condition1> || <condition2> | Condition 1 or condition 2 is met. | (abs(-5) == 5) || (10 < 2) | True |
<condition1> && <condition2> | Condition 1 and condition 2 are met. | (abs(-5) == 5) && (10 < 2) | False |
Track aware examples
In addition, some GeoAnalytics Tools, such as Detect Incidents and Calculate Field, can use track-aware equations in Arcade. In Calculate Field, track equations can be used when the input layer is time-enabled, the expression is track aware, and one or more fields are used to identify tracks.
Use the following track expression in ArcGIS Enterprise 10.6.
Function | Explanation | Example | Result | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
$track.field["fieldname"].history(<value1>) | Returns an array of values in the given field for the specified time index.
| MyField has sequentially ordered values of [10, 20, 30, 40, 50, 60, 70, 80]. The value 10 is at index 0, and the value 80 is at index 7. Expressions are evaluated at each index, and examples outline the index being used for the examples. n represents the number of features in the sequence, and k represents the index being evaluated. Example 1:$track.field["MyField"].history(3)) Example 2:$track.field["MyField"].history(-3) Example 3:mean($track.field["MyField"].history(-2)) Example 4:$track.field["MyField"].history(-3)[0] | When example 1 is evaluated at index k, it will return an array of values at index 3 through k. If you evaluate at index 6 (70), an array of the values at index [3, 4, 5, 6] is returned so that the array is [40, 50, 60, 70]. Example 2 returns an array of values calculated as index k minus the given value minus 1 (k-2). If this is evaluated at index 6 (value = 70), the values of k-2, k-1, and k are returned [50, 60, 70]. Example 3 returns the mean of the values at index k-1 and k. If you evaluate this at index 4 (value = 50), you find the mean of value 40 (index 3) and value 50 (index 4), which equals 45. If you evaluate this at index 7, the result is the mean of 70 and 80, which equals 75. Example 4 returns the first item (index 0) of the array created in example 2, which is 50. | ||||||||||||
$track.field["fieldname"].history(<value1>, <value2>) | Returns an array of values starting from index1 (<value1>) up to index2 (<value2>). | MyField has sequentially ordered values of [10, 20, 30, 40, 50, 60, 70, 80]. 10 is at index 0, and 80 is at index 7. For this example, expressions are evaluated at index 7 (80). Example 1:$track.field["MyField"].history(-3, -2)) Example 2:$track.field["MyField"].history(-5, -2)) | Example 1: [60] Example 2: [40, 50, 60] | ||||||||||||
$track.time.start | Calculates the start time of a track in milliseconds from epoch. | Using a track that starts on January 2, 2017. $track.time.start | 1483315200000 | ||||||||||||
$track.time.duration | Calculates the duration of a track in milliseconds from the start until the current time step. | Using a track that starts on January 2, 2017, and the current time is January 4, 2017. $track.time.duration | 172800000 | ||||||||||||
$track.time.current | Calculates the current time in a track. | Using a feature that occurs on January 3, 2017, at 9:00 a.m. $track.time.current | 1483434000000 | ||||||||||||
$track.index | Returns the time index of the feature being calculated. | Calculating this value on the first feature in a track. $track.index | 0 | ||||||||||||
$track.T(<value>, "<units>") | Returns the feature time plus the time created using the numeric <value> and given <units>.
| Using a feature that is at January 2, 2017, at 2 p.m. Example 1: $track.T(1, "hours") Example 2: $track.T(-2, "days") | Example 1: Returns January 2 at 3 p.m.: 1483369200000 Example 2: Returns December 31st at 2 p.m.: 1483192800000 | ||||||||||||
$track.field["fieldname"].window(<value1>, <value2>) | Returns an array of values in the given field for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.
The window function is available at ArcGIS Enterprise 10.6.1 or later. | MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1:$track.field["MyField"].window(-1,2) Example 2:$track.field["MyField"].window(-2,0)[0] Example 3:$track.field["MyField"].window(0,3)[2] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: When evaluated at index 2 (value is 30), it returns: 10. Example 3: When evaluated at index 2 (value is 30), it returns: 50. | ||||||||||||
$track.geometry.window(<value1>, <value2>) | Returns an array of values representing geometry for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.
The window function is available at ArcGIS Enterprise 10.6.1 or later. | MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}] The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1:$track.geometry.window(-1,2) Example 2: $track.geometry.window(0,1)[0] on a polyline dataset Example 3: $track.geometry.window(0,1)[0] on a polygon dataset Example 4: Find the X value of the previous point $track.geometry.window(-1,0)[0]["x"] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: Polylines are returned in the following format: [{"paths":[[[-180,-22.88],[-177.6,-23.6]],[[180,-18.099999999999994],[179.7,-18.4],[179.4,-18.7],[178.9,-18.9],[178.5,-19.3],[178.2,-19.7],[178.4,-20],[178.8,-20.2],[178.9,-21.8],[179,-22.2],[179.4,-22.7],[180,-22.88]],[[-178,-17],[-178.8,-17.3],[-179.2,-17.5],[-179.6,-17.8],[-179.9,-18],[-180,-18.099999999999994]]]}] Example 3: Polygons are returned in the following format: [{"rings":[[[-7882559.1197999995,6376090.883500002],[-7893142.474300001,6042715.216800004],[-8544018.775999999,6045361.0554000065],[-8544018.775999999,6376090.883500002],[-7882559.1197999995,6376090.883500002]]]}] Example 4: Evaluated at index 2 (value is 30): 2 | ||||||||||||
$track.window(<value1>, <value2>) | Returns an array of values representing geometry and all attributes for the specified time index. The window function allows you to go forward and backward in time.
The window function is available at ArcGIS Enterprise 10.6.1 or later. | MyField has sequentially ordered values of [10, 20, 30, 40, 50], in addition to the objectID, globalID, and instant_datetime fields. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1:$track.window(-1,0)[0] Example 2:geometry($track.window(-1,0)[0]["x"] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: Evaluated at index 2 (value is 30): 2 |
Use the following track expression in ArcGIS Enterprise 10.6.1 or later.
Function | Explanation | Example | Result | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
TrackStartTime() | Calculates the start time of a track in milliseconds from epoch. | Using a track that starts on January 2, 2017. TrackStartTime() | 1483315200000 | ||||||||||||
TrackDuration() | Calculates the duration of a track in milliseconds from the start until the current time step. | Using a track that starts on January 2, 2017, and the current time is January 4, 2017. TrackDuration() | 172800000 | ||||||||||||
TrackCurrentTime() | Calculates the current time in a track. | Using a feature that occurs on January 3, 2017, at 9:00 a.m. TrackCurrentTime() | 1483434000000 | ||||||||||||
TrackIndex | Returns the time index of the feature being calculated. | Calculating this value on the first feature in a track. TrackIndex | 0 | ||||||||||||
TrackFieldWindow(<fieldName>, <startIndex>, <endIndex>) | Returns an array of values in the given field for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.
| MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1:TrackFieldWindow("MyField,-1,2) Example 2:TrackFieldWindow("MyField,-2,0)[0] Example 3:TrackFieldWindow("MyField,0,3)[2] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: When evaluated at index 2 (value is 30), it returns: 10. Example 3: When evaluated at index 2 (value is 30), it returns: 50. | ||||||||||||
TrackGeometryWindow(<startIndex>, <endIndex>) | Returns an array of values representing geometry for the specified time index. The window function allows you to go forward and backward in time. The expression is evaluated at each feature in the track.
| MyField has sequentially ordered values of [10, 20, 30, 40, 50]. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}] The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1: TrackGeometryWindow(-1,2) Example 2: TrackGeometryWindow(0,1)[0] on a polyline dataset Example 3: TrackGeometryWindow(0,1)[0] on a polygon dataset Example 4: Find the X value of the previous point TrackGeometryWindow(-1,0)[0]["x"] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: Polylines are returned in the following format: [{"paths":[[[-180,-22.88],[-177.6,-23.6]],[[180,-18.099999999999994],[179.7,-18.4],[179.4,-18.7],[178.9,-18.9],[178.5,-19.3],[178.2,-19.7],[178.4,-20],[178.8,-20.2],[178.9,-21.8],[179,-22.2],[179.4,-22.7],[180,-22.88]],[[-178,-17],[-178.8,-17.3],[-179.2,-17.5],[-179.6,-17.8],[-179.9,-18],[-180,-18.099999999999994]]]}] Example 3: Polygons are returned in the following format: [{"rings":[[[-7882559.1197999995,6376090.883500002],[-7893142.474300001,6042715.216800004],[-8544018.775999999,6045361.0554000065],[-8544018.775999999,6376090.883500002],[-7882559.1197999995,6376090.883500002]]]}] Example 4: Evaluated at index 2 (value is 30): 2 | ||||||||||||
TrackWindow(<value1>, <value2>) | Returns an array of values representing geometry and all attributes for the specified time index. The window function allows you to go forward and backward in time.
| MyField has sequentially ordered values of [10, 20, 30, 40, 50], in addition to the objectID, globalID, and instant_datetime fields. The geometry of the features are [{x: 1, y: 1},{x: 2, y: 2} ,{x: null, y: null},{x: 4, y: 4}, {x: 5, y: 5}]. The expression is evaluated at each feature in the track. Results are returned inclusive of the start feature and exclusive of the end feature. Example 1:TrackWindow(-1,0)[0] Example 2:geometry(TrackWindow(-1,0)[0]["x"] | Example 1: When evaluated at each feature, the table shows the following results.
Example 2: Evaluated at index 2 (value is 30): 2 |
Use the following track expressions to calculate distance, speed, and acceleration on tracks in ArcGIS Enterprise 10.9 or later.
All distance calculations are calculated in meters, speed in meters per second, and acceleration in meters per second squared. Distances are measured using geodesic distances.
Function | Explanation |
---|---|
TrackCurrentDistance() | The sum of the distances travelled between observations from the first to current observation. |
TrackDistanceAt(value) | The sum of the distances travelled between observations from the first to the current observation plus the given value. |
TrackDistanceWindow(value1, value2) | The distances between the first value (inclusive) to the last value (exclusive) in a window about the current observation (0). |
TrackCurrentSpeed() | The speed between the previous observation and the current observation. |
TrackSpeedAt(value1) | The speed at the observation relative to the current observation. For example, at value 2, it's the speed at the observation two observations after the current. |
TrackSpeedWindow(value1, value2) | The speed values between the first value (inclusive) to the last value (exclusive) in a window around the current observation (0). |
TrackCurrentAcceleration() | The acceleration between the previous observation and the current observation. |
TrackAccelerationAt(value1) | The acceleration at the observation relative to the current observation. |
TrackAccelerationWindow(value1, value2) | The acceleration values between the first value (inclusive) to the last value (exclusive) in a window around the current observation (0). |
The example calculations for distance, speed, and acceleration use examples from the following image.
Function | Example result | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
TrackCurrentDistance() |
| ||||||||||||||
TrackDistanceAt(2) |
| ||||||||||||||
TrackDistanceWindow(-1, 2) |
| ||||||||||||||
TrackCurrentSpeed() |
| ||||||||||||||
TrackSpeedAt(2) |
| ||||||||||||||
TrackSpeedWindow(-1, 2) |
| ||||||||||||||
TrackCurrentAcceleration() |
| ||||||||||||||
TrackAccelerationAt(2) |
| ||||||||||||||
TrackAccelerationWindow(-1, 2) |
|