Calculate field

The Calculate field tool calculates field values for a new or existing field. You can use Arcade functions to define the calculation expression.

Examples

The Calculate field tool can be used in scenarios such as the following:

• Replace empty values with a default value.
• Convert a string column of all uppercase names to title case using the Arcade Proper function, for example, JANE SMITH to Jane Smith.
• Use Arcade mathematical functions to round the values of a numeric column to a specific number of places.
• Maintain the zero padding of a ZIP Code value by casting the integer field to a new string field, for example, 1 to 00001.
• Split a string of unseparated ZIP Codes using commas, for example, 0051500234 to 00515,00234.

Parameters

The following table describes the parameters used in the Calculate field tool:

Parameter	Description
Input dataset	The dataset that will have a field calculated.
Field to calculate	Specifies whether the calculated values will replace an existing field (Existing field) or create a field (New field).
New field name	The name of the new field. This parameter is required if the Field to calculate value is New field.
New field type	The type of the new field. This parameter is required if the Field to calculate value is New field.
Existing field name	The name of the existing field to be replaced with the calculated values. This parameter is used if the Field to calculate value is Existing field.
Arcade expression	The Arcade expression that will be used to calculate the new values.
Spatial reference	The spatial reference that will be used for processing geometry values or functions.

Usage notes

Use the Field to calculate parameter to specify whether values will be calculated for a new field or an existing field.

If you are calculating values for a new field, provide the new field name and specify a new type for the field using the New field name and New field type parameters. The following are the field type options:

• Date only—Calculates a new date only type field. Date only fields support date values such as 1/30/2024.
• Date—Calculates a new date type field. Date fields support date and time values such as 1/30/2024, 10:30 AM.
• Double—Calculates a new double type field. Double fields support fractional numbers approximately between -2.2E308 and 1.8E308.
• Integer—Calculates a new integer type field. Integer fields support whole numbers between -2147483648 and 2147483647.
• String—Calculates a new string type field. String fields support strings of characters (text).
• Point—Calculates a new geometry field containing points.
• Multipoint—Calculates a new geometry field containing multipoints.
• Polyline—Calculates a new geometry field containing polylines.
• Polygon—Calculates a new geometry field containing polygons.

To calculate values for an existing field, choose the field from the input dataset. The field will be returned with the same name and type and will contain the newly calculated values.

For both new and existing fields, provide an Arcade expression to calculate the new values. On the Arcade expression dialog box, access the input dataset's fields from the Profile variables list, or provide a value such as $record.field_name in which field_name is the name of the field. If the field has special characters, it may require using an alternate format to reference that field. For example, a field named %Employed cannot be referenced as $record.%Employed, which is invalid syntax. You must instead use syntax such as $record["%Employed"]. Use the Functions list to access functions to build the expression.

Use the Spatial reference parameter to specify the coordinate system that will be used to process any geometry values or functions. If you use a geometry field in the expression, the geometries will be projected to this spatial reference for processing. If you are calculating a new or existing geometry field, the output values will be stored in this spatial reference. By default, the spatial reference value will be set to the spatial reference of a geometry field from the input dataset. If there are no geometry fields in the input dataset, the spatial reference parameter will be set to WGS 1984 (WKID 4326). This parameter is not used if you are not processing geometries.

To learn more about Arcade, see the ArcGIS Arcade topic. To get started using Arcade, you can try building practice expressions using the Arcade Playground.

The following table outlines common Arcade expressions used in the Calculate field tool:

Common operations	Description	Example	Additional information
Copy field	Copy source field values to a target field.	Copy values from my_origin_field to a new field. return $record.my_origin_field
Set default value	Set a default value for a field.	Replace null values in my_field_name with the string my default value. if ($record.my_field_name == null) { return "my default value" } else { return $record.my_field_name }
Change case	Change the case of the source string.	Convert the values in my_field_name to uppercase or lowercase. // To convert a string to lowercase: return Lower($record.my_field_name) // To convert a string to uppercase: return Upper($record.my_field_name)	Lower Upper
Combine values	Concatenate source values into a string.	Combine field_1 and field_2 to create a field. Separate the values with a comma. var values_to_combine = [ $record.field_1, $record.field_2 ] var separator = ", " return Concatenate(values_to_combine, separator)	Concatenate
Left	Extract a number of characters from the beginning of a string.	Return the first three characters of each value in my_string_field. Left($record.my_string_field, 3)	Left
Right	Extract a number of characters from the end of a string.	Return the last three characters of each value in my_string_field. Right($record.my_string_field, 3)	Right
Substring	Extract a set of characters from the middle of a string.	Return five characters from my_string_field starting with character 2. Mid($record.my_string_field, 2, 5)	Mid
Split	Split a string into parts and return one part.	Split a string field into an array based on the separator `. Return the first part. var parts = Split($record.my_string_field, ',') return parts[0] // Return the first part	Split
Conditional value	Return different values based on an if/else statement.	If the value of my_field_name equals 1 for a given record, return true; otherwise, return false. if($record.my_field_name == 1) { return true } else { return false }
Find and replace	Replace all instances of a value with a different value.	Replace instances of search_value in my_field_name with new_value. var search_value = "my old string" var new_value = "my new string" if($record.my_field_name == search_value){ return new_value } else { return $record.my_field_name }	Replace
Access nested values	Return a nested value from a struct field.	Returns the value for the key myKey in a struct field named my_struct_field. var nested_value = $record.my_struct_field.myKey return nested_value
Check that a key exists	Return true or false based on the presence of the specified key.	Returns true if the key myKey exists in a struct field named struct_field, returns false if the key does not exist. return HasValue($record.struct_field, 'myKey')	HasValue
Get values from a key or set a default if the key value does not exist	Return the values of the specified key, or a default value if the key does not exist.	Returns the key value if the key myKey exists in a struct field named struct_field; returns a default value of MyDefault if the key does not exist. return DefaultValue($record.struct_field, ['myKey'], 'MyDefault')	DefaultValue

Outputs

The tool output is a dataset with all fields from the input dataset as well as the newly calculated field values.

Limitations

The following are known limitations of the Calculate field tool:

• Only one field can be calculated per tool run.
• An existing field type cannot be changed. Use the Update fields tool to update an existing field to a new type.

Licensing requirements

The following licensing and configurations are required:

• Creator or Professional user type
• Publisher, Facilitator, or Administrator role, or an equivalent custom role

To learn more about Data Pipelines requirements, see Requirements.