Zero-dependency C99 core engine for Mongo-style in-memory query matching and rule evaluation using arena memory pools — powering native language bindings and cross-checked against mongory-spec.
Interactive Playground & Visual Debugger ↗ ·
mongory-rb(Ruby) ·mongory-go(Go) ·mongory-js(TypeScript/JS) ·mongory-spec
- MongoDB-like Queries: Use familiar operators like
$eq,$gt,$lt,$in,$and,$or, etc., to build complex queries. - Memory Pool: All memory is managed through a simple memory pool, making resource management straightforward and helping to prevent memory leaks.
- Generic Data Types: Data is represented using a generic
mongory_valuetype, which can encapsulate integers, doubles, strings, arrays, and tables (hash maps). - Extensible: Provides interfaces to define your own custom value converters and regex engines, allowing
mongory-coreto work seamlessly with your existing data structures. - Well-Documented: The public API is thoroughly documented with Doxygen-style comments in the header files.
Here is a simple example of how to use mongory-core to match a document against a query.
First, let's define a C data structure we want to query. Imagine we have a "document" representing a user:
// Document to be queried
// {
// "name": "Jules",
// "language": "C",
// "year": 2024
// }And we want to see if it matches the following query:
// Query
// {
// "language": "C",
// "year": { "$gt": 2020 }
// }Here's the C code to perform this match using mongory-core:
#include <stdio.h>
#include <mongory-core.h>
int main() {
// 1. Initialize the Mongory library
mongory_init();
// 2. Create a memory pool for all allocations
mongory_memory_pool *pool = mongory_memory_pool_new();
// 3. Create the document to be queried as a mongory_table
mongory_value *doc = MG_TABLE_WRAP(pool, 3,
"name", mongory_value_wrap_s(pool, "Jules"),
"language", mongory_value_wrap_s(pool, "C"),
"year", mongory_value_wrap_i(pool, 2024)
);
// 4. Create the query condition
// { "language": "C", "year": { "$gt": 2020 } }
mongory_value *query = MG_TABLE_WRAP(pool, 2,
"language", mongory_value_wrap_s(pool, "C"),
"year", MG_TABLE_WRAP(pool, 1,
"$gt", mongory_value_wrap_i(pool, 2020)
)
);
// 5. Create a matcher with the query condition
mongory_matcher *matcher = mongory_matcher_new(pool, query, NULL);
// 6. Perform the match
bool is_match = mongory_matcher_match(matcher, doc);
// 7. Print the result
if (is_match) {
printf("The document matches the query!\\n");
} else {
printf("The document does not match the query.\\n");
}
// 8. Clean up
pool->free(pool);
mongory_cleanup();
return 0;
}(Note: For a runnable version of this example, see benchmarks/basic_test.c)
mongory-core provides both structured tree APIs (returning mongory_value * Table/Array trees allocated in your arena pool) and stdout helpers that print those trees:
// Structured explain tree:
// { "name", "condition", "priority", "children", ["field"] }
mongory_value *explain_node = mongory_matcher_explain_tree(matcher, pool);
// Print explain tree to stdout
mongory_matcher_explain(matcher, pool);
// Structured trace tree:
// { "name", "condition", "priority", "result": "pass"|"fail"|"skip", "children", ["field"], ["record"] }
// Short-circuited branches are recursively expanded with "result": "skip".
mongory_value *trace_node = mongory_matcher_trace_tree(matcher, doc);
// Print trace tree to stdout and return bool match result
bool matched = mongory_matcher_trace(matcher, doc);This project uses CMake for cross-platform building and testing, with a convenient build script for easy usage.
- Core library (
libmongory-core.a): Zero external runtime dependencies — only a C99 compiler (gcc/clang) andCMake(>= 3.12) (-DBUILD_TESTS=OFF -DBUILD_BENCHMARKS=OFF). - Unit tests & benchmarks: Require
cJSON(libcjson-devon Ubuntu/Debian,cjsonon macOS) and the Unity test framework (./build.sh --setup-unity). - Cross-language
mongory-specconformance tests: Additionally requirelibpcre2-8(libpcre2-devon Ubuntu/Debian,pcre2on macOS) and-DMONGORY_SPEC_DIR=/path/to/mongory-spec.
macOS (Homebrew):
# Library only
brew install cmake
# Full tests + mongory-spec conformance
brew install cmake cjson pcre2Ubuntu/Debian:
# Library only
sudo apt update && sudo apt install -y cmake build-essential
# Full tests + mongory-spec conformance
sudo apt update && sudo apt install -y cmake build-essential libcjson-dev libpcre2-dev pkg-configCentOS/RHEL/Fedora:
# CentOS/RHEL
sudo yum install cmake cjson-devel pcre2-devel gcc
# Fedora
sudo dnf install cmake cjson-devel pcre2-devel gccUse the provided build script for the easiest experience:
# Basic build
./build.sh
# First-time setup for Unity test framework and run unit tests
./build.sh --setup-unity --test
# Run unit tests + mongory-spec conformance
./build.sh --setup-unity
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_BENCHMARKS=OFF -DMONGORY_SPEC_DIR=../mongory-spec
cmake --build build
ctest --test-dir build --output-on-failure# 1. Setup Unity test framework (first time only)
./build.sh --setup-unity
# 2. Create build directory
mkdir build && cd build
# 3. Configure project
cmake ..
# 4. Build
cmake --build .
# 5. Run tests
ctest
# 6. Install (optional)
sudo cmake --install .# Release build (optimized)
cmake -DCMAKE_BUILD_TYPE=Release ..
# Debug build (with debug symbols)
cmake -DCMAKE_BUILD_TYPE=Debug ..
# Disable tests or benchmarks
cmake -DBUILD_TESTS=OFF -DBUILD_BENCHMARKS=OFF ..The project uses clang-format for code formatting:
cmake --build build --target format
# or
./build.sh && cmake --build build --target formatThe original Makefile is still available but deprecated. For cross-platform compatibility, please use the CMake build system.
📝 Migration Note: This project was migrated from Makefile to CMake for better cross-platform support. See
CMAKE_USAGE.mdfor detailed CMake usage instructions.
The public API is documented in the header files in the include/ directory. The comments are compatible with Doxygen. You can generate HTML documentation if you have Doxygen installed.
See docs/performance.md and scripts/bench.sh for C99 benchmark results.