Merge pull request #235 from stac-utils/feature/add-filter-collections-params

add filter extension to collections endpoints

Author: vincentsarago

CHANGES.md

@@ -2,6 +2,9 @@
 
 ## Unreleased 
 
+* remove `cql-text` support for PgSTACSearch `filter`
+* add `filter` and `filter-lang` for CollectionIdParams dependency
+
 ## 1.9.0 (2025-09-23)
 
 * update titiler requirement to `>=0.24,<0.25`

pyproject.toml

@@ -29,6 +29,7 @@ classifiers = [
 dependencies = [
     "titiler.core>=0.24,<0.25",
     "titiler.mosaic>=0.24,<0.25",
+    "cql2>=0.3.6",
     "pydantic>=2.4,<3.0",
     "pydantic-settings~=2.0",
 ]

tests/fixtures/noaa-eri-nashville2020.json

@@ -1,8 +1,10 @@
 """Test titiler.pgstac Mosaic endpoints."""
 
 import io
+import json
 from unittest.mock import patch
 
+import pytest
 import rasterio
 from rasterio.crs import CRS
 
@@ -655,3 +657,26 @@ def test_collections_additional_parameters(app):
         {"field": "datetime", "direction": "asc"},
         {"field": "cloud", "direction": "asc"},
     ]
+
+
+@pytest.mark.parametrize(
+    "filter_expr,filter_lang",
+    [
+        (json.dumps({"op": "=", "args": [{"property": "value"}, "1"]}), "cql2-json"),
+        ("(value = '1')", "cql2-text"),
+    ],
+)
+def test_collections_cql_filter(filter_expr, filter_lang, app):
+    """Get assets for a specific collection and filter."""
+    response = app.get(
+        f"/collections/{collection_id}/point/-85.5,36.1624/assets",
+        params={
+            "filter": filter_expr,
+            "filter-lanq": filter_lang,
+        },
+    )
+    assert response.status_code == 200
+    resp = response.json()
+    assert len(resp) == 1
+    assert list(resp[0]) == ["id", "bbox", "assets", "collection"]
+    assert resp[0]["id"] == "20200307aC0853000w361030"

tests/test_collections.py

@@ -14,7 +14,7 @@
 @pytest.fixture
 def search_no_bbox(app):
     """Search Query without BBOX."""
-    query = {"collections": ["noaa-emergency-response"], "filter-lang": "cql-json"}
+    query = {"collections": ["noaa-emergency-response"]}
     response = app.post("/searches/register", json=query)
     assert response.status_code == 200
     resp = response.json()
@@ -34,7 +34,6 @@ def search_bbox(app):
     query = {
         "collections": ["noaa-emergency-response"],
         "bbox": [-85.535, 36.137, -85.465, 36.179],
-        "filter-lang": "cql-json",
     }
     response = app.post("/searches/register", json=query)
     assert response.status_code == 200
@@ -60,7 +59,7 @@ def test_info(app, search_no_bbox):
     search = resp["search"]
     assert search["search"] == {
         "collections": ["noaa-emergency-response"],
-        "filter-lang": "cql-json",
+        "filter-lang": "cql2-json",
     }
     assert search["metadata"] == {"type": "mosaic"}
 
@@ -1093,7 +1092,7 @@ def test_search_ids_parameter(app):
     query = {
         "collections": ["noaa-emergency-response"],
         "ids": ["20200307aC0853130w361030"],
-        "filter-lang": "cql-json",
+        "filter-lang": "cql2-json",
     }
     response = app.post("/searches/register", json=query)
     assert response.status_code == 200

tests/test_searches.py

@@ -5,14 +5,15 @@
 import warnings
 from dataclasses import dataclass, field
 from threading import Lock
-from typing import List, Optional, Tuple
+from typing import Any, Dict, List, Literal, Optional, Tuple
 from urllib.parse import unquote_plus
 
 import morecantile
 import pystac
 from cachetools import TTLCache, cached
 from cachetools.keys import hashkey
 from cogeo_mosaic.errors import MosaicNotFoundError
+from cql2 import Expr
 from fastapi import HTTPException, Path, Query
 from psycopg import errors as pgErrors
 from psycopg.rows import class_row, dict_row
