ArcObjects Library Reference  (GeoDatabase)    

IFeatureClass.Search Method

Returns an object cursor that can be used to fetch feature objects selected by the specified query.

[Visual Basic 6.0]
Function Search(
    ByVal filter As IQueryFilter, _
    ByVal Recycling As Boolean _
) As IFeatureCursor
[Visual Basic .NET]
Public Function Search ( _
    ByVal filter As IQueryFilter, _
    ByVal Recycling As Boolean _
) As IFeatureCursor
public IFeatureCursor Search (
    IQueryFilter filter,
    bool Recycling
public IFeatureCursor search (
    IQueryFilter filter,
    Boolean Recycling
  IQueryFilter* filter,
  VARIANT_BOOL Recycling,
  IFeatureCursor** Cursor


filter [in]

  filter is a parameter of type IQueryFilter

Recycling [in]

  Recycling is a parameter of type VARIANT_BOOL

Cursor [out, retval]

  Cursor is a parameter of type IFeatureCursor

Product Availability

Available with ArcGIS Engine, ArcGIS Desktop, and ArcGIS Server.


Search will return an IFeatureCursor with all of the features that satisfy some attribute and/or spatial query as specified by an IQueryFilter object. If Nothing is given as the IQueryFilter, then the feature cursor will have all of the features from the feature class.

The recycling parameter controls row object allocation behavior. Recycling cursors rehydrate a single feature object on each fetch and can be used to optimize read-only access, for example, when drawing. It is illegal to maintain a reference on a feature object returned by a recycling cursor across multiple calls to NextFeature on the cursor. Feature objects returned by a recycling cursor should not be modified. Non-recycling cursors return a separate feature object on each fetch. The features returned by a non-recycling cursor may be modified and stored with polymorphic behavior. The Geodatabase guarantees "unique instance semantics" on non-recycling feature objects fetched during an edit session. If the feature object to be retrieved by a call to search has already been instantiated and is being referenced by the calling application, then a reference to the existing feature object is returned.

Feature cursors returned from the Search method cannot be used to update the features in the cursor. The feature cursor returned from the Update method should be used to update those features.

Non-recycling feature cursors returned from the Search method *MUST* be used when copying features from the cursor into an insert cursor of another class.  This is because a recycling cursor reuses the same geometry and under some circumstances all of the features inserted into the insert cursor may have the same geometry.  Using a non-recycling cursor ensures that each geometry is unique.


    //The following function uses an attribute query and a spatial query to get a subset of the features
    //in a feature class. It then loops through those features and calculates their total area.
    public void IFeatureClass__Search(IFeatureClass featureClass)
        //In this function we will use a spatial filter combined with an attribute query to perform the search.
        //You do not have to perform both types of filters on a search, either could be used individually.

        //Construct an envelope to spatially constrain the search
        //(note: Only high-level geometries, envelopes and geometrybags can be used)
        ESRI.ArcGIS.Geometry.IEnvelope envelope = new ESRI.ArcGIS.Geometry.EnvelopeClass();
        envelope.PutCoords(508786, 681196, 513033, 684341);

        //create a spatial query filter
        ISpatialFilter spatialFilter = new SpatialFilterClass();

        //specify the geometry to query with
        spatialFilter.Geometry = (ESRI.ArcGIS.Geometry.IGeometry)envelope;

        //specify what the geometry field is called on the Feature Class that we will be querying against
        String shpFld = featureClass.ShapeFieldName;
        spatialFilter.GeometryField = shpFld;

        //specify the type of spatial operation to use
        spatialFilter.SpatialRel = esriSpatialRelEnum.esriSpatialRelIntersects;

        //create the where statement, in this case we only want the features
        //in the envelope which have a subtype value of "COM"
        spatialFilter.WhereClause = "subtype = 'COM'";
        //cast the spatial filter to the IQueryFilter interface
        IQueryFilter queryFilter = new QueryFilterClass();
        queryFilter = (IQueryFilter)spatialFilter;

        //preform the search on the supplied feature class; use a cursor to hold the results
        IFeatureCursor featureCursor = featureClass.Search(queryFilter, false);

        //get the first feature returned
        IFeature feature = featureCursor.NextFeature();
        //get the "Area" field
        IFields fields = featureCursor.Fields;
        int areaIndex = fields.FindField("Area");

        //a variable to hold the total area
        Double searchedArea = 0;

        //loop through all of the features and
        //calculate the sum of all of the areas
        while (feature != null)
            searchedArea = searchedArea + (Double)feature.get_Value(areaIndex);
            feature = featureCursor.NextFeature();

        Console.WriteLine("The total area of searched features is {0}", searchedArea);


[Visual Basic 6.0]

The following example uses an attribute query to get a subset of the features in a feature class. It then loops through those features and calculates their total area.

Dim pFeatcls As IFeatureClass 
Dim pFeatLayer As IFeatureLayer 
Dim pDoc As IMxDocument 
Dim pMap As IMap 

Set pDoc = ThisDocument 
Set pMap = pDoc.Maps.Item(0) 
Set pFeatLayer = pMap.Layer(0) 
Set pFeatcls = pFeatLayer.FeatureClass 

' +++ create the query filter, and give 
' +++ it a where clause 
Dim pQFilt As IQueryFilter 
Dim pFeatCur As IFeatureCursor 

Set pQFilt = New QueryFilter 
pQFilt.WhereClause = "subtype = 'COM'" 
Set pFeatCur = pFeatcls.Search(pQFilt, False) 

' +++ get the area field 
Dim pFlds As IFields 
Dim pFld As IField 
Dim lAIndex As Long 

Set pFlds = pFeatcls.Fields 
lAIndex = pFlds.FindField ("Area") 
Set pFld = pFlds.Field(lAIndex) 

' +++ a variable to hold the total area 
Dim dtotArea As Double 
dtotArea = 0# 

' +++ loop through all of the features and 
' +++ calculate the sum of all of the areas 
Dim pFeat As IFeature 
Set pFeat = pFeatCur.NextFeature 
dtotArea = dtotArea + pFeat.Value(lAIndex) 
Set pFeat = pFeatCur.NextFeature 
Loop Until pFeat Is Nothing 

' +++ send the total area to a message box 
MsgBox dtotArea 

See Also

IFeatureClass Interface | IQueryFilter Interface


Feedback Send feedback on this page