MapDotNet UX Help

The MapDotNet UX query model is used to represent queries against spatial data sources.  It has classes that encapsulate spatial queries and the resulting data sets.  Typically the query model is used to create queries against map layers.  Queries can also be constructed to query data tables that are not represented by map layers but this is a less common scenario.

The query model uses classes in ISC.MapDotNetServer.Common and ISC.MapDotNetServer.Common.Data.  Note that the contents of these namespaces are slightly different under Silverlight.  These differences will be discussed where applicable.

The Query Request

The QueryRequest class is used to encapsulate queries.  A QueryRequest is serialized and passed to the feature service, FeatureService.svc.  In the RIM controls, the Services class can be used to create a client proxy for the feature service.  Otherwise, you can create one from a service reference.

The QueryRequest can contain queries against multiple map layers or other data sources.  These queries may have optional attribute filters, but any spatial filter is at the level of the QueryRequest and applies to all contained Query objects.

Properties of the QueryRequest class include:

  • ShapeFilterSerial - if present, a serialized Shape object that will be used for a spatial filter.  Point, Multipoint, Polyline, or Polygon shapes may be used and each has a Serialize method.  Envelope is not supported, instead use Envelope.ToPolygon().
  • ShapeFilterOperation - the spatial filter operation to perform, or NO_OPERATION for no spatial filter.  Most of the enumerated operations are pretty straightforward but two merit being noted here:
    • DRILL_DOWN - an AREA_INTERSECT filter, but any filter buffering is ignored when the target layer is a polygon layer.  This is useful for searching across multiple layers for features under a point, as a buffer will be needed to capture point or line data.
    • FAST_APPROXIMATE_INTERSECT - basically an AREA_INTERSECT that is allowed to optimize for speed at the cost of including false positives.  Typically this will use a bounding box intersection or an index-based test without a subsequent shape intersection test.
  • ShapeFilterCoordSys - the coordinate system that the spatial filter is in.  This should usually be a ProjCoordSys.  Use WKTCoordSys when the back end is ArcSDE and you want the data source to handle coordinate transformations.
  • ShapeFilterBufferDistance - if greater than zero, a buffer distance for the search shape in the units the shape will be in at the point of buffering.
  • ShapeFilterBufferAndTransformSequence - indicate whether to buffer first or transform the coordinate system first.  You must transform first (default) unless you are using the data source to handle the transform.
  • UseDataSourceToTransform - indicates whether to use the data source rather than MapDotNet to do coordinate system transformation.  Default is false.  Neither SQL Server 2008/2012 nor shape files can use the data source to transform.
  • ReturnShapes, ReturnShapeBounds, ReturnResultSetBounds - indicate whether you want back, respectively, shapes, shape boundaries, or result set boundaries.
  • ReturnTypes - indicate whether you want data type information returned.  (All data is returned in string form.)
  • MaxRows - the maximum number of rows to return for any single query, or 0 for no limit.  For SQL Server 2008/2012 data sources, use of a row limit can cause performance degradation by causing the spatial index to be ignored.  It may be more efficient to limit result set processing within your application code.  Another option is to use a MapLayerDataSourceSpecification.IndexHintOverride.  (See "Query Objects" below.)
  • ResultShapeCoordSys - the coordinate system to return shapes and bounds in.  This should usually be a ProjCoordSys.  Use WKTCoordSys when the back end is ArcSDE and you want the data source to handle coordinate transformations.
  • ResultShapeBufferDistance - a buffer distance for returned shapes in the units the shape will be in at the time of buffering.
  • ResultShapeBufferAndTransformSequence - indicate whether to buffer first or transform the coordinate system first.  You must buffer first (default) unless you are using the data source to handle the transform.
  • Queries - a collection of Query objects indicating data layers to query.

Query Objects

The Query class encapsulates a single data source to query within a QueryRequest object that may encompass a number of data sources.

