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.
See Also:
Working with query classesQuery classes and cursors
To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
ESRI.ArcGIS.ADF.Connection.Local ESRI.ArcGIS.Geodatabase ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)ESRI.ArcGIS.ADF ESRI.ArcGIS.DataSourcesGDB
Development licensing | Deployment licensing |
---|---|
ArcGIS for Desktop Basic | ArcGIS for Desktop Basic |
ArcGIS for Desktop Standard | ArcGIS for Desktop Standard |
ArcGIS for Desktop Advanced | ArcGIS for Desktop Advanced |
Engine Developer Kit | Engine |