Overview
Queries are handled by the
MapControlBridge.Query method and the
Common .Net SDK classes QueryRequest, Query, QuerySort, QueryResponse, QueryResultTable, and QueryResultRow classes. Queries can also be built and executed by the
MapQueryManager class, which also provides support for sophisticated result formatting.
QueryRequest Class
The QueryRequest class encapsulates one or more queries to be executed. Properties include:
- ShapeFilterSerial - if provided, this is a serialized shape that will be used as a spatial filter for all queries included in the request. (Use Shape.SerializeShape to serialize a shape.)
- ShapeFilterOperation - an instance of the ShapeFilterOperations enumeration used to indicate how shapes should be filtered against ShapeFilterSerial. Most of the operations are self-explanatory. "DRILL_DOWN" applies any provided ShapeFilterBuffer to searches against point or line layers but does not apply the buffer to searches against polygon layers. "DRILL_DOWN" is designed to be used for point click or point hover searches across multiple layers.
- ShapeFilterBufferDistance - distance to buffer the shape by. Any non-zero value indicates that buffering is desired. The value should be in the units that the filter is in. If the filter is also being transformed, it should be in the units the filter will be in when it is buffered. See the ShapeFilterBufferAndTransformSequence property below.
- ShapeFilterCoordSys - a CoordSys object representing the coordinate reference system the shape filter is in. This should be set only if the filter is not in the same coordinate reference system as the layer being queried. Review the CoordSys entry for usage information.
- ShapeFilterBufferAndTransformSequence - if the filter is to be both buffered and transformed, this indicates the order of operations. Note that if UseDataSourceToTransform is set false, this should be left at its default value (transform and then buffer).
- ReturnShapes - set true to include shape data in the query response. ArcSDE backends also require that the geometry column be included in the Fields collection of each associated query to return shapes. Other backends do not have this limitation.
- ReturnShapeBounds - set true to include shape envelopes in the query response. ArcSDE backends also require that the geometry column be included in the Fields collection. Other backends do not have this limitation.
- ReturnResultSetBounds - set true to return the envelope of the entire result set. ArcSDE backends also require that the geometry column be included in the Fields collection. Other backends do not have this limitation.
- ReturnTypes - set true to return information about the data types of attributes returned. (All attribute values are returned as strings.)
- MaxRows - if greater than 0, limits the number of rows returned.
- ResultShapeCoordSys - if non-null, the CoordSys to project results shapes to. The projection will be from the coordinate reference system of the layer queried. Review the CoordSys entry for usage information.
- ResultShapeBufferDistance - if non-zero, the distance to buffer result shapes by. This should be in the units of the coordinate system the data is in. If the data is also being transformed, this should be in the units that the data will be in at the time it is buffered. See ResultShapeBufferAndTransformSequence.
- ResultShapeBufferAndTransformSequence - if the data returned is to be both buffered and transformed, this indicates the order of operations. Note that if UseDataSourceToTransform is set false, this should be left at its default value (buffer and then transform).
- UseDataSourceToTransform - indicates whether the underlying data source is used for transforms. This allows greater flexibility when doing both transform and buffer operations, but some data sources (SpatialDB and Sql Server 2008) do not support transforms.
- Queries - a list of Query objects representing queries to perform within the parameters of this QueryRequest.
Query Class
The Query class represents a single query within a QueryRequest. Properties include:
- Layer - the Layer to query.
- Filter - an optional query string to filter results by attribute values.
- Fields - the list of fields in the layer that should be returned by the query.
- QuerySort - if non-null, a sort to apply to query results.
QuerySort Class
The QuerySort class indicates how to sort the results from a query. Properties include:
- Field - the field to sort on.
- Direction - indicates whether to sort ascending or descending.
- Type - indicates whether to sort as text (case-sensitive or otherwise) or as numeric or DateTime data.
QueryResponse Class
The QueryResponse class encapsulates the response to a QueryRequest. Properties include:
- Error - any overall error that prevented executing any queries.
- QueryResultTables - a list of QueryResultTable objects representing the results of the Queries in the QueryRequest.
A useful method of this class is FillDataSet, which takes a DataSet and adds a DataTable to it for each QueryResultTable in this QueryResponse (empty result tables can be optionally omitted.) Table names match the IDs of the layers queried. All data will be in the form of strings. Column names match field names, and serialized shapes are in a column called "Geometry".
QueryResultTable Class
The QueryResultTable class contains the result of a single Query within a QueryRequest. Properties include:
- Name - the ID of the Layer the query was executed against.
- Error - any error that occured executing the query.
- Fields - the fields returned by the query.
- HasTypes - true if type names are available. See QueryRequest.ReturnTypes above.
- TypeNames - if available, a list of type names corresponding to the values in Fields.
- QueryResultRows - a list of QueryResultRow objects representing the data rows returned by the query. This list may be empty if the query had no errors but also found no data.
- ResultSetBoundsSerial - if requested, a serialized Envelope representing the extents of the result set.
A useful method of this class is GetDataTable, which returns a DataTable with the data from this QueryResultTable. The table name is the ID of the layer queried. All data is in the form of strings. Column names match field names, and serialized shapes are in a column called "Geometry".
QueryResultRow Class
The QueryResultRow represents a single row of data returned as part of the result of a single Query within a QueryRequest. Properties include:
- ShapeSerial - if requested, the serialized shape for this row.
- ShapeBoundsSerial - if requested the serialized Envelope for this shape.
- Values - a list of field values, in the same order as in the Fields list of the QueryResultTable that contains this QueryResultRow.
MapControlBridge.Query Method
This method takes a QueryRequest object, passes it to the FeatureService, and returns the resulting QueryResponse.
EditRequest Class
EditRequest encapsulates one or more edits- row inserts, updates, or deletes- to perform against a spatial layer. Properties include:
- Layer - the Layer to edit.
- Data - a DataTable containing rows to insert, update, or delete. Data is interpreted as follows:
- The RowState of each row indicates the action to perform for that row.
- Column names must correspond to layer field names.
- If the geometry is edited, a column with the name of the geometry column should contain string values that are serialized shapes.
- The PrimaryKey property of the table should be set. Updated and deleted rows will be looked up using this key. It does not have to be the actual primary key column of the layer, but if not it should still identify rows uniquely. If there are only inserted rows and not updated or deleted ones a primary key does not have to be specified but for ArcSDE backends, if it is provided it should be the actual primary key column.
- DataCoordSys - a CoordSys representing the coordinate reference system the data is in. This need only be set if there are inserts or updates and the data is not in the same coordinate system as the layer. Review the CoordSys entry for usage information.
- UseDataSourceToTransform - sets whether the internal transformation engine or the data source is used to do any needed transformation. Note that some data sources (SpatialDB and Sql Server 2008) do not support transforms.
MapControlBridge.Edit Method
This method takes an EditRequest, passes it to the FeatureUpdateService, and returns the resulting DataTable. Rows in the DataTable correspond to rows in the Data property of the EditRequest.
If an overall error prevented any edits, the table will have an extended property (DataTable.ExtendedProperties) called "Error" detailing this. If an individual edit had an error, the RowError property of the row will be set to an error message. For ArcSDE backends, if the row was inserted and the PrimaryKey property was set on the EditRequest's Data object then that column will be set with the new primary key value for the row.