Properties of the Query class include:

  • DataSourceSpecification - this can refer to either a ConnectionDataSourceSpecification or a MapLayerDataSourceSpecification.  The MapLayerDataSourceSpecification is more commonly used.  A MapLayerDataSourceSpecification has the following properties:
    • MapID, LayerID - together, these refer to the map layer to query.  Connection information will be obtained for that layer on the server.
    • WhereClauseOverride - this can be used to override any attribute filters that are present in the map layer.  Only use this if you know the layer has a ConnectionSpecification.WhereClause you do not want applied.  Otherwise, use the Query.Filter property which will be combined with the ConnectionSpecification.WhereClause of the layer.  See notes below under Filter for use of this with shapefile data sources.
    • IndexHintOverride - this is used to specify a specific index to use.  Only the index name is needed.  Currently this is only supported for Sql Server 2008 and ignored for other providers (PostGIS does not support index hints.)  There are only a few cases where it is recommended that you use this.

      • You set up multiple spatial indexes for a Sql Server 2008 geometry column and wish to specify a particular one for your spatial query.  (Note that the query engine will attempt to find the best match anyway.)
      • You specified a spatial index in Studio (i.e. in the layer's ConnectionSpecification).  If your query has no spatial component, assign an empty string to override the hint on the ConnectionSpecification and use no index.
      • You have set a Filter for the query and wish to use an index on one of the columns referenced by the filter.
      • You are using both a query Filter and a shape filter and you do not want the query engine to force use of a spatial index.  Use an empty string for no index specification.
    Use a ConnectionDataSourceSpecification only if you know the complete connection information.  This can be used to query data tables that are not associated with maps.  Note that although Layer.ConnectionSpecification is a ConnectionDataSourceSpecification, in client code a layer's ConnectionSpecification is unusable because the connection string is stripped from it.  This scenario is not supported under Silverlight.
  • ID - an optional query ID.  If provided, this will be used as the name of the QueryResultTable returned for this query.  Otherwise, the layer name is used.
  • Filter - an optional attribute filter for the query.
    • For most data sources, this is a string using SQL where clause syntax.
    • For shapefile and KML data sources only, this is very restricted.  Only <, <=, =, >=, !=, and "LIKE" are supported.  "LIKE" may be used only with a '%' wildcard at the end of the string (i.e. to support auto-complete).  Each expression must have a column name on one side and a value on the other.  Expressions may only be joined with AND.
    • For KML, Folder can be used as a filter.  "Folder = '/Polygons'" will return only data directly in the /Polygons folder, not in /Polygons/Buildings.  Use the * wildcard to include subfolders  "Folder = '/Polygons/*'" will return data from both /Polygons and /Polygons/Buildings
  • DataSelectionKeyword - an enumeration of ALL (default), DISTINCT, MIN, or MAX.  For any but ALL, only a single Field should be specified.  DISTINCT returns distinct values.  MIN and MAX return the limits of numeric columns.
    For ArcSDE data sources only, keywords other than ALL are restricted.  They may only be used where there is no Filter, no QueryRequest.SpatialFilter, and no Layer.ConnectionSpecification.WhereClause.  (See WhereClauseOverride above.)
  • Fields - a list of names of columns to return for the table.  "*" may be used to return all columns.  It is not necessary to include the geometry column, spatial data is returned if and only if QueryRequest.ReturnShapes is set true.
    For KML, available fields are GeometryIndex, name, description, and folder.  These correspond to to the 0-based index of the Placemark in the KML file, the Placemark name and description elements, and the hierarchy of any named Folders that contain the placemark.
  • Sort - simple sorting instructions for the query results.  The QuerySort object has the following properties:
    • Field - a column name.  Only a single field may be sorted on.
    • Direction - indicates whether to sor ascending or descending.
    • Type - indicates how to sort - as numbers, dates, or text with or without case sensitivity.

The Query Response

A service call to the Query method returns a serialized QueryResponse.

The QueryResponse class has the following properties:

  • Error - if an error prevented the processing of the queries, this will be set with an error message.
  • Canceled - if this is true, a cancel request was received before the queries were complete.
  • QueryResultTables - if there is no Error and Canceled is false, this is a list of QueryResultTables, one for each Query object in the request, in the same order.

QueryResultTable objects

The QueryResultTable class encapsulates the data returned for a single Query object.

The QueryResultTable class has the following properties:

  • Error - if set, a message about an error that prevented processing this query.
  • Name - the name of the QueryResultTable.  The query ID, if it was set, or the layer ID, if a map layer was queried, or the data table name.
  • ResultSetBoundsSerial - if QueryRequest.ReturnResultSetBounds was set true, this will be a serialized Envelope representing the boundary of the result set.
  • HasTypes - indicates whether column type data is available.  Set QueryRequest.ReturnTypes to true to retrieve type data.
  • TypeNames - if HasTypes is true, the string name of the appropriate .Net type for each field.
  • Fields - the column names for data returned.  Note that if the geometry column was included in Query.Fields, it will be omitted here.
  • QueryResultRows - a collection of zero or more rows containing the data retrieved by the query.

The GetDataTable() method can be called to get an ADO.Net DataTable containing the query data.  When HasTypes is true, the table columns will be typed.  A column called "Geometry" will be added with serialized shapes, if available.  This method is not available under Silverlight.

QueryResultRow objects

The QueryResultRow class contains a single row of data retrieved by a query.

TheQueryResultRow class has the following properties:

  • ShapeSerial, Shape - serialized and unserialized versions of the record's geometry as a Shape or its serial representation, if QueryRequest.ReturnShapes was set true.  These properties are bound to each other and will always reflect the same geometry.
  • ShapeBoundsSerial - a serialized Envelope representing the boundary of the geometry, if QueryRequest.ReturnShapeBounds was set true.
  • Values - string representations of the field values, in the same order as QueryResultTable.Fields.

Feature Service Methods

The following methods are used to query.

public string BeginQuery(string queryRequest, Guid cancelWorkKey);

Returns a serialized QueryResponse containing the requested data.  queryRequest is a serialized QueryRequest.  The server implementation is asynchronous.  If you use an asynchronous client method, you can provide a Guid as the cancelWorkKey and the Guid can be used as an argument to CancelQuery.  Make sure you use a different Guid in each call to BeginQuery.  If you are not using asynchronous client processing you can pass Guid.Empty as the cancelWorkKey.

void CancelQuery(Guid cancelWorkKey);

Call this to cancel a pending query when using asynchronous client methods.  Your BeginQuery callback handler will still be called but if the cancel request was received before the queries were completed, the Canceled flag will be set on the query response.  If a cancel request is received after a query request is complete it is ignored.

For more on asynchronous client methods, see