Summary
The UpdateCursor function creates a cursor that allows you to update or delete rows on the specified feature class, shapefile, 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.
Discussion
Legacy:
The arcpy.da cursors (arcpy.da.SearchCursor, arcpy.da.UpdateCursor, and arcpy.da.InsertCursor) were introduced with ArcGIS 10.1 to provide significantly faster performance over the previously existing set of cursor functions (arcpy.SearchCursor, arcpy.UpdateCursor, and arcpy.InsertCursor). The original cursors are provided only for continuing backward compatibility.
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 None, which is a Python data type that acts here as a placeholder.
Using UpdateCursor with 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)
Using UpdateCursor with 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, shapefile, or table containing the rows to be updated or deleted. | String |
where_clause | String | |
spatial_reference | Coordinates are specified in the spatial_reference 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 descending, using the form "field1 A;field2 B". | String |
Data Type | Explanation |
Cursor | A Cursor object that can distribute Row objects. |
Code sample
Update field values in a feature class based on another field's value.
import arcpy
# Create update cursor for 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