cqlalchemy 0.0.9

library for constructing cql2-json queries and for generating libraries with multiple STAC extensions"

cqlalchemy

Library to help make CQL2-json queries a little easier!

STAC is a terrific specification for cataloging temporal/spatial data with an emphasis on providing queryable fields for searching that data. One of the ways to make complex queries is to use cql2-json.

This project provides two different functionalities. One is the cqlalchemy.stac.query module which provides query construction class (QueryBuilder) with the most popular extensions (eo, sar, sat, view, mlm).

The other functionality is a script that allows the user to build their own QueryBuilder class from extensions of their choosing, and allowing the opportunity to restrict the fields that can be queried (in the case where it isn't a required field and it's existence in the class might mislead the user).

cqlbuild

The cqlbuild is an interactive cli that allows for creating your own STAC cql2 query class.

Interactive cqlbuild

Add various STAC extensions to the builder. Leave blank to complete adding extensions and move to next step.

Add extension schema by extension name

In some cases the extension schema can be guessed from an extension name. In the below example we use the view extension name:

 % cqlbuild --interactive
Enter extensions, either the path to a local file, a url or the extension json-ld name (sar, sat, etc):
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls : view
treating input view like extension json-ld code and querying https://raw.githubusercontent.com/stac-extensions/view/refs/heads/main/json-schema/schema.json
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls :

Add extension schema with local schema file

 % cqlbuild --interactive
Enter extensions, either the path to a local file, a url or the extension json-ld name (sar, sat, etc):
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls : ./tests/test_data/mlm.schema.json
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls :

Add extension schema by raw schema endpoint

 % cqlbuild --interactive
Enter extensions, either the path to a local file, a url or the extension json-ld name (sar, sat, etc):
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls : https://stac-extensions.github.io/projection/v2.0.0/schema.json
STAC extension, raw schema url, local json extension schema file, local list of extensions or urls :

Omitting fields from the query class interface

Omit fields from the query class interface by adding a field to ignore or a file with a list of fields to ignore.

Enter stac fields to omit from api or a path with a list of fields to omit:
Field to ignore : eo:snow_cover
Field to ignore : created
Field to ignore :

To prevent fields from being queryable through the generated STAC query interface.

cqlbuild from definition file

Below is an example of a definition file for defining what extensions to use and what fields to ignore:

{
  "extensions": [
    "sat",
    "sar",
    "eo",
    "view",
    "landsat",
    "./tests/test_data/mlm.schema.json",
    "https://stac-extensions.github.io/projection/v2.0.0/schema.json"
  ],
  "stac_fields_to_ignore": [
    "view:sun_azimuth",
    "view:sun_elevation",
    "constellation"
  ]
}

It can be used in the cli as follows:

% cqlbuild --definition ./tests/test_data/sample_definition.json --output ./tests/test_data/fixed_up_class.py