The features returned by
items queries can be filtered using
filter query parameter with an expression written using
the Common Query Language (CQL).
CQL expressions return a value of
Only features which evaluate to
true are returned.
The filter expression is evaluated by the database, which will take advantage of indexes (attribute and spatial) to make filter evaluation very efficient.
This section describes the CQL query language subset supported. Note that some special characters may need to be URL-encoded in some clients.
Property and Literal Values
The basic elements of filter expressions are values obtained from feature collection properties, and literals (constants).
Properties are referred to by name. Property names can be quoted, to support including special characters.
Literals can be numbers, boolean or text values. To include single quotes in text values use repeated single quotes.
1.234 true 'a text value' 'it''s easy'
Values of numeric expressions can be computed using the
with parentheses to specify operator precedence.
+ needs to be URL-encoded as
x + 3 2 * (y - 3) p % 10
Values can be compared using conditional operators:
a = b a <> b a > b a >= b a < b a <= b
pop_est >= 1000000 name = 'Finland' count % 10 = 1
BETWEEN predicate tests if a value (a property, literal or expression) lies
in the range defined by a start and end value (inclusive):
e1 [NOT] BETWEEN e2 AND e3
pop_est BETWEEN 1000000 AND 9000000 name NOT BETWEEN 'Chile' AND 'Denmark'
IN predicate tests if a value lies in a list of constant values.
property [NOT] IN ( val1, val2, ... )
id IN (1,2,3) name IN ('Chile', 'Kenya', 'Denmark')
LIKE predicate tests if a text value matches a pattern.
% is a wildcard.
(Note that this may need to be URL-encoded as
ILIKE can be used for case-independent matching.
property [NOT] LIKE | ILIKE pattern
name LIKE 'Ch%' continent ILIKE '%america'
IS NULL predicate
IS NULL predicate tests if a property value is (or is not) null.
property IS [NOT] NULL
name IS NULL
Comparisons and predicates can be combined with the
Operators are evaluated in the order NOT, AND, OR.
Evaluation order can be controlled by enclosing
subexpressions in parentheses.
(continent = 'Europe' OR continent = 'Africa') AND pop_est < 1000000
CQL supports spatial filtering by providing geometry literals and spatial predicates.
Geometry literals use Well-Known Text (WKT) to describe values for points, lines, polygons (with holes), and collections.
POINT (1 2) LINESTRING (0 0, 1 1) POLYGON ((0 0, 0 9, 9 0, 0 0)) POLYGON ((0 0, 0 9, 9 0, 0 0),(1 1, 1 8, 8 1, 1 1)) MULTIPOINT ((0 0), (0 9)) MULTILINESTRING ((0 0, 1 1),(1 1, 2 2)) MULTIPOLYGON (((1 4, 4 1, 1 1, 1 4)), ((1 9, 4 9, 1 6, 1 9))) GEOMETRYCOLLECTION(POLYGON ((1 4, 4 1, 1 1, 1 4)), LINESTRING (3 3, 5 5), POINT (1 5))
CQL also provides a syntax for concisely representing a rectangular polygon by the X and Y ordinates at the lower-left and upper-right corners:
ENVELOPE (1, 2, 3, 4)
By default the coordinate system of geometry literal values is assumed to be geodetic (SRID = 4326).
filter-crs=SRID query parameter can be used to specify that the geometry literals in a filter expression are in a different coordinate system.
Spatial predicates allow filtering features via spatial conditions on the feature geometry. Spatial predicates are defined in the form of spatial functions. Predicates for spatial relationships include:
INTERSECTS- tests whether two geometries intersect
DISJOINT- tests whether two geometries have no points in common
CONTAINS- tests whether a geometry contains another
WITHIN- tests whether a geometry is within another
EQUALS- tests whether two geometries are topologically equal
CROSSES- tests whether the geometries cross
OVERLAPS- tests whether the geometries overlap
TOUCHES- tests whether the geometries touch
Typically a spatial predicate is used to test the relationship between the spatial column of the queried collection and a geometry literal value.
INTERSECTS(geom, ENVELOPE(-100, 49, -90, 50) ) CONTAINS(geom, POINT(-100 49) )
DWITHIN predicate allows testing whether a geometry lies within a given distance of another. The distance is in the units of the dataset’s coordinate system
(degrees in the case of data stored in SRID=4326, or a length unit such as meters for non-geodetic data).
DWITHIN(geom, POINT(-100 49), 0.1)
Temporal filtering in CQL supports date-time literals and the ability to use them in conditions against temporal-valued properties (table columns with type date or timestamp).
Date-time literals specifiy a date, or a timestamp including a date and time (with optional seconds value):
2001-01-01 2001-01-01T10:23 2001-01-01T10:23:45
Temporal values can be compared using the conditional operators
t > 2001-01-01T00:00 AND t <= 2002-12-31T11:59:59
They can also be used in the
The values used can be properties or literals:
t BETWEEN 2001-01-01 AND 2001-12-31 2001-01-01 BETWEEN time1 AND time2