SearchCursor—Python in ArcGIS Notebook Server

Summary

The SearchCursor function establishes a read-only cursor on a feature class or table. SearchCursor can be used to iterate through Row objects and extract field values. The search can optionally be limited by a where clause or by field and optionally sorted.

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.

Search 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 SearchCursor with a for loop.

import arcpy

fc = "c:/data/base.gdb/roads"
field = "StreetName"
cursor = arcpy.SearchCursor(fc)
for row in cursor:
    print(row.getValue(field))

Using SearchCursor with a while loop.

import arcpy

fc = "c:/data/base.gdb/roads"
field = "StreetName"
cursor = arcpy.SearchCursor(fc)
row = cursor.next()
while row:
    print(row.getValue(field))
    row = cursor.next()

Syntax

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

Parameter	Explanation	Data Type
dataset	The feature class, shapefile, or table containing the rows to be searched.	String
where_clause		String
spatial_reference	When specified, features will be projected on the fly using the spatial_reference provided.	SpatialReference
fields	A semicolon-delimited string of fields to be included in the cursor. By default, all fields are included.	String
sort_fields	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

Return Value

Data Type	Explanation
Cursor	A Cursor object that can hand out Row objects.

Code sample

SearchCursor example

List field contents for Counties.shp. Cursor is sorted by state name and population.

import arcpy

# Open a searchcursor
#  Input: C:/Data/Counties.shp
#  Fields: NAME; STATE_NAME; POP2000
#  Sort fields: STATE_NAME A; POP2000 D
rows = arcpy.SearchCursor("c:/data/counties.shp",
                          fields="NAME; STATE_NAME; POP2000",
                          sort_fields="STATE_NAME A; POP2000 D")

# Iterate through the rows in the cursor and print out the
# state name, county and population of each.
for row in rows:
    print("State: {0}, County: {1}, Population: {2}".format(
        row.getValue("STATE_NAME"),
        row.getValue("NAME"),
        row.getValue("POP2000")))