s3vectors-metadata-filter

A flexible and efficient Rust library for filtering data using S3 Vectors Metadata Filter syntax.

Features

• S3 Vectors Metadata Filter Syntax: Support all JSON-based filtering operators.
• (Optional) SQL like expression to JSON document: Human friendly SQL expression to JSON document conversion.
• (Optional) JSON string to Smithy document: JSON string to Smithy document conversion helper function to simplify integration with Rust code.

Quick Start

use s3vectors_metadata_filter::{Filter, FilterValue, context};

// Create a filter from JSON
let filter = Filter::from_json(r#"{"age": {"$gte": 18}}"#).unwrap();

// Build a data context
let data = context! {
    "age" => FilterValue::number(25.0),
    "name" => FilterValue::string("Alice")
};

// Evaluate the filter
assert!(filter.evaluate(&data).unwrap());

Usage Examples

Basic Comparison

use s3vectors_metadata_filter::{Filter, FilterValue, context};

let filter = Filter::from_json(r#"{"status": {"$eq": "active"}}"#).unwrap();
let data = context! {
    "status" => FilterValue::string("active")
};
assert!(filter.evaluate(&data).unwrap());

Implicit Equality

use s3vectors_metadata_filter::{Filter, FilterValue, context};

// Shorthand syntax without $eq
let filter = Filter::from_json(r#"{"genre": "documentary"}"#).unwrap();
let data = context! {
    "genre" => FilterValue::string("documentary")
};
assert!(filter.evaluate(&data).unwrap());

Numeric Comparisons

use s3vectors_metadata_filter::{Filter, FilterValue, context};

let filter = Filter::from_json(r#"{"score": {"$gt": 90}}"#).unwrap();
let data = context! {
    "score" => FilterValue::number(95.0)
};
assert!(filter.evaluate(&data).unwrap());

Array Membership

use s3vectors_metadata_filter::{Filter, FilterValue, context};

let filter = Filter::from_json(r#"{"category": {"$in": ["premium", "gold"]}}"#).unwrap();
let data = context! {
    "category" => FilterValue::string("premium")
};
assert!(filter.evaluate(&data).unwrap());

Array Contains

use s3vectors_metadata_filter::{Filter, FilterValue, context};

// Check if array field contains a value
let filter = Filter::from_json(r#"{"tags": {"$eq": "rust"}}"#).unwrap();
let data = context! {
    "tags" => FilterValue::array(vec![
        FilterValue::string("rust"),
        FilterValue::string("programming")
    ])
};
assert!(filter.evaluate(&data).unwrap());

Complex Queries

use s3vectors_metadata_filter::{Filter, FilterValue, context};

let filter = Filter::from_json(r#"
{
    "$and": [
        {"age": {"$gte": 18}},
        {"$or": [
            {"category": {"$in": ["premium", "gold"]}},
            {"score": {"$gt": 95}}
        ]},
        {"email": {"$exists": true}},
        {"status": {"$ne": "banned"}}
    ]
}"#).unwrap();

let data = context! {
    "age" => FilterValue::number(25.0),
    "category" => FilterValue::string("premium"),
    "score" => FilterValue::number(88.0),
    "email" => FilterValue::string("user@example.com"),
    "status" => FilterValue::string("active")
};

assert!(filter.evaluate(&data).unwrap());

SQL-like Syntax (Optional Feature)

Enable the sql-like feature to parse SQL WHERE clause expressions:

use s3vectors_metadata_filter::parse_sql_like_expr;

// Parse SQL-like expression to JSON filter
let json = parse_sql_like_expr("age >= 18 AND status = 'active'").unwrap();

// Output: {"$and":[{"age":{"$gte":18}},{"status":{"$eq":"active"}}]}
println!("{}", json);

Supported SQL-like syntax:

• Comparison operators: =, !=, >, >=, <, <=
• Logical operators: AND, OR
• Membership: IN (...), NOT IN (...)
• Existence: IS NULL, IS NOT NULL
• Range: BETWEEN ... AND ...

JSON string to Smithy Document (Optional Feature)

Enable the smithy-doc feature to parse JSON string and convert to aws_smithy_types::Document in Rust code:

use s3vectors_metadata_filter::json_str_to_smithy_doc;

// Convert JSON string to aws_smithy_types::Document
let doc = json_str_to_smithy_doc(r#"{"genre": {"$eq": "documentary"}}"#).unwrap();

// Output: Object({"genre": Object({"$eq": String("documentary")})})
println!("{:?}", doc);

About Code

Code in lib.rs is Kiro-authored and the rest code is Human-authored.

License

This project is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.