Skip To Content

Calculate Field

Summary

Calculates the values of a field for a feature class, feature layer, or raster.

Usage

  • To learn more about Python expressions, see Calculate Field Python examples.

    To learn more about Arcade expressions, see the ArcGIS Arcade guide.

    To learn more about SQL expressions, see Calculate field values.

  • When used with a selected set of features, such as those created from a query in Make Feature Layer or Select Layer By Attribute, this tool will only update the selected records.

  • The calculation can only be applied to one field per operation. To apply multiple calculations, use the Calculate Fields tool.

  • Existing field values will be overwritten. A copy of the input table should be made if you want to preserve the original values.

  • For Python calculations, field names must be enclosed in exclamation points (!fieldname!).

    For Arcade calculations, field names must be prefixed with $feature. ($feature.fieldname).

  • To calculate strings to text or character fields, on the dialog box, the string must use double quotation marks ("string"), or in scripting, the string using double quotation marks must also be encapsulated in single quotation marks ('"string"').

  • To calculate a field to be a numeric value, enter the numeric value in the Expression parameter; no quotation marks around the value are required.

  • Legacy:

    arcgis.rand() is no longer supported as of ArcGIS Pro 2.0. Comparable functions using Python's random module should be used instead. To use the random module successfully, add it as an import in the Code Block parameter.

  • The Code Block parameter allows you to create complex expressions. You can enter the code block directly on the dialog box or as a continuous string in scripting. The expression and code block are connected. The code block must relate back to the expression; the result of the code block should be passed into the expression.

    The Code Block parameter is only supported for Python expressions.

  • The Python math module and formatting are available for use in the Code Block parameter. You can import additional modules. The math module provides number-theoretic and representation functions, power and logarithmic functions, trigonometric functions, angular conversion functions, hyperbolic functions, and mathematical constants. To learn more about the math module, see the Python help.

  • Python expressions can be created using properties from the Geometry object including type, extent, centroid, firstPoint, lastPoint, area, length, isMultipart, and partCount (for example, !shape.area!).

  • Python expressions can use the geometry area and length properties with an areal or linear unit to convert the value to a different unit of measure (for example, !shape.length@kilometers!). If the data is stored in a geographic coordinate system and a linear unit is supplied (for example, miles), the length will be calculated using a geodesic algorithm. Using areal units on geographic data will yield questionable results as decimal degrees are not consistent across the globe.

    • Areal unit of measure keywords:
      • ACRES | ARES | HECTARES | SQUARECENTIMETERS | SQUAREDECIMETERS | SQUAREINCHES | SQUAREFEET | SQUAREKILOMETERS | SQUAREMETERS | SQUAREMILES | SQUAREMILLIMETERS | SQUAREYARDS | SQUAREMAPUNITS | UNKNOWN
    • Linear unit of measure keywords:
      • CENTIMETERS | DECIMALDEGREES | DECIMETERS | FEET | INCHES | KILOMETERS | METERS | MILES | MILLIMETERS | NAUTICALMILES | POINTS | UNKNOWN | YARDS
  • Python expressions can be used to calculate the geodesic area or length of a feature by using geodesicArea or geodesicLength properties combined with areal or linear units of measure (for example, !shape.geodesicArea@hectares! or !shape.geodesicLength@miles!).

  • ArcGIS applications use UTF-16-LE encoding to read and write .cal files. Other applications (for example, Notepad) can be used to create or modify .cal files as long as the output is written using UTF-16-LE encoding. Using any other encoding will result in a file that will not load into the code block.

  • When calculating joined data, you cannot directly calculate the joined columns. However, you can directly calculate the columns of the origin table. To calculate the joined data, you must first add the joined tables or layers to the map. You can then perform calculations on this data separately. These changes will be reflected in the joined columns.

  • Python expressions that attempt to concatenate string fields that include a null, or divide by zero, will return a null for that field value.

  • Be aware that this tool honors the Output Extent environment setting. Only those features within the extent will have their field values calculated. The environment setting has no effect on nonspatial data such as tables

  • Calculate Field honors the Transfer Field Domain Descriptions environment. When this environment is turned on, any fields that have an associated domain will use the domain description instead of the field's value. Values from fields that do not have a domain will be unaffected.

  • SQL expressions were implemented to better support calculations against feature services, particularly with performance. Instead of performing calculations one feature or row at a time, a single request is set to the feature service.

    Only feature services and enterprise geodatabases support SQL expressions. For other formats, use Python or Arcade expressions.

    SQL expressions are invalid for feature services that are using versioned data.

Syntax

CalculateField_management (in_table, field, expression, {expression_type}, {code_block})
ParameterExplanationData Type
in_table

The table containing the field that will be updated with the new calculation.

Mosaic Layer; Raster Layer; Table View
field

The field that will be updated with the new calculation.

Field
expression

The simple calculation expression used to create a value that will populate the selected rows.

