IMapServer3.QueryFeatureData2 Method

Returns a record set of features that meet the query filter selection criteria for the specified layer.

[Visual Basic .NET]
Public Function QueryFeatureData2 ( _
    ByVal MapName As String, _
    ByVal pLayerDesciscription As ILayerDescription, _
    ByVal Filter As IQueryFilter, _
    ByVal options As IQueryResultOptions _
) As IQueryResult

[C#]
public IQueryResult QueryFeatureData2 (
    string MapName,
    ILayerDescription pLayerDesciscription,
    IQueryFilter Filter,
    IQueryResultOptions options
);

[C++]
HRESULT QueryFeatureData2(
  BSTR MapName,
  ILayerDescription* pLayerDesciscription,
  IQueryFilter* Filter,
  IQueryResultOptions* options,
  IQueryResult** QueryResult
);

[C++]

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

  pLayerDesciscription is a parameter of type ILayerDescription
Filter [in]

  Filter is a parameter of type IQueryFilter
options [in]

  options is a parameter of type IQueryResultOptions
QueryResult [out, retval]

  QueryResult is a parameter of type IQueryResult

Product Availability

Description

Note: this has been superceded by QueryData.

Remarks

QueryFeatureData2 returns the records of map features that match the parameters of a given query filter. QueryFeatureData2 returns a QueryResult. A QueryResult format can be either KML or a RecordSet. The Format of the QueryResult is specified in QueryResultOptions. QueryResultOptions can also be used to specify a GeoTransformation if one is needed.

QueryFeatureData2 requires a number of input parameters. These include: a Name, LayerDescription and a QueryFilter. The QueryFilter can be an attribute query (SQL espression), a spatial query, a combination of both or null. ILayerDescription2 has SourceID property that can be used to query against a GP result.

QueryFilter

QueryFilter provides the ability to query based on attribute filter (SQL expression) a spatial filter, or a combination of both. 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.

It can be set to null or Nothing to retrieve all data (which is also limited by MaxRecordCount)

If geometry is not desired in the output RecordSet, IQuerFilter�s SubFields must be defined without �Shape� field. When SubFields is empty or includes �Shape�, IRecordSet will include the fields "shape_length" and "shape_area". If the desired spatial reference of the output geometry is different than the original one, OutputSpatialReference should be used. Otherwise geometry is returned in the same spatial reference system as the DefaultMapDescription by default. When SubFields is not defined or=�*�, it returns all visible fields. Invisible or invalid field names or field aliases must not be included in SubField�s string or it will return an error.  Please note ObjectID field is always returned regardless of whether it is in the SubFields or not. Only expection is when DISTINCT is used.

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 QueryFeatureData2 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 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 all sale region features with sales over 1000 and are managed by Bob. QueryFeatureData2 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 all sale region features with sales over 1000 and are managed by Bob. QueryFeatureData2 honors the DefinitionExpression set in LayerDescription.

Results

The result can be returned in two formats: KML and RecordSet.

KML
When KML is the desired output, it is passed back as a URL (when QueryResultFormat is esriQueryResultKMLAsURL) or as a MIME object (when QueryResultFormat is esriQueryResultKMLAsMime). The file or Mime is returned in compressed KMZ format.

Setting LayerResultOptions has no effect on KML output.

RecordSet
When esriQueryResultRecordSetAsObject is selected as QueryResultFormat, the function returns RecordSet as an Object. Use IQueryResult::Object property to access that. The returned object needs to be QI to IRecordSet.

Result Geometry

By default, geometry is returned in the same spatial reference as the DefaultMapDescription. The spatial reference of QueryFeatureData2 results can be set to something different than the DefaultMapDescription by using OutputSpatialReference.  OutputSpatialReference is a property of IQueryFilter.  For SOAP/WSDL users, both OutputSpatialReference & SpatialReferenceFieldName properties are required and must be set.

In some instances the result may require a GeoTransformation . For example, a given map service may be using a spatial reference system based on GCS_WGS_1984. A client wants to display QueryFeatureData2 results based on this map service in a different spatial reference, GCS_European_1950. The results will use the spatial reference of the DefaultMapDescription, GCS_WGS_1984, and display these results incorrectly in GCS_European_1950. Features may not "line up" correctly. In order to correctly display these results a GeoTransformation is needed. Applying the correct GeoTransformation ensures the spatial correctness of the result.

Another instance where a GeoTransformation may be need to be specified in the QueryResultsOption is if the queried layer is projected on the fly within the map service. That is, the coordinate system of the layer's source is different than the DefaultMapDescription coordinate system, and no appropriate transformation has been set in the map document before serving. In this case, you can access the coordinate system of a layer source by first getting the layer's MapLayerInfo, then get Fields from MapLayerInfo, get the Shape  Field from Fields, get GeometryDef from Field, and finally, get the SpatialReference from GeometryDef.

A GeoTransformation is not needed if the projected coordinate systems share the same underlying geographic coordinate system. For best results it is optimal for data (layers within the map service), map service and MapServer output to use the same coordinate system.

In some cases, may be for performance reasons, you may want limit or adjust the geometry being returned in the record set result. Use ILayerResultOptions to manage this. If IncludeGeometry is set to False, geometry is not included in the recordset. This should increase performance in cases where feature geometry is large. You can also choose to densify or generalize the returned geometry by using GeometryResultOptions. Densification is used to better support clients that do not support Arcs (e.g. Bezier, Circular etc.). Generalization reduces the amount of geography being sent across the network and should lead to better performance.

Field visibility and field aliases

QueryFeatureData2 honors field visibility and field aliases set in the source map document. However, the RecordSet does NOT honor any field formatting set in the source map.

Miscellaneous

In order to control the amount of information MapServer needs to process for a query, a maximum number of records can be set. This value is contained in the MaxRecordCount property on IMapServerInit2. The default value for this property is 500. If 600 features match a given query only the first 500 results will be returned. You will be unable to access the remaining 100 records. To be able to access these records the MaxRecordCount would need to be increased to 600. MaxRecordCount can also be changed by modifying the MaxRecordCount XML tag in the MapServer's configuration file.

There are two key differences between Find and QueryFeatureData2. The first is that Find can work on multiple layers while the query methods work with a single layer. The second is that Find only works with a search string. The query methods use a queryFilter as a parameter. This allows the query to be based on either an attribute filter (SQL expression) or a spatial filter.

Precedence. In case where both IQueryFilter::SubField and ILayerResultOption::IncludeGeometry is set, SubField takes precedence over IncludeGeometry. For example, when SubField=�Shape, FName, LName, Address� and IncludeGeometry=False, the output recordset will contain geometry as contained within the Shape field.

See Also