Developer’s Corner: Using Default ImageMosaic CQL filter in GeoServer

Dear All,
in this post we would like to describe how we did help our FAO colleagues with managing their huge ImageMosaics (containing multiple dimensions) by implementing an ImageMosaic improvement for GeoServer (2.2.x and 2.3.x) that allows to specify a default value for the Filter parameter it exposes.

Before proceeding it is worth to provide some background information on how to create an ImageMosaic with additional dimensions (a-la WMS). Here below you can find some videos that shows how to do that.

The ImageMosaic plugin gives you the possibility to configure a mosaic using an index that contains additional attributes which can be used to filter the granules to load at runtime using CQL filters via the CQL_FILTER GeoServer’s vendor option.
When you configure a mosaic using TIME and/or ELEVATION dimensions (see the Dimensions tab in GeoServer Layer configuration page) the GeoServer automatically uses the most recent time and the lowest available elevation  to limit the number of loaded granules with WMS requests that do not specify any value for those dimensions. This is not possible when the mosaic’s index uses an attribute that is not recognized as a dimension  (there is a pull request pending for this) hence in such case GeoServer will not use any default value for such attribute.
In our use case the ImageMosaic plugin is used with the Postgis datastore as backend for the indexing of granules: our granule set is composed by 400.000 raster files with an additional attribute (a String) representing a category that it is used from the outside via a CQL filter to select specific granules at runtime. We do have many granules covering the same geographical area at the same time, representing different categorie, in some cases up to 1024.
Pointing the browser to the layer preview page and clicking on the OpenLayers preview the undelrying ImageMosaic would collect all the granules matching the request filtering by BoundingBox and applying default values to the TIME and ELEVATION (where available) dimensions. Problem is that not applying any default to the additional index attribute that we set up (that is, the category for the granules we mentioned above) and having up to 1024 files per each time instant,  all the ~1024 images should be opened and stitched together to render the final image. This is of course undesirable as, on a side, it might take a long time to generate a small overview, while on the other side it might lead to the dreaded “Too many files open” error that would bring the server to its knees.
In order to avoid this problem and while we wait for the possibility to have additional dimensions merged it is highly recommended when we setup an ImageMosaic layer to add a default CQL filter which would act as a default filter and restrict the loaded granules  as shown below in the Filter textbox:

The behaviour we are trying to model here is as follows. The ImageMosaic plugin allows users to filter granules during WMS requests using either the standard WMS dimensions TIME and ELEVATION as well as via the GeoServer specific CQL_FILTER vendor option. However, we have defaults only for the standard dimensions and there is no such a thing for additional index attributes hence we can mimic this behavior by using the Filter textbox  specifying a default filtering condition. This filter will be overridden at runtime in case the incoming request contains a valid CQL_FILTER parameter.
Last but not least, the updated documentation can be found here:
The GeoSolutions team,