ECQL Reference¶

This section provides a reference for the syntax of the ECQL language. The full language grammar is documented in the GeoTools ECQL BNF definition

Syntax Notes¶

The sections below describe the major language constructs. Each construct lists all syntax options for it. Each option is defined as a sequence of other constructs, or recursively in terms of itself.

Symbols which are part of the ECQL language are shown in code font. All other symbols are part of the grammar description.
ECQL keywords are not case-sensitive.
A vertical bar symbol ‘|’ indicates that a choice of keyword can be made.
Brackets ‘[ … ]’ delimit syntax that is optional.
Braces ‘{ … }’ delimit syntax that may be present zero or more times.

Condition¶

A filter condition is a single predicate, or a logical combination of other conditions.

Syntax	Description
Predicate	Single predicate expression
Condition `AND` \| `OR` Condition	Conjunction or disjunction of conditions
`NOT` Condition	Negation of a condition
`(` \| `[` Condition `]` \| `)`	Bracketing with `(` or `[` controls evaluation order

Predicate¶

Predicates are boolean-valued expressions which specify relationships between values.

Syntax	Description
Expression `=` \| `<>` \| `<` \| `<=` \| `>` \| `>=` Expression	Comparison operations
Expression [ `NOT` ] `BETWEEN` Expression `AND` Expression	Tests whether a value lies in or outside a range (inclusive)
Expression [ `NOT` ] `LIKE` \| `ILIKE` like-pattern	Simple pattern matching. like-pattern uses the `%` character as a wild-card for any number of characters. `ILIKE` does case-insensitive matching.
Attribute [ `NOT` ] `IN (` Expression { `,`Expression } `)`	Tests whether an attribute value is (not) in a set of values.
[ `NOT` ] `IN (` Literal { `,`Literal } `)`	Tests whether a feature ID value is (not) in a given set. ID values are integers or string literals
Expression `IS` [ `NOT` ] `NULL`	Tests whether a value is (non-)null
Attribute `EXISTS` \| `DOES-NOT-EXIST`	Tests whether a featuretype does (not) have a given attribute
`INCLUDE` \| `EXCLUDE`	Always include (exclude) features to which this filter is applied

Temporal Predicate¶

Temporal predicates specify the relationship of a time-valued expression to a time or time period.

Syntax	Description
Expression `BEFORE` Time	Tests whether a time value is before a point in time
Expression `BEFORE OR DURING` Time Period	Tests whether a time value is before or during a time period
Expression `DURING` Time Period	Tests whether a time value is during a time period
Expression `DURING OR AFTER` Time Period	Tests whether a time value is during or after a time period
Expression `AFTER` Time	Tests whether a time value is after a point in time

Spatial Predicate¶

Spatial predicates specify the relationship between geometric values. Topological spatial predicates (INTERSECTS, DISJOINT, CONTAINS, WITHIN, TOUCHES CROSSES, OVERLAPS and RELATE) are defined in terms of the DE-9IM model described in the OGC Simple Features for SQL specification.

