Query API Reference

Detailed reference for the query-related APIs

Query API Reference

The Query API provides a flexible way to search for memories based on multiple criteria. This document provides a detailed reference for the query-related APIs in EngramDB.

QueryBuilder

The QueryBuilder class provides a fluent interface for building complex queries.

Creating a Query

QueryBuilder::new()

Creates a new query builder.

Returns:

• A new QueryBuilder instance

Example:

let query = QueryBuilder::new();

Query Criteria

with_vector(query_vector)

Sets the query vector for similarity search.

Parameters:

• query_vector: Vec<f32> - The query vector

Returns:

• Self - The query builder for method chaining

Example:

let query = QueryBuilder::new()
    .with_vector(vec![0.1, 0.2, 0.3, 0.4]);

with_similarity_threshold(threshold)

Sets the minimum similarity threshold for vector search.

Parameters:

• threshold: f32 - Minimum similarity threshold (0.0 to 1.0)

Returns:

• Self - The query builder for method chaining

Example:

let query = QueryBuilder::new()
    .with_vector(vec![0.1, 0.2, 0.3, 0.4])
    .with_similarity_threshold(0.7);

with_attribute_filter(filter)

Adds an attribute filter to the query.

Parameters:

• filter: AttributeFilter - The attribute filter to add

Returns:

• Self - The query builder for method chaining

Example:

let category_filter = AttributeFilter::equals("category", "work");
let importance_filter = AttributeFilter::greater_than("importance", 0.7);

let query = QueryBuilder::new()
    .with_attribute_filter(category_filter)
    .with_attribute_filter(importance_filter);

with_temporal_filter(filter)

Adds a temporal filter to the query.

Parameters:

• filter: TemporalFilter - The temporal filter to add

Returns:

• Self - The query builder for method chaining

Example:

let time_filter = TemporalFilter::within_last(24 * 60 * 60); // Last 24 hours

let query = QueryBuilder::new()
    .with_temporal_filter(time_filter);

with_limit(limit)

Sets the maximum number of results to return.

Parameters:

• limit: usize - Maximum number of results

Returns:

• Self - The query builder for method chaining

Example:

let query = QueryBuilder::new()
    .with_limit(10);

with_exclude_ids(ids)

Adds IDs to exclude from the results.

Parameters:

• ids: Vec<Uuid> - IDs to exclude

Returns:

• Self - The query builder for method chaining

Example:

let query = QueryBuilder::new()
    .with_exclude_ids(vec![id1, id2, id3]);

Executing the Query

execute(vector_index, memory_nodes)

Executes the query against a vector index and a set of memory nodes.

Parameters:

• vector_index: &VectorIndex - The vector index to search
• memory_nodes: F - A function that can retrieve memory nodes by ID

Returns:

• Result<Vec<MemoryNode>> - A vector of memory nodes matching the query, sorted by relevance

Example:

// Using the Database's query method (recommended)
let results = db.query()
    .with_vector(query_vector)
    .with_attribute_filter(category_filter)
    .execute()?;

// Manual execution (advanced)
let results = query.execute(&vector_index, |id| storage.load(id))?;

AttributeFilter

The AttributeFilter class provides methods for filtering memories based on their attributes.

Creating Filters

AttributeFilter::equals(key, value)

Creates a filter that matches attributes equal to the specified value.

Parameters:

• key: &str - The attribute key
• value: AttributeValue - The value to compare against

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::equals("category", AttributeValue::String("work".to_string()));

AttributeFilter::not_equals(key, value)

Creates a filter that matches attributes not equal to the specified value.

Parameters:

• key: &str - The attribute key
• value: AttributeValue - The value to compare against

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::not_equals("category", AttributeValue::String("personal".to_string()));

AttributeFilter::greater_than(key, value)

Creates a filter that matches numeric attributes greater than the specified value.

Parameters:

• key: &str - The attribute key
• value: AttributeValue - The value to compare against (must be numeric)

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::greater_than("importance", AttributeValue::Float(0.7));

AttributeFilter::less_than(key, value)

Creates a filter that matches numeric attributes less than the specified value.

Parameters:

• key: &str - The attribute key
• value: AttributeValue - The value to compare against (must be numeric)

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::less_than("priority", AttributeValue::Integer(3));

AttributeFilter::contains(key, substring)

Creates a filter that matches string attributes containing the specified substring.

Parameters:

• key: &str - The attribute key
• substring: &str - The substring to search for

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::contains("title", "meeting");

AttributeFilter::exists(key)

Creates a filter that matches memories where the specified attribute exists.

Parameters:

• key: &str - The attribute key

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::exists("category");

AttributeFilter::not_exists(key)

Creates a filter that matches memories where the specified attribute does not exist.

Parameters:

• key: &str - The attribute key

Returns:

• A new AttributeFilter instance

Example:

let filter = AttributeFilter::not_exists("category");

TemporalFilter

The TemporalFilter class provides methods for filtering memories based on their temporal properties.

Creating Filters

TemporalFilter::before(timestamp)

Creates a filter that matches memories created before the specified timestamp.

Parameters:

• timestamp: u64 - The Unix timestamp

Returns:

• A new TemporalFilter instance

Example:

let filter = TemporalFilter::before(1609459200); // Before January 1, 2021

TemporalFilter::after(timestamp)

Creates a filter that matches memories created after the specified timestamp.

Parameters:

• timestamp: u64 - The Unix timestamp

Returns:

• A new TemporalFilter instance

Example:

let filter = TemporalFilter::after(1609459200); // After January 1, 2021

TemporalFilter::between(start_timestamp, end_timestamp)

Creates a filter that matches memories created between the specified timestamps.

Parameters:

• start_timestamp: u64 - The start Unix timestamp
• end_timestamp: u64 - The end Unix timestamp

Returns:

• A new TemporalFilter instance

Example:

let filter = TemporalFilter::between(1609459200, 1640995200); // Between Jan 1, 2021 and Jan 1, 2022

TemporalFilter::within_last(seconds)

Creates a filter that matches memories created within the last specified number of seconds.

Parameters:

• seconds: u64 - Number of seconds

Returns:

• A new TemporalFilter instance

Example:

let filter = TemporalFilter::within_last(24 * 60 * 60); // Within the last 24 hours

Combined Query Example

Here’s an example of a complex query that combines multiple criteria:

// Create filters
let category_filter = AttributeFilter::equals(
    "category",
    AttributeValue::String("work".to_string())
);

let importance_filter = AttributeFilter::greater_than(
    "importance",
    AttributeValue::Float(0.7)
);

let time_filter = TemporalFilter::within_last(7 * 24 * 60 * 60); // Last week

// Build and execute query
let results = db.query()
    .with_vector(vec![0.1, 0.2, 0.3, 0.4])
    .with_similarity_threshold(0.6)
    .with_attribute_filter(category_filter)
    .with_attribute_filter(importance_filter)
    .with_temporal_filter(time_filter)
    .with_limit(10)
    .execute()?;

// Process results
for memory in results {
    println!("Found memory: {:?}", memory);
}