ogc-cql2

Rust implementation of the Open Geospatial Consortium (OGC) Common Query Language (CQL2) described here.

This library aims to fulfill all the requirements listed under Conformance section of the specs.

So far, users of this library will be able to:

• Parse CQL2 Expressions in either Text- or JSON-encoded forms,
• Implement Evaluators to process collections of Resources (a.k.a features) against valid expressions.
• Make use of a comprehensive set of builtin Functions to use in writing their expressions.
• Implement their own versions of Functions and register them w/ Evaluators.

Changes are tracked in ChangeLog.

Parsing Expression Grammar (PEG) + Typify

The text-encoded parser used in this project was generated by rust-peg by manually translating the source into input recognizable by that crate's peg::parser! macro. The reference BNF document is included in the doc folder.

The JSON-encoded one started life from code generated by the cargo-typify tool from the JSON Schema given in the Standard. However some limitations w/ that tool meant that manual intervention was required.

The modified JSON Schema input file is included w/ the source of this crate (cql2.json) as well as a patch file (cql2.json.patch) showing the changes from the original copy.

Change to the BNF Grammar

The BNF grammar specified in the specs limit the WKT representation of multi-point geometries to always enclose point coordinates w/in parenthesis as implied from the following rules...

multipointTaggedText = "MULTIPOINT" ["Z"] multiPointText;
multiPointText = "(" pointText {"," pointText} ")";
pointText = "(" point ")";
point = xCoord yCoord [zCoord];

That meant that text like MULTIPOINT(1 2, 3 4) causes a syntax error forcing the user to write it instead as MULTIPOINT((1 2), (3 4)).

This implementation allows for both forms.

Deviation from the Stadard

The CQL2 specs state that Dates should be considered as local with regard to time zones. This implementation however always assign them the UTC TZ.

Conformance tests

The tests folder contains tests that implement most of the Annex A: Abstract Test Suite (Normative) conformance tests, grouped in folders mirroring the level-1 sections of the specs.

Test data

The folder tests/samples/csv contain 3 CSV files created/converted from the same named Layers in the GeoPackage referenced in the Standard.

Those CSV files were first created by exporting each Layer to a CSV file using DB Browser for SQLite Version 3.13.1, then converting the geometries to their WKT form and renaming their column geom.

The other 2 folders next to csv in the same parent folder mirror the same data found here.

Tests not implemented yet

Some tests, which test filter expressions with AND, OR, and NOT including sub-expressions of 4 predicates are not implemented yet. Those are:

• A.6.6. Conformance Test 24: /conf/accent-insensitive-comparison/logical,
• A.7.3. Conformance Test 27: /conf/basic-spatial-functions/logical,
• A.9.10. Conformance Test 39: /conf/spatial-functions/logical,
• A.10.4. Conformance Test 43: /conf/temporal-functions/logical,
• A.11.2. Conformance Test 45: /conf/array-functions/logical,
• A.12.5. Conformance Test 50: /conf/property-property/logical,
• A.14.3. Conformance Test 54: /conf/arithmetic/logical,

Test result pending request for clarification

The issue here is at the time of this writing still unresolved.

For now, the relevant test (a6/test_23.rs) expected results have been amended according to the findings reported in the issue in question.

How to configure this library

1. Make a copy of the file .env.template and rename it .env.
2. Make sure .env is included in .gitignore.
3. Edit the contents of .env to suit your requirements and environment.

For now these are the environment variables that can be configured:

DEFAULT_CRS

Coordinate Reference System (CRS) code to use when validating geometry coordinates. Defaults to EPSG:4326 if/when undefined.

DEFAULT_PRECISION

Precision (number of digits after the decimal point) to keep/use when processing coordinates. Defaults to 6 if/when undefined. For WGS 84 coordinates this translates to approx. 11.1 cm. accuracy when projecting them to Web Mercator.

For now only positive integers in the range 0..7 inclusive are allowed.

RUST_LOG

See https://docs.rs/env_logger/latest/env_logger/#enabling-logging for details.

TODO

In no particular order...

• Implement missing conformance tests preferably after finding an external set of Test Vectors.
• Add more Functions.
• Implement pooling of Evaluators à la DB connections pools.
• Refine the Evaluator trait as the external interface to this library.
• Investigate ways of translating Expressions to PostGIS clauses + views.
• Improve the way we handle user defined closures.
• Reduce allocation.
• Improve performance.
• Reduce code repetition by using more macros.
• Investigate alternative means for external clients to inject functions logic + metadata.
• The WKT parsing machinery entry-point is private. Make it public. Done 2025-08-31.
• Properly manage + handle global configurable options such as default CRS bearing in mind how it may affect conformance tests. Done 2025-09-02.
• Add an LRU to store commonly used CRSes.

License

This product is licensed under the Apache License Version 2.0 —see included copy or online