UpdateCursor—ArcGIS Pro

Summary

Updates or deletes rows of attribute values from a feature class or table.

The cursor places a lock on the data that will remain until either the script completes or the update cursor object is deleted.

Legacy:

This function is superseded by arcpy.da.UpdateCursor at ArcGIS 10.1 and only remains for use in legacy scripts. For improved performance, functionality, and support for newer field types and tokens, use arcpy.da.UpdateCursor.

Discussion

Update cursors can be iterated with a for loop or in a while loop using the cursor's next method to return the next row. When using the next method on a cursor to retrieve all rows in a table containing N rows, the script must make N calls to next. A call to next after the last row in the result set has been retrieved returns a None type, which acts here as a placeholder.

Iterate through the rows returned by the UpdateCursor function in a for loop.

import arcpy

fc = "c:/data/base.gdb/roads"
field1 = "field1"
field2 = "field2"

cursor = arcpy.UpdateCursor(fc)
for row in cursor:
    # field2 will be equal to field1 multiplied by 3.0
    row.setValue(field2, row.getValue(field1) * 3.0)
    cursor.updateRow(row)

Iterate through the rows returned by the UpdateCursor function in a while loop.

import arcpy

fc = "c:/data/base.gdb/roads"
field1 = "field1"
field2 = "field2"

cursor = arcpy.UpdateCursor(fc)
row = cursor.next()
while row:
    # field2 will be equal to field1 multiplied by 3.0
    row.setValue(field2, row.getValue(field1) * 3.0)
    cursor.updateRow(row)
    row = cursor.next()

Syntax

UpdateCursor (dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields})

Parameter	Explanation	Data Type
dataset	The feature class or table containing the rows to be updated or deleted.	String
where_clause	An expression that limits the rows returned in the cursor. For more information about where clauses and SQL statements, see Introduction to query expressions.	String
spatial_reference	Coordinates are specified in the spatial_reference value provided and converted on the fly to the coordinate system of the dataset.	SpatialReference
fields	A semicolon-delimited string of fields to be included in the cursor. By default, all fields are included.	String
sort_fields	The fields used to sort the rows in the cursor. Ascending and descending order for each field is denoted by A for ascending and D for descending, using the form "field1 A;field2 B".	String

Return Value

Data Type	Explanation
Cursor	A Cursor object that returns Row objects.

Code sample

UpdateCursor example

Update field values in a feature class based on another field's value.

import arcpy

# Create an update cursor for a feature class
rows = arcpy.UpdateCursor("c:/data/base.gdb/roads")

# Update the field used in buffer so the distance is based on the
# road type. Road type is either 1, 2, 3, or 4. Distance is in meters.
for row in rows:
    # Fields from the table can be dynamically accessed from the
    # row object. Here fields named BUFFER_DISTANCE and ROAD_TYPE
    # are used
    row.setValue("BUFFER_DISTANCE", row.getValue("ROAD_TYPE") * 100)
    rows.updateRow(row)

# Delete cursor and row objects to remove locks on the data.
del row
del rows