cql2-filter-builder

name	cql2-filter-builder
description	Use when the user wants to filter AQUAVIEW search results on numerical thresholds for ocean/atmospheric variables — phrases like "waves over 6 m", "SST above 28°C", "min pressure under 10 dbar", "salinity between 34 and 35", "wind speed greater than 25 m/s". Encodes CQL2 syntax for STAC item statistics so the agent emits valid filters on the first try.

CQL2 filter builder

AQUAVIEW indexes per-variable statistics on every STAC item under properties.cube:variables. CQL2 lets you filter on those stats without fetching items first.

The path pattern

For any variable <VAR>, the filterable paths are:

properties->>'cube:variables'->>'<VAR>'->>'min'
properties->>'cube:variables'->>'<VAR>'->>'max'
properties->>'cube:variables'->>'<VAR>'->>'mean'
properties->>'cube:variables'->>'<VAR>'->>'std'

For STAC-standard properties (cloud cover, instrument, off-nadir), use direct property paths:

properties.eo:cloud_cover
properties.platform
properties.sar:instrument_mode
properties.sar:polarizations

Comparison + composition

CQL2-Text uses SQL-like syntax:

properties->>'cube:variables'->>'wave_height'->>'max' > 6

Combine with AND / OR:

properties->>'cube:variables'->>'wave_height'->>'max' > 6
AND properties->>'cube:variables'->>'wind_speed'->>'mean' > 15

Pass to search_datasets as filter="<CQL2>" with filter_lang="cql2-text".

Common gotchas

• Variable name casing matters. It's sst, not SST. It's wave_height, not Wave_Height. When unsure, run search_datasets once with limit=1 and inspect properties['cube:variables'] keys before authoring the filter.
• Per-collection naming differs. sst in COASTWATCH may be analysed_sst in another collection. The skill sst-and-ocean-color has the canonical mapping.
• min/max are per-item stats (across the item's spatial/temporal extent), not per-pixel. To filter "any pixel above X," use max > X. To filter "all pixels above X," use min > X.
• NaN/null variables simply don't match comparisons. There is no IS NULL shortcut — assume missing means "not in scope."
• Don't quote numeric thresholds. > 6 is correct; > "6" will fail.

Worked examples

See examples.md for 10 fully-worked CQL2 filters mapped from plain English.