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 .NET]
Public Function Search ( _
    ByVal filter As IQueryFilter, _
    ByVal Recycling As Boolean _
) As IFeatureCursor

[C#]
public IFeatureCursor Search (
    IQueryFilter filter,
    bool Recycling
);

[C++]
HRESULT Search(
  IQueryFilter* filter,
  VARIANT_BOOL Recycling,
  IFeatureCursor** Cursor
);

[C++]
Parameters
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.

Remarks

Search will return an IFeatureCursor with all of the features that satisfy the attribute and/or spatial constraints as specified by an IQueryFilter reference. If a null value is passed to the filter parameter, the feature cursor will return 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. Features 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. In other words, if the feature retrieved by a search cursor has already been instantiated and is being referenced by the calling application, then a reference to the existing feature object is returned.

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.

Existing rows can be edited with either a search cursor or an update cursor. When using a search cursor, NextRow is called, returning a reference to a row. The row is edited, and IRow.Store is called. When using an update cursor, NextRow is called, the row is edited, and ICursor.UpdateRow is called with the row as a parameter. It is important to remember, when using an update cursor, do not call the Store method.

In the same way, rows can be deleted using a search cursor or an update cursor, with IRow.Delete used instead of IRow.Store, and ICursor.DeleteRow used instead of ICursor.UpdateRow.

The recommended approach depends on whether or not the edits are being made in an edit session, if the cursor is being used by ArcMap or by an Engine application, and if the features being edited are simple or complex. The table below shows which approach to use in different situations:

	ArcMap	Engine - Simple	Engine - Complex
Inside edit sessions	Search Cursor	Search Cursor	Search Cursor
Outside edit sessions	Search Cursor	Update Cursor	Search Cursor

A search cursor is always recommended in ArcMap, because the query may be satisfied by the contents of the map cache, making a DBMS query unnecessary.

When working with simple features and edit sessions in an Engine application, it's recommended that a search cursor be used to take advantage of batched updates in edit operations. With complex features, on the other hand, update calls are overridden by the features' custom behavior, meaning that the feature's store method will be called even if an update cursor is used.

When using cursors within an edit session, they should always be scoped to edit operations. In other words, a cursor should be created after an edit operation has begun and should not be used once that edit operation has been stopped or aborted.

.NET Snippets

Get All Features from Point Search in GeoFeatureLayer | Perform Spatial Query | Get First Feature from Point Search in GeoFeatureLayer |

.NET Samples

Closest facility solver (Code Files: frmClosestFacilitySolver) | Editing using a custom form (Code Files: EditorForm) | Extending the replication synchronization process (Code Files: RasterSyncWorkspaceExtension) | Import signposts (Code Files: SignpostUtilities) | Location-allocation solver (Code Files: frmLocationAllocationSolver) | Multivariate renderer (Code Files: MultivariateRenderer) | Origin-destination cost matrix solver (Code Files: frmODCostMatrixSolver) | Play back tracking data (Code Files: PlaybackDataButton) | Route layer (Code Files: Program) | RSS weather GraphicTracker (Code Files: RSSWeather) | RSS weather layer (Code Files: RSSWeatherLayerClass) | Server spatial query COM utility (Code Files: VegUtils_VBNet) | Service area solver (Code Files: frmServiceAreaSolver) | StreetMap routing (Code Files: RoutingForm) |