Struct QueryBuilder 

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

Builder for creating and executing document queries.

QueryBuilder uses a fluent interface pattern to construct and execute queries against Aurora collections.

Examples

// Query for active premium users
let premium_users = db.query("users")
    .filter(|f| f.eq("status", "active") && f.eq("account_type", "premium"))
    .order_by("created_at", false)
    .limit(10)
    .collect()
    .await?;

Implementations

impl<'a> QueryBuilder<'a>

pub fn new(db: &'a Aurora, collection: &str) -> Self

Create a new query builder for the specified collection

Examples

let query = db.query(“users”);

pub fn filter<F>(self, filter_fn: F) -> Self

where F: Fn(&FilterBuilder<'_, '_>) -> bool + Send + Sync + 'a,

Add a filter function to the query

Examples

let active_users = db.query(“users”) .filter(|f| f.eq(“status”, “active”)) .collect() .await?;

pub fn order_by(self, field: &str, ascending: bool) -> Self

Sort results by a field (ascending or descending)

Parameters

• field - The field to sort by
• ascending - true for ascending order, false for descending

Examples

// Sort by age ascending
.order_by("age", true)

// Sort by creation date descending (newest first)
.order_by("created_at", false)

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

Limit the number of results returned

Examples

// Get at most 10 results
.limit(10)

pub fn offset(self, offset: usize) -> Self

Skip a number of results (for pagination)

Examples

// For pagination: skip the first 20 results and get the next 10
.offset(20).limit(10)

pub fn select(self, fields: &[&str]) -> Self

Select only specific fields to return

Examples

// Only return name and email fields
.select(&["name", "email"])

pub fn debounce(self, duration: Duration) -> Self

Set debounce/throttle interval for reactive queries (watch)

When watching a query, updates will be batched and emitted at most once per interval. This prevents overwhelming the UI with high-frequency updates. Events are deduplicated by document ID, keeping only the latest state.

Examples

use std::time::Duration;

// Rate-limit to max 10 updates per second
let mut watcher = db.query("logs")
    .filter(|f| f.eq("level", "ERROR"))
    .debounce(Duration::from_millis(100))
    .watch()
    .await?;

pub async fn collect(self) -> Result<Vec<Document>>

Execute the query and collect the results

Returns

A vector of documents matching the query criteria

Examples

let results = db.query(“products”) .filter(|f| f.lt(“price”, 100)) .collect() .await?;

pub async fn watch(self) -> Result<QueryWatcher>

where 'a: 'static,

Watch the query for real-time updates

Returns a QueryWatcher that streams live updates when documents are added, removed, or modified in ways that affect the query results. Perfect for building reactive UIs, live dashboards, and real-time applications.

Performance

• Zero overhead for queries without watchers
• Updates delivered asynchronously via channels
• Automatic filtering - only matching changes are emitted
• Memory efficient - only tracks matching documents

Requirements

This method requires the QueryBuilder to have a ’static lifetime, which means the database reference must also be ’static (e.g., Arc).

Examples

use aurora_db::{Aurora, types::Value};
use std::sync::Arc;

let db = Arc::new(Aurora::open("mydb.db")?);

// Basic reactive query - watch active users
let mut watcher = db.query("users")
    .filter(|f| f.eq("active", Value::Bool(true)))
    .watch()
    .await?;

// Receive updates in real-time
while let Some(update) = watcher.next().await {
    match update {
        QueryUpdate::Added(doc) => {
            println!("New active user: {}", doc.id);
        },
        QueryUpdate::Removed(doc) => {
            println!("User deactivated: {}", doc.id);
        },
        QueryUpdate::Modified { old, new } => {
            println!("User updated: {} -> {}", old.id, new.id);
        },
    }
}

Real-World Use Cases

Live Leaderboard:

// Watch top players by score
let mut leaderboard = db.query("players")
    .filter(|f| f.gte("score", Value::Int(1000)))
    .watch()
    .await?;

tokio::spawn(async move {
    while let Some(update) = leaderboard.next().await {
        // Update UI with new rankings
        broadcast_to_clients(&update).await;
    }
});

Activity Feed:

// Watch recent posts for a user's feed
let mut feed = db.query("posts")
    .filter(|f| f.eq("author_id", user_id))
    .watch()
    .await?;

// Stream updates to WebSocket
while let Some(update) = feed.next().await {
    match update {
        QueryUpdate::Added(post) => {
            websocket.send(json!({"type": "new_post", "post": post})).await?;
        },
        _ => {}
    }
}

Real-Time Dashboard:

// Watch critical metrics
let mut alerts = db.query("metrics")
    .filter(|f| f.gt("cpu_usage", Value::Float(80.0)))
    .watch()
    .await?;

tokio::spawn(async move {
    while let Some(update) = alerts.next().await {
        if let QueryUpdate::Added(metric) = update {
            // Alert on high CPU usage
            send_alert(format!("High CPU: {:?}", metric)).await;
        }
    }
});

Collaborative Editing:

// Watch document for changes from other users
let doc_id = "doc-123";
let mut changes = db.query("documents")
    .filter(|f| f.eq("id", doc_id))
    .watch()
    .await?;

tokio::spawn(async move {
    while let Some(update) = changes.next().await {
        if let QueryUpdate::Modified { old, new } = update {
            // Merge changes from other editors
            apply_remote_changes(&old, &new).await;
        }
    }
});

Stock Ticker:

// Watch price changes
let mut price_watcher = db.query("stocks")
    .filter(|f| f.eq("symbol", "AAPL"))
    .watch()
    .await?;

while let Some(update) = price_watcher.next().await {
    if let QueryUpdate::Modified { old, new } = update {
        if let (Some(old_price), Some(new_price)) =
            (old.data.get("price"), new.data.get("price")) {
            println!("AAPL: {} -> {}", old_price, new_price);
        }
    }
}

Multiple Watchers Pattern

// Watch multiple queries concurrently
let mut high_priority = db.query("tasks")
    .filter(|f| f.eq("priority", Value::String("high".into())))
    .watch()
    .await?;

let mut urgent = db.query("tasks")
    .filter(|f| f.eq("status", Value::String("urgent".into())))
    .watch()
    .await?;

tokio::spawn(async move {
    loop {
        tokio::select! {
            Some(update) = high_priority.next() => {
                println!("High priority: {:?}", update);
            },
            Some(update) = urgent.next() => {
                println!("Urgent: {:?}", update);
            },
        }
    }
});

Important Notes

• Requires Arc for ’static lifetime
• Updates are delivered asynchronously
• Watcher keeps running until dropped
• Only matching documents trigger updates
• Use tokio::spawn to process updates in background

See Also

• Aurora::listen() for collection-level change notifications
• QueryWatcher::next() to receive the next update
• QueryWatcher::try_next() for non-blocking checks

pub async fn first_one(self) -> Result<Option<Document>>

Get only the first matching document or None if no matches

Examples

let user = db.query(“users”) .filter(|f| f.eq(“email”, “jane@example.com”)) .first_one() .await?;

pub async fn count(self) -> Result<usize>

Count the number of documents matching the query

Examples

let active_count = db.query(“users”) .filter(|f| f.eq(“status”, “active”)) .count() .await?;

pub async fn update(self, updates: HashMap<&str, Value>) -> Result<usize>

Update documents matching the query with new field values

Returns

The number of documents updated

Examples

let updated = db.query(“products”) .filter(|f| f.lt(“stock”, 5)) .update([ (“status”, Value::String(“low_stock”.to_string())), (“needs_reorder”, Value::Bool(true)) ].into_iter().collect()) .await?;

pub async fn delete(self) -> Result<usize>

Delete documents matching the query

Returns

The number of documents deleted

Examples

let deleted = db.query("users")
    .filter(|f| f.eq("active", false))
    .delete()
    .await?;

Delete documents matching the query

Returns

The number of documents deleted

Note

Deletions are not atomic. If an error occurs during deletion, some documents may have been deleted while others remain. For atomic batch operations, consider using transactions.

Examples

// Delete all inactive users
let deleted = db.query("users")
    .filter(|f| f.eq("status", "inactive"))
    .delete()
    .await?;
println!("Deleted {} users", deleted);