As a data user, I want to use relative time and date-math expressions in queries

[jordanpadams]

Checked for duplicates

Yes - I've already checked

🧑‍🔬 User Persona(s)

Data User, Data Engineer, Planetary Scientist, Automated Systems/CI-CD Pipelines

💪 Motivation

...so that I can easily find recent data without manually calculating dates, and create time-based queries that work consistently in automated systems.

📖 Additional Details

Current Behavior:

• before() and after() require explicit datetime objects
• No support for relative time expressions like "last 30 days" or "this year"
• Users must manually calculate dates for common time periods

Proposed Solution:
Support string-based date-math syntax (Elasticsearch-inspired):

# Relative time expressions
products.after("now-30d")
products.after("now-1y").before("now")
products.after("now-6M")  # 6 months

# Date ranges with slash notation
products.during("2020/2023")  # Start of 2020 to end of 2023
products.during("now-1y/now")

# Named periods
products.after("today")
products.during("this-year")
products.during("last-month")

# Backward compatible with datetime objects
products.after(datetime(2020, 1, 1))

Implementation Approach:

1. Extend before() and after() to accept Union[datetime, str]
2. Add new during() method for date ranges
3. Implement _parse_date_math() helper supporting:
   • Units: d (days), w (weeks), M (months), y (years)
   • Relative: now, today, now-30d, now+1w
   • Named: this-year, last-month, etc.
4. Maintain backward compatibility with datetime objects

Related:

• Part of Priority Requirements PDF (Requirement 2)
• Replaces closed issue As a user, I want to use relative time and date-math in queries #145

---

For Internal Dev Team To Complete

Acceptance Criteria

Given a user wants to query recent data
When I perform products.after("now-30d")
Then I expect products with dates after 30 days ago from current time

⚙️ Engineering Details

To be filled by Engineering Node Team

🎉 I&T

To be filled by Engineering Node Team