Skip to content

bug(query): day-suffix relative durations in time_range ("7d") reach ClickHouse raw and error — sdk.md promises them #285

Closed

Description

@EricAndrechek

What happens

time_range.since accepts Go-duration strings, but the docs promise day suffixes:

since accepts RFC3339 timestamps or relative durations ('1h', '30m', '7d'). — docs/src/content/docs/sdk.md:276

"7d" is not a valid Go duration (time.ParseDuration stops at hours), so internal/query/builder.go:271's parse fails and the raw string falls through as a DateTime literal:

$ curl -X POST '.../v1/query?table=gh_events' -d '{"aggregations":[{"fn":"count","column":"*","alias":"total"}],"time_range":{"column":"event_ts","since":"7d"}}'
{"error":"clickhouse query: code: 41, message: Cannot read DateTime: unexpected alphabetical character: while converting '7d' to DateTime64(3, 'UTC') ..."}

"168h" works fine (verified against stats.wavehouse.dev). So: documented input → opaque ClickHouse error surfaced to the client (and per #271, as a 500/retryable).

Fix options

  1. Support day/week suffixes (recommended — matches docs and user intuition): pre-expand Nd → N*24h, Nw → N*168h before time.ParseDuration, mirroring how ClickHouse/Prometheus-style ranges read.
  2. Or validate and reject unparseable since/until with a clear 400 ("7d" is not a valid duration; use 168h) and fix sdk.md to stop advertising 7d.

Either way, the failure must not be a raw ClickHouse error (ties into #271's error-mapping work).

Workaround in the wild

The docs landing hero (docs/src/components/LiveDemo.astro) uses 168h with a comment pointing at this issue — clean that up when fixed.

Activity

  1. added
    bugSomething isn't working
    documentationImprovements or additions to documentation
    area/queryStructured query AST, SQL builder
    area/sdkTypeScript SDK (clients/ts/)
    on Jun 6, 2026
  2. moved this from Backlog to In progress in WaveHouse Task Boardon Jun 6, 2026
  3. added a commit that references this issue on Jun 8, 2026
    cfb43e4
  4. added a commit that references this issue on Jun 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/docsDocumentation, site/, READMEarea/queryStructured query AST, SQL builderarea/sdkTypeScript SDK (clients/ts/)bugSomething isn't workingdocumentationImprovements or additions to documentation

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions