WITHIN: filtering by timestamp
You use the WITHIN command to filter events by their timestamp. This command automatically finds the primary timestamp field in your dataset and filters events to match your specified time criteria, making time-based filtering straightforward and readable.
Basic syntax
The WITHIN command filters your dataset to include only events that occurred within your specified time window. Hamelin automatically identifies the timestamp field in your data, so you don't need to specify field names.
Pull events that happened in the last hour:
FROM events | WITHIN -1hr
Get events from a specific time window in the past:
FROM security_events | WITHIN -4hr..-2hr
Analyze only today's events using time truncation:
FROM system_logs | WITHIN now()..now()
Look at yesterday's complete activity:
FROM audit_logs | WITHIN (now() - 1d)..(now())
Time intervals vs time ranges
You can use WITHIN with either time intervals or time ranges.
Time intervals get automatically converted to ranges that start or end at "now". This makes them perfect for recent event analysis:
# Negative intervals go backward from now
FROM alerts | WITHIN -1hr # Last hour: -1hr..now()
# Positive intervals go forward from now
FROM alerts | WITHIN 2hr # Next 2 hours: now()..2hr
Time ranges work exactly as you define them, giving you precise control over both start and end points:
# Bounded range: specific start and end
FROM events | WITHIN -4hr..-2hr
# Unbounded range: from start onward
FROM alerts | WITHIN -1hr..
# Range ending at now
FROM events | WITHIN -2hr..now()
Backward vs forward time intervals
Negative intervals look backward from now to capture recent events:
FROM events | WITHIN -30min # Events from 30 minutes ago until now
FROM events | WITHIN -1d # Events from 1 day ago until now
Positive intervals look forward from now, which is useful for scheduled events or planned activities:
FROM scheduled_tasks | WITHIN 2hr # Tasks scheduled for next 2 hours
FROM alerts | WITHIN 15min # Alerts expected in next 15 minutes