IMapServer3.QueryRowIDs Method

Returns the IDs of the rows that meet the query filter selection criteria for the specified table.

[Visual Basic .NET]
Public Function QueryRowIDs ( _
    ByVal MapName As String, _
    ByVal pTableDescription As IMapTableDescription, _
    ByVal pFilter As IQueryFilter _
) As ILongArray

[C#]
public ILongArray QueryRowIDs (
    string MapName,
    IMapTableDescription pTableDescription,
    IQueryFilter pFilter
);

[C++]
HRESULT QueryRowIDs(
  BSTR MapName,
  IMapTableDescription* pTableDescription,
  IQueryFilter* pFilter,
  ILongArray** FIDs
);

[C++]

Parameters
MapName [in]
  MapName is a parameter of type BSTR
pTableDescription [in]

  pTableDescription is a parameter of type IMapTableDescription
pFilter [in]

  pFilter is a parameter of type IQueryFilter
FIDs [out, retval]

  FIDs is a parameter of type ILongArray

Product Availability

Remarks

QueryRowIDs returns an array of ObjectIDs unlike QueryFeatuerIDs or QueryFeatureIDs2. Each integer represents a unique identifier for each feature (FID) of a layer or row of a table being queried.

Please note quering a table with no ObjectID field (such as Excel, text files etc.) fails. You may want to check OIDFieldName to find out whether the table has ObjectID field.

The key differences between QueryRowIDs and QueryFeatureIDs2 are:

• Both table or layer can be queried with QueryRowIDs
• QueryRowIDs returns IDs sorted by a field, when ORDER BY is set on queryfilter's PostfixClause and the underlying datasource supports that.

QueryRowIDs requires a number of input parameters. These include: a MapName, IMapTableDescription and a IQueryFilter.

LayerDescription for a layer can be obtained from MapServerInfo::DefaultMapDescription while StandaloneTableDescription can be obtained using MapServerInfo::StandaloneTableDescriptions property.

QueryFilter 

QueryFilter provides the ability to query based on attribute filter (SQL expression), a spatial filter, time filter, a combination of both or null. Attribute filters take any valid ‘non-GIS data specific’ SQL statement. For example, CNTRY_CODE=‘BD’ or POPULATION=12345. Syntax for querying date fields depend on the underlying data. If you are working with Shapefile or File GeoDatabase data the syntax is <FieldName>=date ‘YYYY-MM-DD’; for Access-based Personal GeoDatabase the sytax is #YYYY-MM-DD#. For SDE database, check with the specific database’s help.

TimeQueryFilter

When a layer is time aware (use IMapTableTimeInfo::SupportsTime property), a query can be made to retrieve a set of features that are available at a specific time or for a period of time. In order to perform a time query, TimeQueryFilter object needs to created and passed in to this function. Since the object implements IQueryFilter and ISpatialFilter interfaces, an attribute or spatial query can be combined with time.

SearchShape 

Geometry set in ISpatialFilter should meet the following criteria:

• It should have the Spatial Reference System defined. In cases where it is not defined, the coordinate system is assumed to be in DataFrame’s coordinate system
• It must be one of the high-level geometries i.e. Point, Multipoint, Polyline, Polygon or Multipatch. Low-level geometry e.g. BezierCurve, CircularCurve must be wrapped into a high-level geometry
• It must be topologically correct. For more information, see help on IPolygon and ITopologicalOperator::Simplify .

DefinitionExpressions

A DefinitionExpression can be set on a layer in order to limit layer features available for display or query. This expression can be also be set in the source map document as a definition query. Any DefinitionExpression set in the LayerDescription will override any definition query set in the source map. MapServer QueryFeatureIDs2 honors DefinitionExpression.

Let's look at some examples. You have a layer in your map that represents sales regions. The layer includes fields REGIONS, SALES and MANAGER.

Example #1: In the source map the layer has a definition query, "REGION='North'". No DefintionExpression is specified in LayerDescription. Your QueryFilter where clause is "MANAGER='Bob'". The result will be the ids of all sale region features that fall within the North region and are managed by Bob.

Example #2: In the source map the layer has a definition query, "REGION='North'". You apply a DefinitionExpression in LayerDescription as "SALES > 1000". Your QueryFilter where clause is "MANAGER='Bob'". The result will be the ids of all sale region features with sales over 1000 and are managed by Bob. QueryFeatureIDs2 honors the DefinitionExpression set in LayerDescription. The DefinitionExpression overrides the definition query set in the source map. If you wish to include the layer's original defintion query, "REGION='North'" in your final query, you must include this in your QueryFilter, ""MANAGER='Bob' AND "REGION='North'".

Example #3: In the source map the layer has no definition query. You apply a DefinitionExpression in LayerDescription as "SALES > 1000". Your QueryFilter where clause is "MANAGER='Bob'". The result will be the ids of all sale region features with sales over 1000 and are managed by Bob. QueryFeatureIDs2 honors the DefinitionExpression set in LayerDescription.

Page through Result

Result from QueryRowIDs can be used to page through a result. When a query is expected to return a lot of rows and showing all those records on a single page is not desirable, you may use the following steps to page through your result and get records for a selected subset on demand:

• QueryRowIDs to get a list of IDs and hold them in memory on client side
• Get a subset of those IDs and wrapped them in FIDSet or form a WhereClause expression (i.e. OBJECTID=2 or OBJECTID=3)
• Create a QueryFilter and assign FIDSet or WhereClause to it
• Execute a QueryData() function

Miscellaneous

MaxRecordCount does not affect QueryRowIDs.

The results of this function can be used with LayerDescription::SelectionFeatures to display the selection in the exported image.

See Also