madapes
Repositories
7
 Projects Packages

query_engine (0.1.7)

Published 2026-02-16 09:24:58 +00:00 by vlad

Installation

[registry]
default = "gitea"

[registries.gitea]
index = "sparse+" # Sparse index
# index = "" # Git

[net]
git-fetch-with-cli = true
cargo add query_engine@0.1.7

About this package

High-performance Rust query engine with UQF (Unified Query Format) support

Query Engine

A high-performance, embedded query engine for JSON documents, written in Rust. It utilizes the Unified Query Format (UQF)—a schema-agnostic, JSON-based AST—to provide fast, type-safe filtering, sorting, and pagination.

Key Features

  • 🚀 High Performance: Built with zero-copy parsing (serde), arena allocation (bumpalo), and data-parallel execution (rayon) for maximum throughput.
  • 🛡️ Type Safety: Strict type checking with configurable leniency, ensuring predictable query behavior.
  • 🔌 Embeddable: Core engine exposes a C-compatible FFI, making it easy to bind from any language.
  • 📦 Multi-Language Support: First-class bindings for Node.js (TypeScript) and Go.
  • 🔍 Rich Query Capabilities: Supports 20+ operators including logical ($and, $or), comparison ($gt, $lte), set ($in), string ($regex, $contains), and array ($elemMatch) operations.
  • ⚡ Resource Control: Built-in support for query timeout, scan limits, and recursion depth caps to prevent denial-of-service.

Installation

Rust

Add to your Cargo.toml:

[dependencies]
query_engine = { git = "https://git.madapes.com/madapes/query-engine" }

Node.js

npm install @madapes/query-engine

Go

go get github.com/madapes/query-engine-go

Quick Start

Rust Example

use query_engine::{Engine, Query, FilterNode, InMemorySource, Document};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize the engine
    let engine = Engine::new();

    // 2. Load some documents
    let source = InMemorySource::from_documents(vec![
        Document::new(json!({"id": 1, "status": "active", "age": 25})),
        Document::new(json!({"id": 2, "status": "inactive", "age": 30})),
        Document::new(json!({"id": 3, "status": "active", "age": 35})),
    ]);

    // 3. Build a query: status="active" AND age > 20
    let query = Query::new(FilterNode::and(vec![
        FilterNode::eq("status", json!("active")),
        FilterNode::gt("age", json!(20)),
    ])).with_limit(10);

    // 4. Execute
    let response = engine.find(&query, &source)?;
    println!("Found {} documents", response.count);

    Ok(())
}

Node.js Example

import { Engine, Documents, F, query } from '@madapes/query-engine';

const engine = new Engine();
const docs = new Documents();

docs.addMany([
  { id: 1, status: 'active', age: 25 },
  { id: 2, status: 'inactive', age: 30 },
]);

const result = engine.find(
  query()
    .filter(F.and(
      F.eq('status', 'active'),
      F.gt('age', 20)
    ))
    .build(),
  docs
);

console.log(`Found ${result.count} documents`);

Documentation

Comprehensive documentation is available in the Project Wiki:

Development

Requirements

  • Rust 1.85+ (2024 edition)
  • Node.js 20+ (for bindings)
  • Go 1.21+ (for bindings)

Build & Test

# Build core engine
cargo build --release

# Run all tests (Rust, Node.js, Go)
cargo test --all-features

Directory Structure

  • src/: Rust core implementation.
  • bindings/: Language bindings (Node.js, Go).
  • benches/: Performance benchmarks.
  • docs/wiki/: Documentation source (auto-published).
  • examples/: usage examples.
  • schemas/: UQF JSON schema.

License

MIT

Dependencies

ID Version
base64 ^0.22
jsonschema ^0.29
regex ^1.11
serde ^1.0
serde_json ^1.0
thiserror ^2.0
criterion ^0.5

Keywords

query json filter database
Details
Cargo
2026-02-16 09:24:58 +00:00
178
Mad Apes
Repository Site
MIT
78 KiB
Assets (1)
query_engine-0.1.7.crate 78 KiB
Versions (4) View all
0.1.7 2026-02-16
0.1.6 2026-02-15
0.1.5 2026-02-14
0.1.3 2026-02-14