Working with query cursors (ArcObjects .NET 10.8 SDK)

Summary

This topic explains how to create and use a query cursor to execute Structured Query Language (SQL) queries against a database and work with the result set in ArcGIS as a cursor.

In this topic

Eligibility of data for query cursors
Creating a query cursor

Eligibility of data for query cursors

Query cursors are slightly more flexible than query classes with the types of queries they can use. Unique identifiers are not needed for query cursors like they are for query classes. Since a query description is not created as an intermediate step, ID mapping cannot be specified. However, other query class restrictions do apply to query cursors, such as the following:

Geometry fields - A geometry field is not required, but a maximum of one geometry field can be in the result set.
Spatial references - All geometries in a geometry field should share the same spatial reference identifier (SRID).

If these restrictions are violated, creating the cursor will not immediately fail, but an error will be raised when the first row is retrieved from the cursor (or when the first row with a different spatial reference is retrieved, in the second case).

One notable difference from query classes is that the rows returning a query cursor can contain different geometry types. That is, if a table contains a single geometry column with a combination of point, lines, and polygons in different rows, a query cursor can still be used to read each row.

Creating a query cursor

To create a query cursor, pass an SQL query into the ISqlWorkspace.OpenQueryCursor method; the cursor is returned.

The following code example shows how a query cursor can be used to read the rows of a SQL join:

[C#]

// Construct an SQL query.
StringBuilder queryBuilder=new StringBuilder();
queryBuilder.Append("SELECT CITY_NAME, STATE_NAME, CITYSHAPE ");
queryBuilder.Append("FROM CAPITALS JOIN STATES ");
queryBuilder.Append("ON CAPITALS.FIPS=STATES.FIPS ");
queryBuilder.Append("ORDER BY CITY_NAME");
String query=queryBuilder.ToString();

using(ComReleaser comReleaser=new ComReleaser())
{
    // Create the query cursor.
    IFeatureCursor featureCursor=(IFeatureCursor)sqlWorkspace.OpenQueryCursor
        (query);
    comReleaser.ManageLifetime(featureCursor);

    // Iterate through the features.
    IFeature feature=null;
    while ((feature=featureCursor.NextFeature()) != null)
    {
        // Write the values to the console.
        Console.WriteLine("City: {0}", feature.get_Value(0));
        Console.WriteLine("State: {0}", feature.get_Value(1));
        IPoint point=feature.get_Value(2)as IPoint;
        if (point != null)
        {
            Console.WriteLine("Location: {0}, {1}", point.X, point.Y);
        }
    }
}

[VB.NET]

' Construct an SQL query.
Dim queryBuilder As StringBuilder=New StringBuilder()
queryBuilder.Append("SELECT CITY_NAME, STATE_NAME, CITYSHAPE ")
queryBuilder.Append("FROM CAPITALS JOIN STATES ")
queryBuilder.Append("ON CAPITALS.FIPS=STATES.FIPS ")
queryBuilder.Append("ORDER BY CITY_NAME")
Dim query As String=queryBuilder.ToString()

Using comReleaser As ComReleaser=New ComReleaser()
' Create the query cursor.
Dim featureCursor As IFeatureCursor=CType(sqlWorkspace.OpenQueryCursor(query), IFeatureCursor)
comReleaser.ManageLifetime(featureCursor)

' Iterate through the features.
Dim feature As IFeature=featureCursor.NextFeature()
While Not feature Is Nothing
    ' Write the values to the console.
    Console.WriteLine("City: {0}", feature.Value(0))
    Console.WriteLine("State: {0}", feature.Value(1))
    Dim point As IPoint=TryCast(feature.Value(2), IPoint)
    If Not point Is Nothing Then
        Console.WriteLine("Location: {0}, {1}", point.X, point.Y)
    End If
    feature=featureCursor.NextFeature()
End While
End Using

Query cursors can implement the IFeatureCursor interface, depending on whether or not their query includes a geometry column.

Query cursors are always non-recycling cursors, providing them with the flexibility to handle multiple geometry types in a single column.

Development licensing	Deployment licensing
ArcGIS Desktop Basic	ArcGIS Desktop Basic
ArcGIS Desktop Standard	ArcGIS Desktop Standard
ArcGIS Desktop Advanced	ArcGIS Desktop Advanced
Engine Developer Kit	Engine

Working with query cursors

In this topic

Eligibility of data for query cursors

Creating a query cursor

See Also: