IMapServer3.QueryData Method

Returns a record set of rows that meet the query filter selection criteria for the specified table.

[Visual Basic .NET]
Public Function QueryData ( _
    ByVal MapName As String, _
    ByVal pMapTableDescription As IMapTableDescription, _
    ByVal Filter As IQueryFilter, _
    ByVal options As IQueryResultOptions _
) As IQueryResult

[C#]
public IQueryResult QueryData (
    string MapName,
    IMapTableDescription pMapTableDescription,
    IQueryFilter Filter,
    IQueryResultOptions options
);

[C++]
HRESULT QueryData(
  BSTR MapName,
  IMapTableDescription* pMapTableDescription,
  IQueryFilter* Filter,
  IQueryResultOptions* options,
  IQueryResult** QueryResult
);

[C++]

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

  pMapTableDescription is a parameter of type IMapTableDescription
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

Remarks

QueryData returns the records of map features from a layer or of rows from a table that match the parameters of a given query filter. QueryData returns a QueryResult. A QueryResult format can be a RecordSet, a KMZ, JSON or AMF. The Format of the QueryResult is specified in QueryResultOptions. QueryResultOptions can also be used to specify a GeoTransformation if one is needed.

QueryData requires a number of input parameters. These include: a MapName, IMapTableDescription and a IQueryFilter. The QueryFilter can be an attribute query (SQL expression), a spatial query, a time query, a combination of all or null. ILayerDescription2 has SourceID property that can be used to query against a GP result.

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 syntax 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. You may get the list of all visible fields from IMapTableInfo::Fields. Please note ObjectID field is always returned regardless of whether it is in the SubFields or not. Only expection is when DISTINCT is used.

When only the unique value from a field is desired, you need to set PrefixClause="DISTINCT". In case when you want the result sorted by field(s), set ORDER BY <field1, field2,...> to PostfixClause. Please note these options will only be honored when the source database supports that such as ArcSDE GeoDatabase, File GeoDatabase and Personal GeoDatabase.

Note: MapServer query function does not support raster data. You should avoid including raster field from SubFields.

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.

Values in StartTimeField or EndTimeField are returned in the Layer's TimeReference. If the desired time reference is different than the layer's one, OutputTimeReference should be explicitly set.

SearchShape

It is only required for spatial query. Since a table does not contain geometry, SearchShape is ignored when a table is queried. Geometry set in SpatialFilter 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 Polygon.

DefinitionExpressions

A DefinitionExpression can be set on a layer or a standalone table in order to limit layer features or rows 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 or StandaloneTableDescription will override any definition query set in the source map. MapServer QueryData 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 DefinitionExpression 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. QueryData 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 definition 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. QueryData honors the DefinitionExpression set in LayerDescription.

Results

For KML (Keyhole Markup Language), JSON (JavaScript Object Notation) or AMF (Action Message Format), result can be passed back as a URL (when QueryResultOptions.Format is esriQueryResultKMLAsURL) or as a MIME object (when QueryResultOptions.Format is esriQueryResultKMLAsMime).

KML 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

QueryData 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.

The main differences between QueryData & QueryFeatureData are that the former can search both layer and table and honors their settings e.g. DefinitionExpression etc.

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

.NET Related Topics