fix(ogc): send Water Data list filters and CQL2 JSON filters correctly

[thodson-usgs]

Summary

A list passed to most filters of the waterdata OGC getters returned an empty frame. get_daily(bbox=..., time=..., approval_status="Approved") returns 759 rows; approval_status=["Approved", "Provisional"] returned 0, without an error. The library sent lists as comma-joined GET values, and the Water Data API reads that as one value for most parameters.

How I checked. For every list-valued parameter of the 11 Water Data OGC getters, I sampled two real values (bbox around Madison, WI) and compared three things:

• a comma-joined GET;
• a CQL2 in POST;
• the union of the two single-value requests.

That covered all collections on v1 and three on v0; v0 behaved the same way.

Result	Count
Comma GET correct	36 parameter/collection pairs, all identifiers or codes: monitoring_location_id, monitoring_location_number, parameter_code, statistic_id, time_series_id, computation_identifier, computation_period_identifier, data_type, and field_visit_id on channel-measurements (but not on field-measurements)
Comma GET returns 0 rows (HTTP 200)	~90 text parameters, e.g. approval_status, unit_of_measure, site_type_code, hydrologic_unit_code, sublocation_identifier
Comma GET returns HTTP 400	the numeric parameters: altitude, drainage_area, the well depths
CQL2 POST	correct for every parameter tested

Another 40 had too few distinct values in the sample to test.

The behavior varies by parameter, not by collection, so the per-collection cql2_services field had it backwards. It also had a second bug: with a CQL-text filter=, the server ignores the POST body. On monitoring-locations, a two-site list plus a filter returned 10,000 rows instead of 2. That already affects get_monitoring_locations() and get_combined_metadata() on main.

Change

• OgcDialect.cql2_services (per collection) is replaced by OgcDialect.lists_as_cql2 (per API), which WATERDATA_DIALECT sets.
• With it set, every multi-value filter is a CQL2 in predicate in a POST body.
• With a CQL-text filter, the lists are added to the filter as prop IN ('a', 'b') AND (filter) and sent by GET. ogc.filters._cql_in_clause builds that clause, and waterdata.ratings now uses it for its STAC filter too. The values are quoted, because every Water Data queryable is typed as a string; numbers work quoted or not.
• NGWMN is unchanged and keeps comma-joined GETs:
  • it reads them as lists (checked for site ids and state_name);
  • its firewall answers any text filter naming a site, with = or IN, with HTTP 403, so a list can't be folded into a filter there;
  • it answers a POST body plus a text filter with HTTP 400.

A CQL2 JSON filter goes in the request body. filter_lang="cql-json" failed with HTTP 400 "Bad CQL text" in every Water Data OGC getter. OGC API Features allows a CQL2 JSON filter in the URL, but neither the Water Data nor the NGWMN API reads one there; both accept it as a POST body (checked 2026-10-11). The body is ANDed with any list predicates. On NGWMN, comma-joined list values stay in the URL beside it. A filter that isn't a JSON object raises ValueError before sending.

Apostrophes in a folded value. The API's CQL-text parser rejects the standard '' escape for an apostrophe with HTTP 400 (v0 and v1, checked 2026-10-12). A folded value containing ' is therefore double-quoted. A double-quoted token that names a property is read as that property, which a value containing ' can't be. A value with both quote characters raises ValueError. _cql_text_literal replaces _quote_cql_str.

Blank filter. filter="" (or whitespace) is no longer sent, and neither is its filter_lang; the API answered it with HTTP 400.

Tests

