9. Queries

Core plugin Query allows to search for geographical objects. Found objects are hilighted and if requested related data are returned to client.

Depending on configuration and user choices, queries are executed on one layer, several layers or all layers currently displayed on map.

Queries can be executed on a geographic selection or using a list of object IDs. Geographic selection can be a point, a rectangle, a polygon or a circle but is a rectangle by default. The second way to execute a query is used in particular to maintain selection persistence: object IDs are stored client-side and sent to server each time the page is reloaded.

Hilighting objects can be done using standard Mapserver queries or using special Hilight plugin. See Section 9.3.3, “Hilight Configuration” for more information.

Results are returned and displayed using Tables plugin. See Section 9.1.2, “Tables Configuration” for more information.

9.1. Client-side Configuration

9.1.1. query.ini

Here are the options that can be set in client's query.ini:

persistentQueries: if true, queries will be persistent. If false, selection is lost after next page reload. Note that persistency will work only with layers with id_attribute_string set (see Section 9.3, “Related Elements in Mapfile”)
displayExtendedSelection: if true, shows form for selection extended functions. This form is mainly used by developers (see TODO: link to developer's doc)
queryLayers: the comma separated list of layers which will appear in the extended selection form. If this list is absent, all msLayers appear in the form.
returnAttributesActive: if true, the layers attributes can be requested. If false, only object IDs will be returned (default: false)
defaultPolicy: can be either POLICY_XOR, POLICY_UNION, POLICY_INTERSECTION or POLICY_REPLACE. Defines how new selected objects are mixed with previous ones (default: POLICY_XOR)
defaultMaskmode: if true, selected objects are highlighted in mask mode (default: false). See also Section 9.3.3.2, “Mask Mode”
defaultHilight: if true, objects are highlited (default: true)
defaultAttributes: if true, the layers attributes are returned (default: true)
defaultTable: if true, the results table is displayed (default: true)
weightQueryByPoint: integer which defines display order of the query by point tool icon in toolbar (default: 40). Negative weighted tools are disabled
weightQueryByBbox: see weightQueryByPoint (default: 41).
weightQueryByPolygon: see weightQueryByPoint (default: 42).
weightQueryByCircle: see weightQueryByPoint (default: 43).

9.1.2. Tables Configuration

Tables plugin can be used by any plugin to manage, transfer and display tables structure. In basic CartoWeb installation, only Query plugin uses this functionality.

To configure table appearance, use tables client-side rules described in Developer's Documentation (Section 2.4.3, “Tables”).

9.2. Server-side Configuration

9.2.1. query.ini

Here are the options that can be set in server's query.ini:

drawQueryUsingHilight: if true, query hilighting will use Hilight plugin. In this case, Hilight plugin must be loaded on server. If false, objects will be hilighed using MapServer query functionality. See also Section 9.3.3, “Hilight Configuration” (default: false)
noRowId: if true, row id will not be included in the table. In this case the row id will not be displayed in the output table (html, pdf, etc.). (default: false)

9.2.2. MapServer Query Configuration

MapQuery plugin can be used by any plugin to retrieve objects information from MapServer.

Following options can be set in server's mapquery.ini:

maxResults: Maximum number of results to handle in the query plugin. This limit is to avoid high load on the server. It should be the client responsibility not to ask too many objects to avoid reaching this limit. Ignoring big queries can be done with the ignoreQueryThreshold parameter, which give a better behaviour for the user
ignoreQueryThreshold: Do not take into account the elements selected by a shape (rectangle, polygon) in a query, if this shape intersects more than ignoreQueryThreshold objects. It should be less than maxResults to have informative messages to the user

9.3. Related Elements in Mapfile

9.3.1. Making a Layer Queriable

To make a MapServer layer queriable, one have to add a TEMPLATE parameter in the mapfile layer definition. In our case, any value fits. For instance:

LAYER
  NAME "foobar"
  ...
  TEMPLATE "ttt"
  ...
END

9.3.2. Meta Data

Here are the meta data that can be set to mapfile's layers:

"id_attribute_string" "name|type": describes the attribute used for the id, and the type of the id. Type can be either "int" or "string". Caution: case sensitive
"query_returned_attributes" "attribute1 attribute2": the names (space separated) of the fields returned by a query. If not set, all fields are returned. Caution: case sensitive
"hilight_use_logical_expressions" "true"/"false": Set this to true if you are using a layer for hilight (using the convention yourlayer_hilight) and you want to preserve your expressions in the hilight layer for hilighted objects. IMPORTANT: you need to set this metadata on the hilight layer, not the original one.

Example:

METADATA
  "id_attribute_string" "FID|string"
  "query_returned_attributes" "FID FNAME"
END

9.3.3. Hilight Configuration

Hilight plugin can be used by any plugin to hilight objects on the map. In basic CartoWeb installation, only Query plugin uses this functionality. As Hilight plugin is not a core plugin, it must be loaded in order to use it with queries.

9.3.3.1. Normal Mode

Hilight on a specific layer can be generated by several means: special layer activation, special class activation, dynamic layer/class generation. Decision is made in the following order:

looks for a layer named "<layer_name>_hilight"
if not found, looks for a class named "hilight" in the current layer
if not found, dynamically creates a layer if meta data "hilight_createlayer" is set to "true"
if meta data "hilight_createlayer" is not set or set to "false", dynamically creates a class

Here are the meta data that can be set to mapfile's layers:

"hilight_color" "0-255 0-255 0-255": the hilight color of a dynamically generated class
"hilight_createlayer" "true": if true, a new layer will be dynamically generated for the hilight
"hilight_transparency" "1-100": the transparency, for dynamically generated layers

Examples:

Hilight using "<layer_name>_hilight" layer

LAYER
  NAME "foo"
  ...
END

LAYER
  NAME "foo_hilight"
  ...
END

Hilight using class "hilight"

LAYER
  NAME "foo"
  ...
  CLASS
    EXPRESSION /_always_false_/
    NAME "hilight"
    STYLE
      ...
    END
  END
  # other layer classes
  CLASS
    ...
  END
END

Hilight using dynamically generated layer

LAYER
  NAME "foo"
  ...
  METADATA
    "hilight_createlayer" "true"
    "hilight_color" "255 255 0"
    "hilight_transparency" "50"
  END
END

9.3.3.2. Mask Mode

When mask mode is requested, decision is made in the following order:

looks for a layer named "<layer_name>_mask"
if not found, dynamically creates a mask layer by copying current layer

Masking process also tries to find a layer which would hide the area outside all possible selections:

tries to activate a layer with name set in meta data "outside_mask"
if meta data "outside_mask" is not set, looks for a layer named "default_outside_mask"
if not found, no outside mask will be displayed

Here are the meta data that can be set to mapfile's layers:

"mask_color" "0-255 0-255 0-255": color of the mask when mask layer (<layer_name>_mask) is not defined
"mask_transparency" "true": transparency of the mask when mask layer (<layer_name>_mask) is not defined
"outside_mask" "layer_name": name of layer which will mask the outside (aka "complement"). If not set, will try to find a layer named "default_outside_mask"

Examples:

Mask using "<layer_name>_mask" layer

LAYER
  NAME "foo"
  ...
END

LAYER
  NAME "foo_mask"
  ...
END

Mask using "<layer_name>_mask" layer and an outside mask

LAYER
  NAME "foo"
  METADATA
    "outside_mask" "bar"
  END
  ...
END

LAYER
  NAME "foo_mask"
  ...
END

LAYER
  NAME "bar"
  ...
END

Mask using dynamically generated layer and default outside mask

LAYER
  NAME "foo"
  METADATA
    "mask_color" "255 255 255"
    "mask_transparency" "60"
  END
  ...
END

LAYER
  NAME "default_outside_mask"
  ...
END