Filtering behavior on array fields?

[emmanuelmathot]

I am struggling finding out the proper filtering behaviour for array fields. The only example I find in the spec is the Example 15

Example 15 : Using the IN List predicate

The predefined function IN allows for checking if a value is in a list of values.

Example 15: cql2-text (GET)

filter=keywords IN ('fire', 'forest', 'wildfire')

Example 15: cql2-json (POST)

{
    "filter-lang": "cql2-json",
    "filter": {
        "op": "in",
        "args": [
            {
                "property": "keywords"
            },
            [
                "fire",
                "forest",
                "wildfire"
            ]
        ]
    }
}

My understanding is that any items with any of the "fire", "forest", "wildfire" string in the keywords array field will be returned.

What about the following example:

filter=keywords = 'fire'

cql2-json (POST)

{
    "filter-lang": "cql2-json",
    "filter": {
        "op": "eq",
        "args": [
            {
                "property": "keywords"
            },
            "fire"
        ]
    }
}

I would expect that any items with the "fire" string in the keywords array field will be returned. From a user pov and STAC browser current implementation, I believe this is how it should be handled.

cc @bitnerd @philvarner @gadomski @jonhealy1 @batpad

If we agree, can we precise the filtering behaviour in the spec?

[gadomski]

I would expect that any items with the "fire" string in the keywords array field will be returned

I'm no CQL2 expert, but I think equality (=) doesn't work with collections, such as a keywords array. I think you need to use in or has?

[batpad]

I tried a few variations:

@emmanuelmathot what you have above:

{
    "filter-lang": "cql2-json",
    "filter": {
        "op": "eq",
        "args": [
            {
                "property": "keywords"
            },
            "fire"
        ]
    }
}

does NOT work. But, if I pass the query as an array, then this works, so:

{
    "filter-lang": "cql2-json",
    "filter": {
        "op": "eq",
        "args": [
            {
                "property": "keywords"
            },
            ["fire"]
        ]
    }
}

In my attempts, using the in operator with a string or array of strings as query did not work (returned 0 results), and has was not recognized as a valid operator.

[philvarner]

The behavior of eq is implementation-dependent for arrays. For example, as @emmanuelmathot said, the below doesn't work in the implementation he's using, but it does in stac-server using OpenSearch, because OpenSearch treats an array value as if the field had each of the values individually.

{
    "filter-lang": "cql2-json",
    "filter": {
        "op": "eq",
        "args": [
            {
                "property": "keywords"
            },
            "fire"
        ]
    }
}

For consistent behavior, we have to use the CQL2 Array Functions https://docs.ogc.org/is/21-065r2/21-065r2.html#array-functions. which allows equals, contains, contained_by, and overlaps, and would allow:

{
  "op": "a_contains",
  "args": [
    { "property": "keywords" },
    [ "fire" ]
  ]
}