Skip to content

feat: add Elasticsearch/Grafana date-math syntax to time filter - #2322

Open
pike00 wants to merge 1 commit into
beancount:mainfrom
pike00:date-math-syntax
Open

feat: add Elasticsearch/Grafana date-math syntax to time filter#2322
pike00 wants to merge 1 commit into
beancount:mainfrom
pike00:date-math-syntax

Conversation

@pike00

@pike00 pike00 commented Jul 27, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds Elasticsearch/Grafana-style date-math expressions (now-1y, now/M, now-1y/y, etc.) to the Fava time filter, with an explicit snap concept for period boundaries.

New syntax

now[+/-Nunit][/snap]
  • Units: d (days), w (weeks), M (months), y (years)
  • Snaps: /d, /w, /M, /y, /fy (fiscal year), /fQ (fiscal quarter)
  • Ranges: now-30d - now, now/M - now, now-1y/y - now/y

Without an explicit snap, the unit determines the period (e.g. now-1M = last calendar month, equivalent to now-1M/M).

Changes

Backend (src/fava/util/date.py)

  • DATEMATH_RE — regex for now[+/-N][unit][/snap]
  • _snap_date() — snaps to d/w/M/y/fy/fQ boundaries
  • _period_end_from_snap() — computes exclusive end from a snapped start
  • _eval_datemath() — evaluates a single date-math expression
  • _parse_datemath() — handles single and range date-math, tried before legacy parser
  • parse_date_resolved() — returns (begin, end, "YYYY-MM-DD to YYYY-MM-DD") for UI/API use
  • All legacy syntax (2024, year-1, FY2024, 2024 - 2025) preserved

Tests (tests/test_util_date.py)

  • 24 new parametrized tests: date-math singles, fiscal snaps, ranges, resolved descriptions
  • All 169 tests pass

Docs (docs/time-filter-syntax.md)

  • Full date-math section with snap explanation and step-by-step walkthroughs

Backward compatibility

All existing syntax continues to work unchanged. Date-math is tried first, then falls through to the legacy parser.

Snap concept

A snap rounds a date down to the start of a period. Without a snap, now-1y means "exactly 1 year ago" (a single point). With a snap, now-1y/y means "the start of the year that was 1 year ago" (the full calendar year). Without an explicit snap, the unit implies the snap — now-1M is equivalent to now-1M/M.

Adds now-relative date expressions (now-1y, now/M, now-1y/y, /fy, /fQ) and an explicit snap concept for date-math. All legacy syntax preserved.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant