Skip to content

Commit b9b7c83

Browse files
philvarnerphilvarner
committed
add a getting started section
1 parent 9acf92d commit b9b7c83

File tree

1 file changed

+35
-24
lines changed

1 file changed

+35
-24
lines changed

‎fragments/filter/README.md

Lines changed: 35 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
- [Limitations of Item Search](#limitations-of-item-search)
2222
- [Filter expressiveness](#filter-expressiveness)
2323
- [Conformance Classes](#conformance-classes)
24-
- [Grammar and schemas](#grammar-and-schemas)
24+
- [Getting Started with Implementation](#getting-started-with-implementation)
2525
- [Queryables](#queryables)
2626
- [GET Query Parameters and POST JSON fields](#get-query-parameters-and-post-json-fields)
2727
- [Interaction with Endpoints](#interaction-with-endpoints)
@@ -47,25 +47,22 @@
4747
- [Example 6: Spatial](#example-6-spatial)
4848
- [Example 6: INTERSECTS cql-text (GET)](#example-6-intersects-cql-text-get)
4949
- [Example 6: INTERSECTS cql-json (POST)](#example-6-intersects-cql-json-post)
50-
- [Implementations](#implementations)
5150

5251
## Overview
5352

5453
The Filter extension provides an expressive mechanism for searching based on Item attributes.
5554

56-
This extension uses several conformance classes defined in the
55+
This extension references behavior defined in the
5756
[OGC API - Features - Part 3: Filtering and the Common Query Language (CQL)](https://portal.ogc.org/files/96288)
5857
specification. As of May 2020, this specification is in draft status. The only anticipated change before final is to the
5958
division of behavior among conformance classes, as described further
60-
in [OAFeat Part 3 Conformance Classes](#oafeat-part-3-conformance-classes).
59+
in the [Conformance Classes](#conformance-classes) section.
6160

6261
OAFeat Part 3 CQL formally defines syntax for both a text format (cql-text) as an ABNF grammar (largely similar to the BNF grammar
63-
in the General Model) and a JSON format (cql-json) as an OpenAPI schema, and provides a precise natural language description of
64-
the declarative semantics.
65-
The CQL Text format has long-standing use within
62+
in the General Model) and a JSON format (cql-json) as a JSON Schema and OpenAPI schema, and provides a precise natural
63+
language description of the declarative semantics. The CQL Text format has long-standing use within
6664
geospatial software (e.g., GeoServer), is expected not to change before final.
67-
OGC CQL Text has been previously described
68-
in [OGC Filter Encoding](https://www.ogc.org/standards/filter) and
65+
OGC CQL Text has been previously described in [OGC Filter Encoding](https://www.ogc.org/standards/filter) and
6966
[OGC Catalogue Services 3.0 - General Model](http://docs.opengeospatial.org/is/12-168r6/12-168r6.html#62)
7067
(including a BNF grammar in Annex B). The CQL JSON format is newly-defined, but also not
7168
expected to change before final.
@@ -114,8 +111,9 @@ predicates.
114111
## Conformance Classes
115112

116113
OAFeat CQL defines several conformance classes that allow implementers to create compositions of
117-
functionality that support whatever expressiveness they need. Implementers many choose not to incur the cost of
118-
implementing functionality they do not need, or may not be able to implement functionality that is not supported by
114+
functionality that support whatever expressiveness they need. This allows implementers to incrementally support CQL
115+
syntax, without needing to implement a huge spec all at once. Some implementers choose not to incur the cost of
116+
implementing functionality they do not need or may not be able to implement functionality that is not supported by
119117
their underlying datastore, e.g., Elasticsearch does not support the spatial predicates required by the
120118
Enhanced Spatial Operators conformance class.
121119

@@ -168,7 +166,20 @@ will support arbitrary uses of properties and literals in expressions on either
168166
implementations that use datastores that do not easily support right-hand side properties to implement Simple CQL
169167
(e.g., Elasticsearch). Implementers should feel free to only implement `property operand literal` expressions at this time.
170168

171-
## Grammar and schemas
169+
## Getting Started with Implementation
170+
171+
It recommended that implementers start with fully implementing only a subset of functionality. As stated previously,
172+
until the OAFeat CQL spec is finalized, it is legal in a STAC API implementation to advertise that the Simple CQL conformance
173+
class is implemented, but that only a subset of that functionality is implemented.
174+
175+
A good place to start is
176+
implementing only the logical and simple comparison operators (`=`, `<`, `<=`, `>`, `>=`), defining a static Queryables
177+
schema with no queryables advertised, and only implementing CQL Text. Following from that can be support for
178+
INTERSECTS and ANYINTERACTS, defining a static Queryables schema with only the basic Item properties, and also
179+
implementing CQL JSON. From there, other comparison operators can be implemented and a more
180+
dynamic Queryables schema (if desired).
181+
182+
Formal definitions and grammars for CQL can be found here:
172183

173184
- The [OAFeat (CQL) spec](https://portal.ogc.org/files/96288) includes an ABNF for cql-text and both JSON Schema and
174185
OpenAPI specifications for cql-json. The standalone files are:
@@ -179,6 +190,18 @@ implementations that use datastores that do not easily support right-hand side p
179190
- A OpenAPI specification for only the parts of the CQL JSON encoding required by this extension is [here](cql.yml)
180191
- xtraplatform-spatial has a CQL [ANTLR 4 grammer](https://github.com/interactive-instruments/xtraplatform-spatial/tree/master/xtraplatform-cql/src/main/antlr/de/ii/xtraplatform/cql/infra)
181192

193+
These projects have or are developing CQL support:
194+
195+
- [GeoPython PyCQL](https://github.com/geopython/pycql/tree/master/pycql), and the
196+
[Bitner fork](https://github.com/bitner/pycql) to be used in stac-fastapi
197+
- [Franklin](https://github.com/azavea/franklin) is working on it in [this PR](https://github.com/azavea/franklin/pull/750).
198+
- [Geotools](https://github.com/geotools/geotools) has support for [CQL text](https://github.com/geotools/geotools/tree/main/modules/library/cql/src/main/java/org/geotools/filter/text/cql2)
199+
200+
Note that the [xbib CQL library (JVM)](https://github.com/xbib/cql) is the OASIS Contextual Query Language, not
201+
OGC CQL, and should not be used to implement this extension, as they are significantly different query languages.
202+
[Stacatto](https://github.com/planetlabs/staccato) uses this for their query language implementation, but it is
203+
not compliant with this extension.
204+
182205
## Queryables
183206

184207
The Queryables mechanism allows a client to discover what variable terms are available for use when writing filter
@@ -761,15 +784,3 @@ GeoJSON geometries.
761784
},
762785
}
763786
```
764-
765-
## Implementations
766-
767-
- [GeoPython PyCQL](https://github.com/geopython/pycql/tree/master/pycql), and the
768-
[Bitner fork](https://github.com/bitner/pycql) to be used in stac-fastapi
769-
- [Franklin](https://github.com/azavea/franklin) is working on it in [this PR](https://github.com/azavea/franklin/pull/750).
770-
- [Geotools](https://github.com/geotools/geotools) has support for [CQL text](https://github.com/geotools/geotools/tree/main/modules/library/cql/src/main/java/org/geotools/filter/text/cql2)
771-
772-
Note that the [xbib CQL library (JVM)](https://github.com/xbib/cql) is the OASIS Contextual Query Language, not
773-
OGC CQL, and should not be used to implement this extension, as they are significantly different query languages.
774-
[Stacatto](https://github.com/planetlabs/staccato) uses this for their query language implementation, but it is
775-
not compliant with this extension.

0 commit comments

Comments
 (0)