If you look through the CQL and ECQL page in GeoServer’s documentation, there are several examples but they don’t cover everything you can do with CQL. Basically, a CQL filter is a list of phrases similar to where clauses in SQL, separated by the combiner words AND or OR. You can use the following operators in a CQL phrase:

• Comparison operations: =, <, >, and combinations
• Math expressions: +, -, *, /
• NOT
• IS, EXISTS
• BETWEEN, BEFORE, AFTER
• IN
• LIKE
• Geometric operators: CONTAINS, BBOX, DWITHIN, CROSS(ES), INTERSECT(S)

Some of these operations have examples in the GeoServer documentation, and others can be inferred from the GeoTools documentation (the stuff in their CQL.toFilter() calls). CQL can also call any of GeoServer’s filter functions.You can add parenthesis as needed to affect the order the filters are evaluated in, just like in SQL.

CQL has a lot of power for such a short spec, but it has a one very large deficiency that requires some database designing to avoid: the utter lack of join support. This makes sense when you consider that GeoServer doesn’t know about joins either. Ultimately, you’re using CQL against the GeoServer layer, not the underlying database structure. Building views or adding reference columns to the table GeoServer is accessing can help get around this.

In PhillyTreeMap.org, we use 4 types of CQL filters: id lookups using =, null checks using IS, date and integer ranges using BETWEEN and text searches using LIKE. Here are examples of those uses along with some array joining to get a valid CQL filter string at the end:

filter_list = []
filter_list.append("species_id = 212")
filter_list.append("height IS NULL")
filter_list.append("dbh BETWEEN 10 and 20")
filter_list.append("neighborhood_id_list LIKE '%42%' ")
cql = ' AND '.join(filter_list)
# should look like this: "species_id = 212 AND height IS NULL AND dbh BETWEEN 10 and 20 AND neighborhood_id_list LIKE '%42%' "


The above CQL filter would locate trees in a specific species, have no height value, only have dbh values between 10 and 20 inches and are in a particular neighborhood. The neighborhood_id_list filter would have been a join if this were written in standard SQL since neighborhoods and trees have a many-to-many relationship in our database. Since we can’t do joins, any time a tree is added or the location is updated, all of it’s related geographies’ ids are added to a reference column on the tree, and used specifically for this type of query.

CQL is passed to GeoServer in the same way as any other WMS variable. We’re using openlayers, so most of the WMS configuration variables are already set when we create the layer. The WMS layer has a little method called mergeNewParams that lets us change those parameters after the layer has been initialized. It also automatically redraws the layer, so the changes take place immediately. To add CQL to the WMS call, just add the CQL_FILTER variable to the layer’s parameters and the layer should update.

wms_layer.mergeNewParams({'CQL_FILTER': "species_id = 212 AND height IS NULL AND dbh BETWEEN 10 and 20 AND neighborhood_id_list LIKE '%42%' "});


You can remove any filters by deleting the parameter from the layer as if it was a normal javascript object. You’ll need to redraw the layer yourself before the change will be visible.

delete wms_layer.params.CQL_FILTER;
wms_layer.redraw();


Though it begs the question: who would win a WMS shootout: WMS, WMS, WMS, WMS, or WMS?

In the WMS specification, OGC defined an “optional” GetFeatureInfo request that returns feature information based on a pixel from a map.  It’s both useful and limiting that the request is based on the pixel — it’s useful in that you can just pass along the pixel that the user clicked on, but you don’t have a lot of control (without other trickery I won’t go into here).  But here’s the catch: the output format isn’t defined in the standard.  But here the problem becomes the opportunity — most WMS servers allow you can define your own output format, which includes JSON.

But again the problem returns to the fact that there isn’t a standard in place here:  different mapservers handle the output format definition differently.  MapServer has a very straightforward method — it will respond to a “text/html” request with three templates you can define: you can define a header template, a content template (that is repeated for each feature), and a footer template.  It will replace any attribute name surrounded with brackets with the value of the attribute.  So if you create a header.html file with a single left bracket (‘[') and a footer.html with a single right bracket (']‘) and then a template.html file that is something like:

{
id: “[id]“,
attribute: “[attribute]“
}

you’ll get responses to your GetFeatureInfo request in proper JSON, e.g.:

“[ { id: "123", attribute: "foo" }, { id: "456", attribute: "bar" } ]“

GeoServer has a different structure for its GetFeatureInfo templates, which is described here but the same basic approach works, with the major difference being that you create a single template with header and footer sections.  I’m not sure how it’s done with ArcGIS Server, but with ArcIMS there are XSL files for each output format, and you could create one that generates JSON without too much trouble if you are familiar with XSL.  If someone figures out how to do this with ArcGIS Server, I’ve love to know.

Of course, what would really be fantastic would be if the OGC standard was extended to include a standard output format — I won’t even dare to dream for a standard way to define the output format.