Introduction

CQL stands for Common Query Language, I believe it originated with the library of congress, it:

The OGC then extended it for spatial queries, specifying it in their Catalog 2.0 spec. The full BNF syntax is also detailed at: [GEOTOOLS:CQL Parser Design].

At GeoServer we've ported it to also be used in WFS and WMS, as it's a nice intuitive and powerful way of specifying how to filter data. It can be included in any WMS request, and will only display the features that match the CQL filter. Or in a WFS request it can replace the normal Filter (which is normal a bunch of XML) to tell which raw data to fetch.

This tutorial will walk through several examples of to use CQL, and hopefully raise it's profile a bit. We've had it available in GeoServer since version 1.5.0-RC1.

Queries

TODO

point in random road

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=roads&CQL_FILTER=INTERSECT(gen_full,%20POINT%20(-89.397024%2031.065245))

point in washington square park:

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=poly_landmarks&CQL_FILTER=INTERSECT(the_geom,POINT(-73.99738%2040.73109))

Streets that cross a line near my office.

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=roads&CQL_FILTER=INTERSECT(gen_full,LINESTRING(-74.00747%2040.73971,-74.00775%2040.73454))

populations over 8 million

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=gnis_pop&CQL_FILTER=population%3E8000000

landmarks in a bbox near my apartment

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=poly_landmarks&CQL_FILTER=BBOX(the_geom,-73.99051,40.4039,-73.96132,40.67060)

This seems to be a well formed filter, it shows up fine in GeoServer, but it's getting the same complaint as when we don't have the name right:

http://sigma.openplans.org:8080/geoserver/wfs?service=WFS&request=GetFeature&typename=poly_landmarks&CQL_FILTER=cfcc+=+'D85'+AND+NOT+DISJOINT(the_geom,LINESTRING(-73.99051%2040.4039,-73.96132%2040.67060))

Errors

Unfortunately error reporting is quite poor right now. I've opened a bug for this: http://jira.codehaus.org/browse/GEOS-1062 Basically if you get a 'transformer error' it's likely that you've used an attribute name that is not in the feature type you requested. Check the spelling, and the DescribeFeatureType response to make sure it's there. If you turn verbose exceptions on you can look at the cause of the transformer error, and if it's a class cast exception in the PostPreProcessFilterSplittingVisitor then it's almost definitely because you specified an attribute that isn't there.