A cursor is a data access object that can be used to either iterate over the set of rows in a table or insert new rows into a table. Cursors have three forms: search, insert, or update. Cursors are commonly used to read existing geometries and write new geometries.
Each type of cursor is created by a corresponding ArcPy function (SearchCursor, InsertCursor, or UpdateCursor) on a table, table view, feature class, or feature layer. A search cursor can be used to retrieve rows. An update cursor can be used to positionally update and delete rows, while an insert cursor is used to insert rows into a table or feature class.
| Cursor | Explanation |
|---|---|
arcpy.da.InsertCursor(in_table, field_names) | Inserts rows |
arcpy.da.SearchCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}) | Read-only access |
arcpy.da.UpdateCursor(in_table, field_names, {where_clause}, {spatial_reference}, {explode_to_points}, {sql_clause}) | Updates or deletes rows |
| Cursor | Explanation |
|---|---|
arcpy.InsertCursor(dataset, {spatial_reference}) | Inserts rows |
arcpy.SearchCursor(dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields}) | Read-only access |
arcpy.UpdateCursor(dataset, {where_clause}, {spatial_reference}, {fields}, {sort_fields}) | Updates or deletes rows |
Cursors can only be navigated in a forward direction; they do not support backing up and retrieving rows that have already been retrieved. If a script needs to make multiple passes over the data, the cursor's reset method may be called.
Search or update cursors are able to be iterated with a for loop. The next row can also be accessed by explicitly using Python's builtin 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 StopIteration exception.
import arcpy
cursor = arcpy.da.SearchCursor(fc, ['fieldA', 'fieldB'])
for row in cursor:
print(row)
Search and update cursors also support with statements.
import arcpy
with arcpy.da.SearchCursor(fc, ['fieldA', 'fieldB']) as cursor:
for row in cursor:
print(row)
Each row retrieved from a table is returned as a list of field values. The values will be returned in the same order as provided to the cursor's field_names argument. A cursor's fields property can also be used to confirm the order of field values.
The cursor object
SearchCursor, UpdateCursor, and InsertCursor create a cursor object that can be used to iterate through the records. The methods of the cursor object created by the various cursor functions vary depending on the type of cursor created.
The following chart shows the methods supported by each cursor type:
| Cursor type | Method | Effect on position |
|---|---|---|
arcpy.da.SearchCursor | reset() | Resets the cursor to its starting position |
arcpy.da.InsertCursor | insertRow() |
Inserts a row into the table |
arcpy.da.UpdateCursor |
updateRow() | Updates the current row |
deleteRow() | Removes the row from the table | |
reset() | Resets the cursor to its starting position |
insertRow
An insert cursor is used to create new rows and insert them. Once the cursor has been created, the insertRow method is used to insert a list (or tuple) of values that will make up the new row. Any field in the table that is not included in the cursor will be assigned the field's default value.
import arcpy
# Create insert cursor for table
#
cursor = arcpy.da.InsertCursor("c:/base/data.gdb/roads_lut",
["roadID", "distance"])
# Create 25 new rows. Set the initial row ID and distance values
#
for i in range(0,25):
cursor.insertRow([i, 100])
updateRow
The updateRow method is used to update the row at the current position of an update cursor. After returning a row from the cursor object, you can modify the row as needed and call updateRow, passing in the modified row.
import arcpy
# Create update cursor for feature class
#
with arcpy.da.UpdateCursor("c:/base/data.gdb/roads",
["roadtype", "distance"]) as cursor:
for row in cursor:
# Update the values in the distance field by multiplying
# the roadtype by 100. Road type is either 1, 2, 3 or 4.
#
row[1] = row[0] * 100
cursor.updateRow(row)
deleteRow
The deleteRow method is used to delete the row at the current position of an update cursor. After fetching the row, you call deleteRow on the cursor to delete the row.
import arcpy
# Create update cursor for feature class
#
with arcpy.da.UpdateCursor("c:/base/data.gdb/roads",
["roadtype"]) as cursor:
# Delete all rows that have a roads type of 4
#
for row in cursor:
if row[0] == 4:
cursor.deleteRow()
Accessing and setting field values
For each cursor, the fields used are supplied by a list (or tuple) of field names. When a row is returned from the cursor it is returned as a list of field values that correspond by index position.
In the sample below, state name and population count are accessed by position.
import arcpy
fc = "c:/base/data.gdb/USA/States"
# Use SearchCursor to access state name and the population count
#
with arcpy.da.SearchCursor(fc, ['STATE_NAME', 'POP2000']) as cursor:
for row in cursor:
# Access and print the row values by index position.
# state name: row[0]
# population: row[1]
#
print('{} has a population of {}'.format(row[0], row[1]))
Tokens can also be used as shortcuts in place of field names. All tables include an ObjectID field, which may have many different names depending on the data type. Simple feature classes require a geometry field, typically (but not always) named Shape. The OID@ token can be used to access the ObjectID field, and the SHAPE@ token (which returns a geometry object) can be used to access the geometry field of a feature class without having prior knowledge of what the field names are.
Search cursor on a multipoint feature class
import arcpy
infc = arcpy.GetParameterAsText(0)
# Enter for loop for each feature
#
for row in arcpy.da.SearchCursor(infc, ["OID@", "SHAPE@"]):
# Print the current multipoint's ID
#
print("Feature {}:".format(row[0]))
# For each point in the multipoint feature,
# print the x,y coordinates
#
for pnt in row[1]:
print("{}, {}".format(pnt.X, pnt.Y))
Additional geometry tokens can be used to access specific geometry information. Accessing the full geometry is more costly timewise. If you only need specific properties of the geometry, use tokens to provide shortcuts to access geometry properties. For instance, SHAPE@XY will return a tuple of x,y coordinates that represent the feature's centroid.
Cursors and locking
Insert and update cursors honor table locks set by ArcGIS applications. Locks prevent multiple processes from changing the same table at the same time. There are two types of locks: shared and exclusive.
- A shared lock is applied anytime a table or dataset is accessed. Multiple shared locks can exist for a table, but no exclusive locks are permitted if a shared lock exists. Displaying a feature class in ArcMap and previewing a table in ArcCatalog are examples of when a shared lock would be applied.
- Exclusive locks are applied when changes are made to a table or feature class. Editing and saving a feature class in ArcMap; changing a table's schema in ArcCatalog; or using an insert cursor on a feature class in a Python IDE, such as PythonWin, are examples of when an exclusive lock is applied by ArcGIS.
Update and insert cursors cannot be created for a table or feature class if an exclusive lock exists for that dataset. The UpdateCursor or InsertCursor functions fail because of an exclusive lock on the dataset. If these functions successfully create a cursor, they apply an exclusive lock on the dataset so that two scripts cannot create an update or insert cursor on the same dataset.
In Python, the lock persists until the cursor is released. Otherwise, all other applications or scripts could be unnecessarily prevented from accessing a dataset. A cursor can released by one of the following:
- Including the cursor inside a with statement, which will guarantee the release of locks regardless of whether or not the cursor is successfully completed
- Calling reset() on the cursor
- The completion of the cursor
- Explicitly deleting the cursor using Python's del statement
An edit session in ArcMap applies a shared lock to data during the edit session. An exclusive lock is applied when edits are saved. A dataset is not editable if an exclusive lock already exists.
Cursors and BLOB fields
A binary large object (BLOB) is data stored as a long sequence of binary numbers. ArcGIS stores annotation and dimensions as BLOBs, and items such as images, multimedia, or bits of code can be stored in this type of field. You can use a cursor to load or view the contents of a BLOB field.
In Python, BLOB fields can accept strings, bytearray, and memoryviews. When reading BLOB fields, a memoryview object is returned.
import arcpy
data = open("c:/images/image1.png", "rb").read()
ic = arcpy.da.InsertCursor("c:/data/fgdb.gdb/fc", ['imageblob'])
ic.insertRow([data])
import arcpy
sc = arcpy.da.SearchCursor("c:/data/fgdb.gdb/fc", ["imageblob"])
memview = sc.next()[0]
open("c:/images/image1_copy.png", "wb").write(memview.tobytes())