Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to Filter Extension for CQL2 #225

Merged
merged 13 commits into from
Dec 3, 2021
109 changes: 109 additions & 0 deletions fragments/filter/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,15 @@
- [Example 9: Using IS NULL](#example-9-using-is-null)
- [Example 9: cql2-text (GET)](#example-9-cql2-text-get)
- [Example 9: cql2-json (POST)](#example-9-cql2-json-post)
- [Example 10: Using BETWEEN](#example-10-using-between)
- [Example 10: cql2-text (GET)](#example-10-cql2-text-get)
- [Example 10: cql2-json (POST)](#example-10-cql2-json-post)
- [Example 11: Using LIKE](#example-11-using-like)
- [Example 11: cql2-text (GET)](#example-11-cql2-text-get)
- [Example 11: cql2-json (POST)](#example-11-cql2-json-post)
- [Example 12: Using Case-insensitive Comparison Functions](#example-12-using-case-insensitive-comparison-functions)
- [Example 12: cql2-text (GET)](#example-12-cql2-text-get)
- [Example 12: cql2-json (POST)](#example-12-cql2-json-post)

## Overview

Expand Down Expand Up @@ -932,3 +941,103 @@ filter=sentinel:data_coverage > 50 OR landsat:coverage_percent < 10 OR (sentinel
}
}
```

### Example 10: Using BETWEEN

The BETWEEN operator allows for checking if a numeric value is within a specified inclusive range.

#### Example 10: cql2-text (GET)

```http
filter=eo:cloud_cover BETWEEN 0 AND 50
```

#### Example 10: cql2-json (POST)

```json
{
"filter": {
"op": "between",
"args": [
{ "property": "eo:cloud_cover" },
[ 0, 50 ]
]
}
}
```

### Example 11: Using LIKE

The LIKE operator allows for pattern-based string matching.


{ "op" : "in", "args" : [ { "property" : "prop-name" }, [ 123, 456 ] ] }
{ "function" : "my-func", "args" : [ "myarg1", 123 ] }


#### Example 11: cql2-text (GET)

```http
filter=mission LIKE "sentinel%"
```

#### Example 11: cql2-json (POST)

```json
{
"filter": {
"op": "like",
"args": [
{ "property": "mission" },
"sentinel%"
]
}
}
```

### Example 12: Using Case-insensitive Comparison Functions

The predefined functions `UPPER` and `LOWER` allow for case-insensitive comparisons, and are used in the same way
user-defined functions are.

#### Example 12: cql2-text (GET)

```http
filter=LOWER(provider) == "coolsat"
```

```http
filter=UPPER(provider) == "NASA"
```

#### Example 12: cql2-json (POST)

```json
{
"filter": {
"op": "eq",
"args": [
{
"function" : "lower",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So upper and lower are implemented as "function" not with "op"?

As these are standard, shouldn't they use "op"? My impression is that "function" was for platform defined functions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct. They're not operators since they don't return a boolean value -- they return a string value. However, I looked it up in the spec and I did define them wrong -- they're not operators or functions, they're a separate thing, which is confusing, because the text syntax is exactly the same as if they were functions. I'll update the examples.

The spec is here:
https://github.com/opengeospatial/ogcapi-features/blob/b752479d850c52f372c4164202f041ecbe906e46/cql2/standard/schema/cql2.json

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm going to ask the CQL2 folks about this, because it seems like it would be simpler if it was just a pre-defined function.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Collaborator Author

@philvarner philvarner Dec 2, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, so this is changing in CQL2 opengeospatial/ogcapi-features#641

UPPER/LOWER will be replaced with a function CASEI

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After looking at CASEI, I have some significant concerns about it. I'm just going to yank it for beta.5, and re-add after it's stabilitzed in CQL2. I wrote up the concerns here if you're interested
opengeospatial/ogcapi-features#641 (comment)

"args": [ { "property": "provider" } ]
},
"coolsat"
]
}
}
```

```json
{
"filter": {
"op": "eq",
"args": [
{
"function": "upper",
"args": [ { "property": "provider" } ]
},
"NASA"
]
}
}
```