Scripting Your ArcGIS Geoprocessing Tasks with Cursors (Part 2)
In our last post we gave an overview of some basic ArcGIS geoprocessing concepts. The next few posts will cover the functional groupings of geoprocessing objects, and we’ll start with the cursor objects which are displayed in an orange color on the Geoprocessing Object Model Diagram.
In database terms a cursor refers to a subset of records that is obtained by applying an attribute and/or spatial query on a feature class or table. This subset of records is held in memory rather than visually displayed. Do not confuse cursors with selections sets. Selection objects are used to display the currently selected features or rows in the ArcMap display, while cursors are not used for display purposes. For instance a search cursor could be used to programmatically generate a mailing list of all parcels of land with a property value greater than $100,000. The Geoprocessing framework provides the ability to obtain cursors from geographic datasets (Feature Classes) as well as regular database tables. These cursor objects allow you to manage a subset of records in a single object. In this article we will explore the Geoprocessor classes, methods, and properties used to manipulate cursors as specified through the Geoprocessor Object Model Diagram which you can see in the figure below.
Types of Cursors
There are three distinct types of cursors that can be created through the use of corresponding methods found on the GpDispatch object. The most commonly used type of cursor is the “Search Cursor” which is used in query operations to return a subset of records that meet the query conditions. Search cursors are read-only cursors which you can iterate through to obtain information. You can not use a search cursor to insert, update, or delete records from a table. A second type of cursor is the “Insert Cursor” which is specifically used to insert a new record in your table or feature class. Finally, the “Update Cursor” is used to update or delete records in a table or feature class. The records returned in an update or search cursor can be constrained to match attribute criteria.
It is important that you create the proper type of cursor for the operation that you are performing. For example, don’t create a search cursor if you are attempting to update data in a table. As we mentioned, search cursors are read-only structures so you won’t be able to update the data. We’ll explore each of the cursor types in more detail later in this article.
Cursor Objects in the Geoprocessor Object Model Diagram
The GpDispatch or arcgisscripting object, also called the Geoprocessor Object, is the point of entry for all scripts accessing the Geoprocessor objects.
Among many other properties and methods, the GpDispatch object contains three methods that can be used to create cursor objects.
Each of these methods return a cursor type that corresponds to the method name on GpDispatch. For instance, calling the InsertCursor method would return an instance of an InsertCursor that can be used to insert new rows in a table or feature class. Each method takes a required “InputValue” parameter that points to a data source (table, feature class, etc). In addition, the SearchCursor and UpdateCursor methods take an optional “WhereClause” parameter that allows you to constrain the records that are returned through the use of a where clause.
The InsertCursor method on GpDispatch is used to return an InsertCursor object which is used to add rows to a table.
This class contains three methods. The NewRow( ) method is used to create a new row object as seen in the figure below.
Once a new Row object has been created you can use the FieldName property in conjunction with the SetValue( ) method to populate data for a particular field name in the new row. After you’ve created a new row with the NewRow( ) method and optionally set the values for the fields in this row you’ll need to call the InsertRow( ) method on InsertCursor to add the row to your table or feature class.
To add a new row to a feature class, you must populate the Shape field as well. You can use the Point and Array objects which are also found on the Geoprocessor Object Model Diagram to accomplish this task.
Take a look at the following Python code example that shows how you can use the InsertCursor object to insert a new record in a table.
The SearchCursor method on GpDispatch is used to return a SearchCursor object which is used to obtain a read-only subset of records from a table or feature class.
This class contains two methods which are used to iterate through the collection of rows that are returned. Remember that the SearchCursor( ) method on GpDispatch can include an optional “WhereClause” parameter that can be used to restrict the number of records that are returned in this class. For instance, perhaps you only want to return the hydrant inspections done by an employee by the name of Steve Smith. You could call the Search Cursor( ) method as follows to accomplish this limitation on the records returned.
searchCursor = gp.SearchCursor(“Hydrants”,”Ins_By = “Steve Smith”)
After the SearchCursor( ) method has been called and returned a SearchCursor object, you can access the individual Row objects within the SearchCursor object through the Next and Reset methods.
When the SearchCursor is initially created, a pointer is placed at the top of the rows returned, just above the first record. To obtain the first Row in the cursor you will need to make a call to the Next( ) method similar to the code example below.
row = searchCursor.Next( )
Each successive call to the Next( ) method will return the next Row in the cursor until the end of the record collection has been reached at which point the row variable will be set to a value of “None”. Cursor objects are referred to as “forward-moving” objects which simply means that you can move forward one record at a time, but not backwards. However, you can use the Reset( ) method to reset the pointer back to the top of the cursor.
You will notice that the Row object returned by a Search Cursor is slightly different than a Row object returned by an Insert or Update Cursor. Rows returned in a SearchCursor object do not have a SetValue( ) method. The reason for this is that SearchCursor’s are read-only objects so you can’t update or insert values into these records.
Take a look at the following Python code example that shows how you can use the SearchCursor object to obtain a read only set of rows from a table.
The UpdateCursor method on GpDispatch is used to return an UpdateCursor object which is used to update or delete records from a table or feature class.
This class contains Next( ) and Reset( ) methods for navigating through the records that were returned along with an UpdateRow( ) method for updating values in the table or feature class and a DeleteRow( ) method for deleting records. Similar to the SearchCursor( ) method, the UpdateCursor( ) method on GpDispatch can also include an optional “WhereClause” parameter that can be used to restrict the number of records that are returned in this object.
Rows can be updated in an UpdateCursor through the SetValue( ) method and the FieldName property.
Take a look at the code example below to see an example of how you can use an UpdateCursor to delete records from a table.
Each Row object in a FeatureClass has an associated Geometry object containing the geometric content for the row. This is more commonly known as the “Shape” field. When you access the “Shape” field from a Row object a Geometry object is returned, and contains a number of read only properties that give you geographic information about the current row. Notice the relationship between Row objects and Geometry objects in the figure below.
Some of the more commonly used properties include:
Type – data type (point, polyline, polygon)
Extent – geographic extent (bounding box) of the feature
Area – area of a polygon feature
Length – length of a polyline feature
Geoprocessor cursor structures provide you with the ability to query, insert, update, and delete records from Feature Classes and Tables. These easy to create and flexible cursor structures are in-memory collections of records that can be constrained through the use of a “WhereClause” parameter that can be used on the GpDispatch methods that create these cursors. Once generated, these cursor structures provide an easy to navigate, forward-moving structure that can be used to investigate the contents of individual records.
Cursor objects are but one small section of the Geoprocessing programming library. To obtain more information on these objects as well as other functionality exposed by this library please see our comprehensive virtual training course “Introduction to Geoprocessing with Python”.
We will be presenting a new Virtual GIS Classroom course, “GIS Programming 101: Mastering Python for Geoprocessing in ArcGIS” starting March 24th and ending April 18th.