Search STAC using the Filter extension - Esri/geoportal-server-catalog GitHub Wiki

Introduction

Our STAC API implementation has been enhanced with support for the Filter Extension. This extension gives greater flexibility in finding STAC items using a more sophisticated query using the Open Geospatial Consortium CQL2 Text or JSON language.

Preparing for Filter Support

To get the best result for searches using the Filter Extension:

Know your STAC item properties

STAC item properties may be of different data types, such as text, long, double, boolean, date. Also understand the different prefixes (like eo or pc) you have in your STAC items. These typically (not necessarily) point to the extension being used to define the properties.

Setup Field Mapping

Unless you modify WEB-INF/classes/config/elastic-mappings-7.json directly before creating the index, you'll have to tell Geoportal Server what data type your fields are. Typically, it is not possible to change the data type or mapping of a field that already has data in the index. Geoportal Server can use the dynamic templates to make the index treat the data in the right data type.

Predefined dynamic templates include:

  • _txt = free text field
  • _s = keyword field
  • _b = boolean field
  • _i = integer field
  • _l = long field
  • _f = float field
  • _d = double field
  • _dt = date field: e.g. 2025-01-16T11:35:56.732Z
  • _cat = hierarchical category field: e.g. continent > country > state/province > county/municipality > city > neighborhood ...

For oriented imagery, you may have the following mapping of a few of the image attributes. Each of these fields has double values. The mapped field is stored in the properties of the JSON.

<beans:value>CameraHeading=properties.CameraHeading_d</beans:value>
<beans:value>CameraPitch=properties.CameraPitch_d</beans:value>
<beans:value>CameraRoll=properties.CameraRoll_d</beans:value>

Update STAC configuration files

When Geoportal Server outputs STAC responses, it uses a series of template files to populate the response. Update the template files stac-item.json, stac-items.json, and stac-queryables.json in geoportal/WEB-INF/classes/service/config with the fields and extensions you're using. For example, in stac-item.json you may find a section like below:

  ...
  "properties": {
    "updated": "$._source.sys_modified_dt",
    "datetime": "$._source.sys_modified_dt",
    
    "eo:sun_azimuth": "$._source.properties._SunAzimuth_l",
    "eo:sun_elevation": "$._source.properties._SunZenith_l",
    "eo:cloud_cover": "$._source.properties._CloudCover_l",

    "CameraRoll": "$._source.properties.CameraRoll_d",
    "Name": "$._source.properties.Name",
    "CameraPitch": "$._source.properties.CameraPitch_d",
    "CameraHeading": "$._source.properties.CameraHeading_d",

This indicates that the STAC item has properties like eo:sun_azimuth that in this example is mapped to $._source.properties._SunAzimuth_l.

Reference STAC Extensions

In the configuration files, update the reference to the extensions to match the content in your STAC. For example:

  "stac_extensions": [
    "https://stac-extensions.github.io/eo/v2.0.0/schema.json",
    "https://stac-extensions.github.io/pointcloud/v2.0.0/schema.json",
    "https://stac-extensions.github.io/video/v1.0.0/schema.json"
  ],

Publish Items and Test

Follow the Filter Extension page for CQL2 syntax and construct your tests.

An example:

curl --location 'http://localhost:8081/geoportal/stac/search' \
--header 'Content-Type: application/json' \
--data '{
    "filter": {
        "op": "and",
        "args": [
            {
                "op": "=",
                "args": [
                    { "property": "OrientedImageryType"},
                    { "literal": "Horizontal"}
                ]
            },
            {
                "op": "<",
                "args": [
                    { "property": "CameraHeading"},
                    { "literal": 179}
                ]
            }
        ]
    }
}'