Syntax	Description
`INTERSECTS(`Expression `,` Expression `)`	Tests whether two geometries intersect. The converse of `DISJOINT`
`DISJOINT(`Expression `,` Expression `)`	Tests whether two geometries are disjoint. The converse of `INTERSECTS`
`CONTAINS(`Expression `,` Expression `)`	Tests whether the first geometry topologically contains the second. The converse of `WITHIN`
`WITHIN(`Expression `,` Expression `)`	Tests whether the first geometry is topologically within the second. The converse of `CONTAINS`
`TOUCHES(`Expression `,` Expression `)`	Tests whether two geometries touch. Geometries touch if they have at least one point in common, but their interiors do not intersect.
`CROSSES(`Expression `,` Expression `)`	Tests whether two geometries cross. Geometries cross if they have some but not all interior points in common
`OVERLAPS(`Expression `,` Expression `)`	Tests whether two geometries overlap. Geometries overlap if they have the same dimension, have at least one point each not shared by the other, and the intersection of the interiors of the two geometries has the same dimension as the geometries themselves
`EQUALS(`Expression `,` Expression `)`	Tests whether two geometries are topologically equal
`RELATE(` Expression `,` Expression `,` pattern `)`	Tests whether geometries have the spatial relationship specified by a DE-9IM matrix pattern. A DE-9IM pattern is a string of length 9 specified using the characters `TF012`. Example: `'1T*T'`
`DWITHIN(` Expression `,` Expression `,` distance `,` units `)`	Tests whether the distance between two geometries is no more than the specified distance. distance is an unsigned numeric value for the distance tolerance. units is one of `feet`, `meters`, `statute miles`, `nautical miles`, `kilometers`
`BEYOND(` Expression `,` Expression `,` distance `,` units `)`	Similar to `DWITHIN`, but tests whether the distance between two geometries is greater than the given distance.
`BBOX (` Expression `,` Number `,` Number `,` Number `,` Number [ `,` CRS ] `)`	Tests whether a geometry intersects a bounding box specified by its minimum and maximum X and Y values. The optional CRS is a string containing an SRS code (For example, `'EPSG:1234'`. The default is to use the CRS of the queried layer)

Expression¶

An expression specifies a attribute, literal, or computed value. The type of the value is determined by the nature of the expression. The standard PEMDAS order of evaluation is used.

Syntax	Description
Attribute	Name of a feature attribute
Literal	Literal value
Expression `+` \| `-` \| `*` \| `/` Expression	Arithmetic operations
function `(` [ Expression { `,` Expression } ] `)`	Value computed by evaluation of a filter function with zero or more arguments.
`(` \| `[` Expression `]` \| `)`	Bracketing with `(` or `[` controls evaluation order

Attribute¶

An attribute name denotes the value of a feature attribute.

Simple attribute names are sequences of letters and numbers, e.g. States123
Attribute names quoted with double-quotes may be any sequence of characters, e.g. “States!@#”
Note: id is one of a few reserved keywords in ECQL and thus an attribute (or database column) named id must be quoted, e.g. “id”

Literal¶

Literals specify constant values of various types.

Type	Description
Number	Integer or floating-point number. Scientific notation is supported.
Boolean	`TRUE` or `FALSE`
String	String literal delimited by single quotes. To include a single quote in the string use two single-quotes: `''`
Geometry	Geometry in WKT or EWKT format. WKT is defined in the OGC Simple Features for SQL specification. All standard geometry types are supported: `POINT`, `LINESTRING`, `POLYGON`, `MULTIPOINT`, `MULTILINESTRING`, `MULTIPOLYGON`, `GEOMETRYCOLLECTION`. EWKT allows specifying a geometry spatial reference system by prefixing it with a numerical code, in the form `SRID=number;WKT`, for example, `SRID=4326;POINT (1 2)`. A custom type of Envelope is also supported with syntax `ENVELOPE (` x1 x2 y1 y2 `)`.
Time	A UTC date/time value in the format `yyyy-mm-hhThh:mm:ss`. The seconds value may have a decimal fraction. The time zone may be specified as `Z` or `+/-hh:mm`. Example: `2006-11-30T00:30:00Z`
Duration	A time duration specified as `P` [ y `Y` m `M` d `D` ] `T` [ h `H` m `M` s `S` ]. The duration can be specified to any desired precision by including only the required year, month, day, hour, minute and second components. Examples: `P1Y2M`, `P4Y2M20D`, `P4Y2M1DT20H3M36S`

Time Period¶

Specifies a period of time, in several different formats.

Syntax	Description
Time `/` Time	Period specified by a start and end time
Duration `/` Time	Period specified by a duration before a given time
Time `/` Duration	Period specified by a duration after a given time

Previous: Filter Encoding Reference

Next: Filter functions