Document Store: Query Language

Document Store: Query Language

Part of: HeliosDB Document Store User Guide

Query Language

Field Equality

Basic Equality:

// Find user named Alice
collection.find(doc! { "name": "Alice" }, None).await?;

// Find developer role
collection.find(doc! { "role": "developer" }, None).await?;

// Nested field
collection.find(doc! { "address.city": "San Francisco" }, None).await?;

HeliosDB Native:

use heliosdb_document::Filter;

let filter = Filter::eq("name", json!("Alice"));
let docs = store.find(&Collection::new("users"), filter)?;

Comparison Operators

$gt, $gte, $lt, $lte

// Greater than
collection.find(doc! { "age": { "$gt": 25 } }, None).await?;

// Greater than or equal
collection.find(doc! { "age": { "$gte": 25 } }, None).await?;

// Less than
collection.find(doc! { "age": { "$lt": 65 } }, None).await?;

// Less than or equal
collection.find(doc! { "age": { "$lte": 65 } }, None).await?;

// Range query
collection.find(doc! {
    "age": { "$gte": 25, "$lte": 65 }
}, None).await?;

HeliosDB Native:

let filter = Filter {
    op: FilterOp::Gt {
        field: "age".to_string(),
        value: json!(25),
    },
};

$ne (Not Equal)

// Not equal
collection.find(doc! { "status": { "$ne": "deleted" } }, None).await?;

Logical Operators

$and

// Multiple conditions (implicit AND)
collection.find(doc! {
    "role": "developer",
    "age": { "$gte": 25 }
}, None).await?;

// Explicit AND
collection.find(doc! {
    "$and": [
        { "role": "developer" },
        { "age": { "$gte": 25 } },
        { "status": "active" }
    ]
}, None).await?;

HeliosDB Native:

let filter = Filter::and(vec![
    Filter::eq("role", json!("developer")),
    Filter {
        op: FilterOp::Gte {
            field: "age".to_string(),
            value: json!(25),
        },
    },
    Filter::eq("status", json!("active")),
]);

$or

// Any condition matches
collection.find(doc! {
    "$or": [
        { "role": "developer" },
        { "role": "architect" },
        { "department": "Engineering" }
    ]
}, None).await?;

$not

// Negate condition
collection.find(doc! {
    "age": { "$not": { "$lt": 18 } }  // age NOT less than 18
}, None).await?;

$nor

// None of the conditions match
collection.find(doc! {
    "$nor": [
        { "status": "deleted" },
        { "archived": true }
    ]
}, None).await?;

Array Operators

$in

// Field value in array
collection.find(doc! {
    "role": { "$in": ["developer", "architect", "engineer"] }
}, None).await?;

HeliosDB Native:

let filter = Filter {
    op: FilterOp::In {
        field: "role".to_string(),
        values: vec![
            json!("developer"),
            json!("architect"),
            json!("engineer"),
        ],
    },
};

$nin (Not In)

// Field value not in array
collection.find(doc! {
    "status": { "$nin": ["deleted", "archived", "suspended"] }
}, None).await?;

$all

// Array contains all values
collection.find(doc! {
    "skills": { "$all": ["Rust", "MongoDB"] }
}, None).await?;

$elemMatch

// Array element matches multiple conditions
collection.find(doc! {
    "orders": {
        "$elemMatch": {
            "status": "shipped",
            "total": { "$gte": 100 }
        }
    }
}, None).await?;

$size

// Array has specific length
collection.find(doc! {
    "skills": { "$size": 3 }
}, None).await?;

Element Operators

$exists

// Field exists
collection.find(doc! {
    "email": { "$exists": true }
}, None).await?;

// Field does not exist
collection.find(doc! {
    "deleted_at": { "$exists": false }
}, None).await?;

HeliosDB Native:

let filter = Filter {
    op: FilterOp::Exists {
        field: "email".to_string(),
        exists: true,
    },
};

$type

// Field is specific BSON type
collection.find(doc! {
    "age": { "$type": "int" }
}, None).await?;

// Field is string
collection.find(doc! {
    "name": { "$type": "string" }
}, None).await?;

Nested Field Queries

// Dot notation for nested fields
collection.find(doc! {
    "address.city": "San Francisco",
    "address.state": "CA"
}, None).await?;

// Deep nesting
collection.find(doc! {
    "user.profile.preferences.theme": "dark"
}, None).await?;

// Array of nested documents
collection.find(doc! {
    "orders.0.total": { "$gte": 100 }  // First order total >= 100
}, None).await?;

Regular Expression Queries

$regex

// Case-insensitive pattern match
collection.find(doc! {
    "name": { "$regex": "^A", "$options": "i" }  // Starts with 'A' or 'a'
}, None).await?;

// Contains pattern
collection.find(doc! {
    "email": { "$regex": "@example\\.com$" }  // Ends with @example.com
}, None).await?;

// Multiple patterns
collection.find(doc! {
    "$or": [
        { "name": { "$regex": "Smith" } },
        { "name": { "$regex": "Johnson" } }
    ]
}, None).await?;

Common Regex Patterns:

// Email validation
doc! { "email": { "$regex": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$" } }

// Phone number (US)
doc! { "phone": { "$regex": "^\\d{3}-\\d{3}-\\d{4}$" } }

// URL
doc! { "website": { "$regex": "^https?://" } }

// Alphanumeric
doc! { "username": { "$regex": "^[a-zA-Z0-9_]+$" } }

Text Search

// Full-text search (requires text index)
collection.find(doc! {
    "$text": { "$search": "database rust programming" }
}, None).await?;

// Text search with score
let options = FindOptions::builder()
    .projection(doc! { "score": { "$meta": "textScore" } })
    .sort(doc! { "score": { "$meta": "textScore" } })
    .build();

collection.find(doc! {
    "$text": { "$search": "mongodb nosql" }
}, options).await?;

---

Navigation: ← Previous: CRUD Operations | Back to Index | Next: Indexing →