SearchCursor

Summary

Returns rows of attribute values from a feature class or table.

The SearchCursor function iterates through Row objects and extracts field values.

Legacy:

This function is superseded by arcpy.da.SearchCursor 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.SearchCursor.

Discussion

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 a None type, which acts here as a placeholder.

Iterate through the rows returned by the SearchCursor function in 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))

Iterate through the rows returned by the SearchCursor function in 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})
ParameterExplanationData Type
dataset

The feature class or table containing the rows to be searched.

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 returned in 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

The fields 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 D".

String
Return Value
Data TypeExplanation
Cursor

A Cursor object that returns Row objects.

Code sample

SearchCursor example

List field contents for a feature class. The cursor is sorted by state name and population.

import arcpy

# Create a search cursor for a feature class
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")))

Related topics