Mango Query (Rust)
A Rust implementation of the CouchDB Mango Query specification using the Builder pattern and Serde.
This library serves as:
- A query filter serializer for use in REST and GraphQL APIs.
- A query translation layer between Mango queries and other database schemas (e.g. Mango -> SQL, Mango -> DynamoDB).
- An in-memory query filter for data collections with custom pagination/sorting capabilities.
Installation
Add this to your Cargo.toml:
[]
= { = "0.1.0", = ["dynamodb"] } # Enable "dynamodb" feature if using DynamoDB compiler
= { = "1.0", = ["derive"] }
= "1.0"
Usage Example
Basic Selector & Options
Using MangoQueryBuilder to build CouchDB-compatible Mango query representations.
use MangoQueryBuilder;
use json;
Output:
Nesting & Logical Combinators
use MangoQueryBuilder;
use json;
Output:
Database Flavours (Query Compilation)
Translate your Mango queries into database-specific filter formats.
1. DynamoDB Flavour
[!NOTE] Requires the
dynamodbfeature flag to be enabled.
Compiles queries to AWS SDK-compliant expressions. Output fields (filter_expression, expression_attribute_names, and expression_attribute_values) are wrapped in Option, returning None if they are empty. It also includes the key_condition string field, index_name: Option<String> (representing the index resolved from the query's use_index property), exclusive_start_key: Option<HashMap<String, AttributeValue>> (resolved and parsed from the query's base64-encoded bookmark property), and limit: Option<i32> (representing the query's execution limit).
You can pass an optional DynamoDBConfig to the compiler containing:
key_condition: An initial key condition string.attribute_names: Initial attribute name placeholders.attribute_values: Initial attribute value placeholders as aHashMap<String, AttributeValue>.
The compiler will automatically merge the configuration's names and values with the placeholders generated during query compilation.
use AttributeValue;
use ;
use json;
use HashMap;
2. PostgreSQL Flavour
Compiles queries to parameterized where_clause strings, parameter values, and dynamic JOIN statements. Dot notation paths translate to JSONB query extractors (e.g., column->>'field') automatically.
use ;
use json;
use HashMap;
In-Memory Collection Filtering
Filter, sort, and project local arrays of items using a strictly typed MangoQuery with pagination bookmarks and limit boundaries.
use ;
use json;
API Reference
MangoQueryBuilder Selector Options
.r#where(field, value): Add field condition (e.g. implicit equality{ name: "Juan" })..where_op(field, operator, value): Add field condition operator (e.g..where_op("age", "$gte", json!(18)))..and(selectors): Combine selectors using logical$and..or(selectors): Combine selectors using logical$or..nor(selectors): Combine selectors using logical$nor..not(selector): Invert condition using logical$not..text(query): Add full text search index expression.
MangoQueryBuilder Parameters
.fields(fields_vec): Fields to include in final projected documents..sort(sort_rules_vec): Specify a full sort structure..sort_field(field, direction): Add a single field to sort by fluently (e.g., direction isSome("desc")orNone)..limit(limit_val): Limit the result set size..skip(skip_val): Skip the first N documents..use_index(use_index_val): Hint CouchDB to use a specific index..allow_fallback(boolean): Controls index selection fallback..conflicts(boolean): Include document conflict information..r(quorum): Set replica read quorum..bookmark(string): Pagination resume token..update(boolean): Force updating index before execution..stable(boolean): Return results from a stable set of shards..execution_stats(boolean): Include execution statistics in response metadata.
Supported Operators
| Operator | Description | Supported Types |
|---|---|---|
$eq |
Equal to | String, Number, Boolean, Null |
$ne |
Not equal to | String, Number, Boolean, Null |
$gt |
Greater than | Number, String |
$gte |
Greater than or equal to | Number, String |
$lt |
Less than | Number, String |
$lte |
Less than or equal to | Number, String |
$in |
Exists in array | Array |
$nin |
Does not exist in array | Array |
$exists |
Check field existence | Boolean |
$type |
Check field JSON type | String ("null", "boolean", "number", "string", "array", "object") |
$size |
Array size matching | Integer |
$mod |
Divisor & remainder matching | [Divisor, Remainder] |
$regex |
Regex matching (via regex crate) | String |
$beginsWith |
Prefix case-sensitive matching | String |