Struct LogQuery 

pub struct LogQuery<'a> { /* private fields */ }

Builder for configuring and executing log queries from indexed journal files.

This builder allows you to specify:

• Direction (forward/backward in time)
• Anchor timestamp (starting point)
• Limit (maximum entries to retrieve)
• Source timestamp field (which field to use for timestamps)
• Filter (to match specific entries)

Example

use journal_index::{Anchor, Direction};
use journal_function::logs::LogQuery;

let entries = LogQuery::new(&file_indexes, Anchor::Head, Direction::Forward)
    .with_limit(100)
    .execute();

Implementations

impl<'a> LogQuery<'a>

pub fn new( file_indexes: &'a [FileIndex], anchor: Anchor, direction: Direction, ) -> Self

Create a new log query builder with required parameters.

Arguments

• file_indexes - Journal file indexes to query
• anchor - Starting point for the query (Head, Tail, or specific timestamp)
• direction - Direction to iterate (Forward or Backward)

Optional Configuration

Use builder methods to set optional parameters:

• Limit: None (unlimited)
• Source timestamp field: _SOURCE_REALTIME_TIMESTAMP
• Filter: None

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

Set the maximum number of log entries to retrieve (optional).

If not set (None), all matching entries will be retrieved.

pub fn with_source_timestamp_field(self, field: Option<FieldName>) -> Self

Set the source timestamp field to use for entry timestamps (optional).

Pass None to use the entry’s realtime timestamp from the journal header. Pass Some(field_name) to use a custom timestamp field from the entry data.

pub fn with_filter(self, filter: Filter) -> Self

Set a filter to apply to log entries (optional).

Only entries matching the filter will be included in the results.

pub fn with_after_usec(self, after: u64) -> Self

Set the lower time boundary (inclusive) in microseconds (optional).

Only entries with timestamp >= after_usec will be included. This enforces a hard boundary regardless of anchor or limit.

pub fn with_before_usec(self, before: u64) -> Self

Set the upper time boundary (exclusive) in microseconds (optional).

Only entries with timestamp < before_usec will be included. This enforces a hard boundary regardless of anchor or limit.

pub fn with_regex(self, pattern: impl Into<String>) -> Self

Set a regex pattern for full-text search (optional).

Only entries where at least one data object (in “FIELD=value” format) matches the regex will be included in the results.

The pattern will be compiled when the query is executed. Invalid patterns will cause execute() to return an error.

pub fn with_cancellation(self, token: CancellationToken) -> Self

Set a cancellation token for the query (optional).

When set, the query will check the token before processing each file and return early with partial results if cancelled.

pub fn with_progress(self, counter: Arc<AtomicUsize>) -> Self

Set a progress counter for the query (optional).

When set, the counter is incremented (via fetch_add) after each file is processed in retrieve_log_entries.

pub fn with_output_fields<I, S>(self, fields: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Limit returned field-value pairs to the requested on-disk field names.

pub fn execute(self) -> Result<Vec<LogEntryData>>

Execute the query and return log entries.

This consumes the builder and returns a vector of log entries sorted by timestamp according to the configured direction.

Errors

Returns an error if anchor or direction were not set, or if time boundaries are invalid.

pub fn execute_page( self, state: Option<&PaginationState>, ) -> Result<(Vec<LogEntryData>, PaginationState)>

Execute the query with pagination support.

This consumes the builder and returns a page of log entries along with pagination state that can be used to retrieve the next page.

Arguments

• state - Optional pagination state from a previous query. Pass None for the first page.

Returns

Returns a tuple of (log entry data, new pagination state). If the pagination state is empty (no file positions tracked), there are no more results.

Errors

Returns an error if anchor or direction were not set, or if time boundaries are invalid.