• Offline: 10 request-shape tests now assert the CQL2 body instead of the comma-joined URL. New tests cover the text-filter fold (with apostrophe quoting and the both-quotes error), the blank filter, and the comma-join default for a dialect without the switch. All 1,263 pass, and coverage is 99.03%. ruff, mypy, import-linter, xenon and complexipy are clean.
• CQL2 JSON filter: offline tests cover the filter alone, ANDed with lists, beside NGWMN-style comma values, and rejected when it isn't a JSON object. A live test checks that a JSON filter returns the same rows as its text form, using the filter the error message suggests.
• Live: a new live test checks that a list value containing an apostrophe, folded into a text filter, returns its rows. Another @pytest.mark.live test checks that get_daily(approval_status=[a, b]) returns the rows of a plus the rows of b, with and without a text filter. Both pass on this branch; the version without a filter returns 0 rows on main.
• Live checks, compared with main:
  • a site list plus a text filter: 62 rows, expected 62;
  • get_monitoring_locations with a list plus a filter: 2 rows, expected 2;
  • a 600-site chunked get_latest_daily: 93 rows, the same as main;
  • get_nearest_continuous with two sites: 3 rows, the same as main;
  • ngwmn.get_water_level with two sites: unchanged.

Notes

• Getter docstrings are unchanged. The fix makes filter_lang="cql-json" work as documented, so the docstrings don't describe how it is sent.

• Cost of the text-filter fold. An IN clause costs about 10 bytes per value, where a comma-joined value costs 3. A large list combined with filter= therefore splits into roughly 1.45–2× as many chunks, which means more requests against the hourly quota. A simplify-pass measurement on 3,000 site ids with a filter gave 16 chunks instead of 8. Without a filter, the POST body is no larger than the comma form (8 chunks either way). Keeping comma-joined GETs for the identifier parameters would avoid this, but it needs a list of the parameters the API reads correctly, which is the option this PR deliberately doesn't take.

• Caching: list queries on every collection are now POSTs. I haven't checked whether the edge caches GET responses; if it does, those queries no longer get cache hits.

• Follow-up: get_cql still sends its verbatim body through a separate builder (cql_body). It could use the filter_lang="cql-json" path instead, but that changes behavior (the body is parsed and re-serialized), so it isn't part of this PR.

• Conflict with ADR 0014 (proposed): Service declarations and OGC endpoints #445: ADR 0014 (proposed): Service declarations and OGC endpoints #445 renames cql2_services to cql2_collections and groups the dialect fields. If this merges first, ADR 0014 (proposed): Service declarations and OGC endpoints #445's rebase replaces that rename with this switch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HBt3Ee7eneKtdKQWq2T3YK

[thodson-usgs]

claude, see my suggestions

[thodson-usgs]

is there a more intuitive name for this function?

[thodson-usgs]

Renamed to lists_as_cql2 ("send lists as CQL2"), in b98b45f. It names what the request builder does with a list, which multi_value_cql2 left implicit.

[thodson-usgs]

revert this change, similarly for other occurrences of filter, filter_lang. Should filter and filter_lang be given the same name? Should we omit the comment on lexicographic-comparison pitfalls.

[thodson-usgs]

Reverted the docstring change in all 11 getters (b98b45f). The fix makes cql-json work as users already expect, so the docstrings do not need to describe the transport.

On your two questions:

• One name for filter and filter_lang: I would keep them separate. They mirror the OGC filter / filter-lang query parameters, and R dataRetrieval uses the same pair. One possible follow-up is to accept a dict for filter and infer cql-json from that, but that is a new feature, not part of this fix.
• The lexicographic-pitfall pointer: I agree it should go. :mod:dataretrieval.ogc.filters is not in the reference docs, so the link goes nowhere, and the module docstring does not explain the pitfall to users anyway. _check_numeric_filter_pitfall already raises a ValueError that explains it when a filter triggers it. The pointer is on main in all 11 getters, so I would remove it in a small separate PR rather than add docstring changes back to this one. Want me to open that?

[thodson-usgs]

Too verbose, can you explain the fixes in roughly half the length.

[thodson-usgs]

Cut from 180 words to 101 (b98b45f). It keeps the approval_status example, the cause, and the three changes in behavior, and drops the list of parameters that did work and the explanation of why the text filter dropped the list.