Struct EventQuery 

pub struct EventQuery {

    pub session_id: Option<String>,
    pub session_ids: Option<Vec<String>>,
    pub event_type: Option<String>,
    pub permission_mode: Option<String>,
    pub framework: Option<String>,
    pub after_ts: Option<DateTime<Utc>>,
    pub before_ts: Option<DateTime<Utc>>,
    pub after_id: Option<i64>,
    pub limit: Option<usize>,
    pub order_by: EventOrder,
    pub direction: Option<Order>,
    pub api_requests_only: bool,
    pub exclude_api_requests: bool,
}

Composable query builder for event retrieval.

EventQuery provides a fluent API for constructing event queries with filters, ordering, and pagination.

Ordering Behavior

The query provides explicit ordering via the order_by field:

• EventOrder::Timestamp: Order by event timestamp (default)
• EventOrder::Id: Order by event ID

Use order_by_timestamp() or order_by_id() to set the ordering column, and with_direction() to control ascending/descending order.

Use Cases

• Recent events: Use order_by_timestamp() with Order::Desc (default)
• Watching new events: Use order_by_id() with after_id for pagination

Defaults

• order_by: EventOrder::Timestamp - orders by timestamp
• direction: Order::Desc for timestamp, Order::Asc for ID

Example

// Get 50 most recent events for a session (orders by timestamp DESC)
let query = EventQuery::new()
    .order_by_timestamp()
    .with_session(Some("session-123".to_string()))
    .with_limit(50);

// Watch for new events after ID 100 (orders by ID ASC)
let query = EventQuery::new()
    .order_by_id()
    .with_after_id(100)
    .with_limit(10);

Fields

session_id: Option<String>

Filter by session ID (mutually exclusive with session_ids)

session_ids: Option<Vec<String>>

Filter by multiple session IDs (mutually exclusive with session_id)

event_type: Option<String>

Filter by event type (case-insensitive)

permission_mode: Option<String>

Filter by permission mode

framework: Option<String>

Filter by framework (claude, cursor, gemini)

after_ts: Option<DateTime<Utc>>

Filter events after this timestamp (exclusive)

before_ts: Option<DateTime<Utc>>

Filter events before this timestamp (exclusive)

after_id: Option<i64>

Filter events after this ID (exclusive)

limit: Option<usize>

Maximum number of events to return

order_by: EventOrder

Column to order results by (default: Timestamp)

direction: Option<Order>

Sort direction (default: Desc for timestamp, Asc for ID)

api_requests_only: bool

When true, only return API request events (events with token data)

exclude_api_requests: bool

When true, exclude API request events

Implementations

impl EventQuery

pub fn new() -> Self

Create a new empty query.

The query defaults to ordering by timestamp (descending). Use order_by_id() for ID-based ordering (e.g., when watching for new events).

pub fn order_by_timestamp(self) -> Self

Order results by timestamp.

This is the default ordering and is suitable for viewing recent events. Default direction is Order::Desc (newest first).

Example

let query = EventQuery::new()
    .order_by_timestamp()
    .with_limit(50);

pub fn order_by_id(self) -> Self

Order results by ID.

Use this when watching for new events with after_id pagination. Default direction is Order::Asc (oldest first, for forward pagination).

Example

let query = EventQuery::new()
    .order_by_id()
    .with_after_id(100)
    .with_limit(10);

pub fn with_after_ts(self, ts: DateTime<Utc>) -> Self

Filter events after the given timestamp (exclusive)

pub fn with_before_ts(self, ts: DateTime<Utc>) -> Self

Filter events before the given timestamp (exclusive)

pub fn with_between_ts(self, start: DateTime<Utc>, end: DateTime<Utc>) -> Self

Filter events between two timestamps (exclusive on both ends).

Note: If start >= end, the filter will return no results. The caller is responsible for ensuring start < end for meaningful queries.

pub fn with_after_id(self, id: i64) -> Self

Filter events after the given ID (exclusive).

Use with order_by_id() for consistent pagination when watching for new events.

Example

let query = EventQuery::new()
    .order_by_id()
    .with_after_id(last_seen_id)
    .with_limit(10);

pub fn with_limit(self, limit: usize) -> Self

Set the maximum number of events to return

pub fn with_direction(self, direction: Order) -> Self

Set the sort direction (Asc/Desc).

This controls whether results are in ascending or descending order. If not set, defaults to Order::Desc for timestamp ordering and Order::Asc for ID ordering.

pub fn with_session(self, session_id: Option<String>) -> Self

Set session filter if value is Some.

Note: This clears any previously set session_ids filter.

pub fn with_sessions(self, session_ids: &[impl AsRef<str>]) -> Self

Filter events by multiple session IDs.

Use this to efficiently query events for multiple sessions in a single database query, avoiding the N+1 query problem.

Note: This clears any previously set session_id filter. Passing an empty slice will result in no events being returned.

Example

// Get events for multiple sessions at once
let events = storage.query(
    &EventQuery::new()
        .with_sessions(&["session-1", "session-2", "session-3"])
        .with_event_type(Some("UserPromptSubmit".to_string()))
        .with_limit(100)
)?;

pub fn with_event_type(self, event_type: Option<String>) -> Self

Set event type filter if value is Some

pub fn with_permission_mode(self, permission_mode: Option<String>) -> Self

Set permission mode filter if value is Some

pub fn with_framework(self, framework: impl Into<String>) -> Self

Filter by framework

pub fn api_requests_only(self) -> Self

Only return API request events (events with token data)

pub fn exclude_api_requests(self) -> Self

Exclude API request events from results

pub fn effective_direction(&self) -> Order

Returns the effective sort direction for this query.

Storage implementations should use this method to determine the sort direction when executing queries.

Returns

• If direction is explicitly set, returns that value.
• For EventOrder::Id, defaults to Order::Asc (for watching new events).
• For EventOrder::Timestamp, defaults to Order::Desc (most recent first).

Example

use mi6_core::{EventQuery, Order};

// Default: Desc for timestamp ordering
let query = EventQuery::new();
assert_eq!(query.effective_direction(), Order::Desc);

// With order_by_id: Asc for watching
let query = EventQuery::new().order_by_id();
assert_eq!(query.effective_direction(), Order::Asc);

// Explicit direction overrides default
let query = EventQuery::new().with_direction(Order::Asc);
assert_eq!(query.effective_direction(), Order::Asc);

pub fn orders_by_id(&self) -> bool

Returns true if this query should order by ID instead of timestamp.

Storage implementations should use this method to determine which column to use for ordering results.

Example

use mi6_core::EventQuery;

// Default: order by timestamp
let query = EventQuery::new();
assert!(!query.orders_by_id());

// With order_by_id(): order by ID
let query = EventQuery::new().order_by_id();
assert!(query.orders_by_id());

Trait Implementations

impl Clone for EventQuery

fn clone(&self) -> EventQuery

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for EventQuery

fn default() -> EventQuery

Returns the “default value” for a type.