feat(waterdata): add get_cql for generalized CQL2 queries

[thodson-usgs]

Summary

Adds get_cql(service, cql, ...) — a single public entry point for querying any Water Data OGC API collection with an arbitrary CQL2 filter, for predicates the typed getters (get_daily, get_continuous, …) can't express: a top-level or, like with % wildcards, comparison operators (</>/between), nested boolean trees, and geometry predicates beyond a bounding box.

The CQL2 body (a Python dict or a pre-serialized JSON str) is POSTed verbatim against the collection; the result is shaped exactly like the typed getters — wire id renamed to the service's id column, columns ordered/sorted, dtypes coerced — and returned as (DataFrame, BaseMetadata).

Like get_stats_data (and unlike the chunked typed getters), this is a single request: the CQL body is opaque, so there's nothing to chunk; server-side CQL errors surface as the module's standard typed errors. CQL2 grammar: https://api.waterdata.usgs.gov/docs/ogcapi/complex-queries/

API

def get_cql(
    service: WATERDATA_SERVICES,
    cql: str | dict,
    *,
    properties: str | Iterable[str] | None = None,
    bbox: list[float] | None = None,
    limit: int | None = None,
    skip_geometry: bool | None = None,
    convert_type: bool = True,
) -> tuple[pd.DataFrame, BaseMetadata]:

from dataretrieval import waterdata

# Monitoring locations whose HUC starts with "02070010" — LIKE with a % wildcard.
df, md = waterdata.get_cql(
    service="monitoring-locations",
    cql={"op": "like", "args": [{"property": "hydrologic_unit_code"}, "02070010%"]},
)

service is validated against WATERDATA_SERVICES (the 11 OGC time-series collections); properties honors the same "id" → service id-column rewrite as the typed getters.

Implementation

Reuses existing module machinery rather than duplicating it:

• _construct_cql_request (utils): POST/CQL2 builder for a verbatim body; shares the skipGeometry/limit/bbox/properties URL block with _construct_api_requests via the extracted _ogc_query_params.
• Fetch goes through the same non-chunked anyio-portal path as get_stats_data, extracted as _run_sync; result shaping reuses the existing _finalize_ogc hook.
• _OUTPUT_ID_BY_SERVICE / WATERDATA_SERVICES: the 11 OGC collections and their id columns, kept in sync (guarded by a test).

Also in this PR: adopt _OUTPUT_ID_BY_SERVICE across the typed getters

The 11 typed getters each hardcoded their output_id (e.g. daily → "daily_id") and passed it to get_ogc_data, duplicating the service→id map. get_ogc_data now derives output_id from service via the map (single source of truth); output_id becomes an optional override that get_reference_table (metadata collections, not in the map) still passes. Drops the 11 hardcoded assignments.

Tests

• Unit: _construct_cql_request builds the right POST/URL/verbatim body; skip_geometry=None omits the param; an unknown service raises; the WATERDATA_SERVICES ↔ _OUTPUT_ID_BY_SERVICE sync invariant.
• Live: compound AND-of-INs, str/dict body equivalence, "id" → output_id translation, LIKE wildcard — plus all typed getters re-verified after the refactor.

ruff clean; verified against the live API.

Addresses #198

🤖 Generated with Claude Code

[thodson-usgs]

do we need to shield this against string comparisons as we do in filters.py?