SQL Expression
expression_type
(Optional)

Specifies the type of expression that will be used.

Legacy:

PYTHON and PYTHON_9.3 are still supported for backward compatibility but are not listed as choices. Python scripts that use these keywords will continue to work.

Python 3 (PYTHON3 in Python) returns the values in date fields as Python datetime objects. PYTHON and PYTHON_9.3 return the values in date fields as strings.

  • PYTHON3Python expression type. This is the default.
  • ARCADEArcade expression type.
  • SQLSQL expression.

To learn more about Python expressions, see Calculate Field examples.

To learn more about Arcade expressions, see the ArcGIS Arcade guide.

To learn more about SQL expressions, see Calculate field values.

SQL expressions were implemented to better support calculations against feature services, particularly with performance. Instead of performing calculations one feature or row at a time, a single request is set to the feature service.

Only feature services and enterprise geodatabases support SQL expressions. For other formats, use Python or Arcade expressions.

SQL expressions are invalid for feature services that are using versioned data.

String
code_block
(Optional)

Allows for a block of code to be entered for complex expressions.

String

Code sample

CalculateField example 1 (Python window)

The following Python window script demonstrates how to use the CalculateField function in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data"
arcpy.AddField_management("vegtable.dbf", "VEG_TYP2", "TEXT", "", "", "20")
arcpy.CalculateField_management("vegtable.dbf", "VEG_TYP2", 
                                '!VEG_TYPE!.split(" ")[-1]', "PYTHON3")
CalculateField example 2 (stand-alone script)

Use CalculateField to assign centroid values to new fields.

# Name: CalculateField_centroids.py

# Import system modules
import arcpy

# Set environment settings
arcpy.env.workspace = "C:/data/airport.gdb"
 
# Set local variables
inFeatures = "parcels"
fieldName1 = "xCentroid"
fieldName2 = "yCentroid"
fieldPrecision = 18
fieldScale = 11
 
# Add fields
arcpy.AddField_management(inFeatures, fieldName1, "DOUBLE", 
                          fieldPrecision, fieldScale)
arcpy.AddField_management(inFeatures, fieldName2, "DOUBLE", 
                          fieldPrecision, fieldScale)
 
# Calculate centroid
arcpy.CalculateField_management(inFeatures, fieldName1, 
                                "!SHAPE.CENTROID.X!",
                                "PYTHON3")
arcpy.CalculateField_management(inFeatures, fieldName2, 
                                "!SHAPE.CENTROID.Y!",
                                "PYTHON3")
CalculateField example 3 (stand-alone script)

Use CalculateField with a code block to calculate values based on ranges.

# Name: CalculateField_ranges.py

# Import system modules
import arcpy
 
# Set environment settings
arcpy.env.workspace = "C:/data/airport.gdb"
 
# Set local variables
inTable = "parcels"
fieldName = "areaclass"
expression = "getClass(float(!SHAPE.area!))"

codeblock = """
def getClass(area):
    if area <= 1000:
        return 1
    if area > 1000 and area <= 10000:
        return 2
    else:
        return 3"""
 
# Execute AddField
arcpy.AddField_management(inTable, fieldName, "SHORT")
 
# Execute CalculateField 
arcpy.CalculateField_management(inTable, fieldName, expression, "PYTHON3", 
                                codeblock)
CalculateField example 4 (stand-alone script)

Use CalculateField to assign random values to a new field.

# Name: CalculateField_Random.py

# Import system modules
import arcpy
import random
 
# Set environment settings
arcpy.env.workspace = "C:/data/airport.gdb"
  
# Set local variables
inFeatures = "parcels"
fieldName = "RndValue"
expression = "random.randint(0, 10)"
code_block = "import random"
 
# Execute AddField
arcpy.AddField_management(inFeatures, fieldName, "LONG")
 
# Execute CalculateField 
arcpy.CalculateField_management(inFeatures, fieldName, expression, "PYTHON3", 
                                code_block)
CalculateField example 5 (Python window)

The following Python window script demonstrates how to use the CalculateField function with ARCADE in immediate mode.

import arcpy
arcpy.env.workspace = "C:/data/fgdb.gdb"
arcpy.CalculateField_management("data", "new_value", "$feature.value1 + $feature.value2", "ARCADE")
CalculateField example 6 (Python window)

The following Python window script demonstrates how to use the CalculateField function with SQL in immediate mode.

import arcpy
feature_service = "<a feature service url>"
arcpy.CalculateField_management("data", "NEW_VALUE", "SAMPLE * (BASELINE - 40)", "SQL")

Environments

Transfer Field Domain Descriptions

When this environment is turned on, any fields that have an associated domain will use the domain description instead of the field's value. Values from fields that do not have a domain will be unaffected.

Licensing information

  • ArcGIS Desktop Basic: Yes
  • ArcGIS Desktop Standard: Yes
  • ArcGIS Desktop Advanced: Yes

Related topics