Filter

specdraftimplcandidate

Filter features with CQL2 expressions.

Scope

This building block provides query parameters to filter features using CQL2 (in Text or JSON encoding).

In addition to the standard functions specified in CQL2, the following custom functions are supported, too:

• UPPER(String): String returns the string in upper case.
• LOWER(String): String returns the string in lower case.
• NOW(): Timestamp returns the current time.
• DIAMETER2D(Geometry): Double returns the diameter of a geometry with 2D coordinates.
• DIAMETER3D(Geometry): Double returns the diameter of a geometry with 3D coordinates.

Limitations

Depending on the feature provider, some capabilities of CQL2 may not be supported. Specifically, in GeoPackage feature providers, queryables in a JSON column that are arrays are not supported. In PostgreSQL/PostGIS feature providers, the A_OVERLAPS operator is not supported for queryables in a JSON column.

The conformance classes Functions and Arithmetic Expressions are not supported.

The operator IN requires a property on the left side and literals on the right side.

Only booleanLiteral may be used from booleanExpression in a scalarExpression.

The Unicode characters "\x10000" to "\x10FFFF" are not supported.

Conformance Classes

This building block implements requirements of the conformance classes Filter and Features Filter from the draft specification OGC API - Features - Part 3: Common Query Language as well as the conformance classes Basic CQL2, Advanced Comparison Operators, Case-insensitive Comparisons, Accent-insensitive Comparisons, Basic Spatial Functions, Basic Spatial Functions with additional Spatial Literals, Spatial Functions, Temporal Functions, Array Functions, Property-Property Comparisons, CQL2 Text encoding, and CQL2 JSON encoding from the draft specification Common Query Language (CQL2. The implementation is subject to change in the course of the development and approval process of the draft.

The publication of queryables is controlled via Feature Collections - Queryables and is a prerequisite for clients to be able to determine the queryable feature properties.

Query Parameters

Name	Resources	Description
filter	Features, Vector Tile	The filter expression in the filter language declared in filter-lang. Coordinates are in the coordinate reference system declared in filter-crs.
filter-crs	Features, Vector Tile	Specifies which of the supported coordinate reference systems is used to encode coordinates in the filter expression in parameter filter. Default is WGS84 longitude/latitude (CRS84).
filter-lang	Features, Vector Tile	Language of the query expression in the filter parameter. Supported are cql2-text and cql2-json, specified in the OGC candidate standard Common Query Language (CQL2). cql2-text is an SQL-like text encoding for filter expressions that also supports spatial, temporal and array predicates. cql2-json is a JSON encoding of the same grammar, suitable for use as part of a JSON object that represents a query. The use of cql2-text is recommended for filter expressions in the filter parameter.

Configuration

Options

Name	Default	Description	Type	Since
buildingBlock		Always FILTER.	string	v2.0
enabled	false	Enable the building block?	boolean	v2.0

Examples

- buildingBlock: FILTER
  enabled: true