Cross-layer filtering provides the ability to find features from layer A that have a certain relationship to features in layer B.
This can be used, for example, to find all bus stops within a given distance from a specified shop,
or to find all coffee shops contained in a specified city district.

The querylayer module adds filter functions that implement cross-layer filtering.
The functions work by querying a secondary layer within a filter being applied to a primary layer.
The name of the secondary layer and an attribute to extract from it are provided as arguments,
along with an ECQL filter expression to determine which features are of interest.
A common use case is to extract a geometry-valued attribute, and then use the
value(s) in a spatial predicate against a geometry attribute in the primary layer.

Filter functions are widely supported in GeoServer, so cross-layer filtering can be used in SLD rules and WMS and WFS requests, in either XML or CQL filters.

The extension provides the following filter functions to support cross-layer filtering.

Name

Arguments

Description

querySingle

layer : String, attribute : String, filter : String

Queries the specified layer applying the specified ECQLfilter and returns the value of attribute from the first feature in the result set.
The layer name must be qualified (e.g. topp:states).
If no filtering is desired use the filter INCLUDE.

queryCollection

layer : String, attribute : String, filter : String

Queries the specified layer applying the specified ECQLfilter and returns a list containing the value of attribute for every feature in the result set.
The layer name must be qualified (e.g. topp:states).
If no filtering is desired use the filter INCLUDE.
An exception is thrown if too many results are collected (see Memory Limits).

collectGeometries

geometries: a list of Geometry objects

Converts a list of geometries into a single Geometry object.
The output of queryCollection must be converted by this function in order to use it in spatial filter expressions (since geometry lists cannot be used directly).
An exception is thrown if too many coordinates are collected (see Memory Limits).

In the GeoServer 2.1.x series, in order to have cross-layer filters execute with optimal performance it is necessary to specify the
following system variable when starting the JVM:

-Dorg.geotools.filter.function.simplify=true

This ensures the functions are evaluated once per query, instead of once per result feature.
This flag is not necessary for the GeoServer 2.2.x series.
(Hopefully this behavior will become the default in 2.1.x as well.)

The queryCollection and collectGeometries functions do not perform a true database-style join.
Instead they execute a query against the secondary layer every time they are executed, and load the entire result into memory.
The functions thus risk using excessive server memory if the query result set is very large,
or if the collected geometries are very large.
To prevent impacting server stability there are built-in limits to how much data can be processed:

at most 1000 features are collected by queryCollection

at most 37000 coordinates (1MB worth of Coordinate objects) are collected by collectGeometries

These limits can be overridden by setting alternate values for the following parameters (this can be done using JVM system variables, servlet context variables, or enviroment variables):

QUERY_LAYER_MAX_FEATURES controls the maximum number of features collected by queryCollection

GEOMETRY_COLLECT_MAX_COORDINATES controls the maximum number of coordinates collected by collectGeometries