@@ -42,13 +43,23 @@ def SearchIdParams(
 
 @cached(  # type: ignore
     TTLCache(maxsize=cache_config.maxsize, ttl=cache_config.ttl),
-    key=lambda pool, collection_id, ids, bbox, datetime, query, sortby: hashkey(
+    key=lambda pool,
+    collection_id,
+    ids,
+    bbox,
+    datetime,
+    query,
+    sortby,
+    filter_expr,
+    filter_lang: hashkey(
         collection_id,
         ids,
         bbox,
         datetime,
         query,
         sortby,
+        filter_expr,
+        filter_lang,
     ),
     lock=Lock(),
 )
@@ -66,10 +77,23 @@ def get_collection_id(  # noqa: C901
     ids: Optional[str] = None,
     bbox: Optional[str] = None,
     datetime: Optional[str] = None,
+    # Extensions
     query: Optional[str] = None,
     sortby: Optional[str] = None,
+    filter_expr: Optional[str] = None,
+    filter_lang: Literal["cql2-text", "cql2-json"] = "cql2-json",
 ) -> str:  # noqa: C901
     """Get Search Id for a Collection."""
+    search_params: Dict[str, Any] = {
+        "collections": [collection_id],
+        "datetime": datetime,
+    }
+    if ids:
+        search_params["ids"] = ids.split(",")
+
+    if bbox:
+        search_params["bbox"] = list(map(float, bbox.split(",")))
+
     sort_param: List[model.SortExtension] = []
     if sortby:
         for sort in sortby.split(","):
@@ -80,16 +104,21 @@ def get_collection_id(  # noqa: C901
                         direction="desc" if sortparts.group(1) == "-" else "asc",
                     )
                 )
+    if sort_param:
+        search_params["sortby"] = sort_param
 
-    search = model.PgSTACSearch(
-        collections=[collection_id],
-        ids=ids.split(",") if ids else None,
-        bbox=list(map(float, bbox.split(","))) if bbox else None,
-        datetime=datetime,
-        query=json.loads(unquote_plus(query)) if query else None,
-        sortby=sort_param or None,
-    )
+    if filter_expr:
+        if filter_lang == "cql2-text":
+            search_params["filter"] = Expr(filter_expr).to_json()
+            search_params["filter-lang"] = "cql2-json"
+        else:
+            search_params["filter"] = json.loads(filter_expr)
+            search_params["filter-lang"] = filter_lang
 
+    if query:
+        search_params["query"] = json.loads(unquote_plus(query))
+
+    search = model.PgSTACSearch.model_validate(search_params)
     with pool.connection() as conn:
         with conn.cursor(row_factory=dict_row) as cursor:
             cursor.execute(
@@ -210,6 +239,7 @@ def CollectionIdParams(
             },
         ),
     ] = None,
+    # Extensions
     query: Annotated[
         Optional[str],
         Query(
@@ -231,6 +261,28 @@ def CollectionIdParams(
             },
         ),
     ] = None,
+    filter_expr: Annotated[
+        Optional[str],
+        Query(
+            alias="filter",
+            description="""A CQL2 filter expression for filtering items.\n
+Supports `CQL2-JSON` as defined in https://docs.ogc.org/is/21-065r2/21-065r2.htmln
+Remember to URL encode the CQL2-JSON if using GET""",
+            openapi_examples={
+                "user-provided": {"value": None},
+                "landsat8-item": {
+                    "value": "id='LC08_L1TP_060247_20180905_20180912_01_T1_L1TP' AND collection='landsat8_l1tp'"  # noqa: E501
+                },
+            },
+        ),
+    ] = None,
+    filter_lang: Annotated[
+        Literal["cql2-text", "cql2-json"],
+        Query(
+            alias="filter-lang",
+            description="The coordinate reference system (CRS) used by spatial literals in the 'filter' value. Default is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`",
+        ),
+    ] = "cql2-text",
 ) -> str:
     """Collection endpoints Parameters"""
     return get_collection_id(
@@ -241,6 +293,8 @@ def CollectionIdParams(
         datetime=datetime,
         query=query,
         sortby=sortby,
+        filter_expr=filter_expr,
+        filter_lang=filter_lang,
     )
 
 

titiler/pgstac/dependencies.py

@@ -21,9 +21,6 @@
 # TODO: add "startsWith", "endsWith", "contains", "in"
 Operator = Literal["eq", "neq", "lt", "lte", "gt", "gte"]
 
-# ref: https://github.com/radiantearth/stac-api-spec/tree/master/fragments/filter#get-query-parameters-and-post-json-fields
-FilterLang = Literal["cql-json", "cql-text", "cql2-json"]
-
 
 class Metadata(BaseModel):
     """Metadata Model."""
@@ -135,8 +132,9 @@ class PgSTACSearch(BaseModel, extra="allow"):
     ids: Optional[List[str]] = None
     bbox: Optional[BBox] = None
     intersects: Optional[Geometry] = None
-    query: Optional[Dict[str, Dict[Operator, Any]]] = None
     datetime: Optional[str] = None
+    # Extensions
+    query: Optional[Dict[str, Dict[Operator, Any]]] = None
     sortby: Optional[List[SortExtension]] = Field(
         default=None,
         description="An array of property (field) names, and direction in form of '{'field': '<property_name>', 'direction':'<direction>'}'",  # noqa: E501
@@ -182,12 +180,7 @@ class PgSTACSearch(BaseModel, extra="allow"):
             ],
         },
     )
-    filter_crs: Optional[str] = Field(
-        default=None,
-        alias="filter-crs",
-        description="The coordinate reference system (CRS) used by spatial literals in the 'filter' value. Default is `http://www.opengis.net/def/crs/OGC/1.3/CRS84`",
-    )
-    filter_lang: Optional[FilterLang] = Field(
+    filter_lang: Optional[Literal["cql2-json"]] = Field(
         default="cql2-json",
         alias="filter-lang",
         description="The CQL filter encoding that the 'filter' value uses.",