For AI agents: the complete documentation index is available at https://silt-db.dev/llms.txt, the full documentation bundle is available at https://silt-db.dev/llms-full.txt, and this page is available as Markdown at https://silt-db.dev/reference/compatibility.md.

    Compatibility contract

    Silt is a MongoDB-shaped JSON document database implemented over SQLite, currently an alpha. It is not wire-compatible with MongoDB, a complete MongoDB server, a fully compatible BSON store, or a complete implementation of every Mingo operator. Unsupported syntax normally throws SILT_UNSUPPORTED or SILT_VALIDATION; document-dependent invalid values abort execution in SQLite. There is no JavaScript query fallback.

    MongoDB semantics are the target; the initial research examined MongoDB 8.3.8. Executable conformance evidence in the captured validation run is against MongoDB 8.0.29. See test methodology and actual results.

    Data and API

    AreaCurrent behavior
    Stored valuesPlain JSON objects containing finite numbers, strings, booleans, null, arrays and nested plain objects. Missing fields remain distinguishable from explicit null.
    Numeric precisionOriginal JSON tokens are preserved when copying values. Computed values depend on SQLite; the tested Expo 3.50.3 has proven extreme-double parser/formatter defects. See Numeric precision.
    BSONDate, ObjectId, Decimal128, Binary, BSON RegExp, Timestamp, MinKey/MaxKey and numeric subtype identity are not implemented. Unsupported JavaScript/BSON values fail validation. Converting a Date to a string first changes its semantics; it does not create BSON date support.
    IDsPersistent unique _id; generated UUID string when absent. Scalar and valid embedded-object IDs supported, arrays rejected. String IDs use indexed key probes; non-string IDs use SQL semantic uniqueness checks and conservative reads to avoid cross-engine key-spelling mismatches. Engine numeric limits still apply. This is not MongoDB's ObjectId generation.
    Collection APIPortable async openDatabase and asynchronous cursors over Node, better-sqlite3 or Expo drivers; synchronous SQLiteDatabase remains a Node option. Initialization differs from Mingo's in-memory array API.
    StreamingCursor iteration decodes returned rows lazily; .toArray()/.all() collects the result by request. No permanent JS document or op cache.
    PersistenceOwned server files default to WAL/full synchronous mode, page-cache configuration, version checks, transactions and reopen tests. Borrowed connections retain caller configuration. Actual Expo browser persistence uses its OPFS implementation and DELETE journal mode. SQLite may use its own memory/temp storage during complex execution.
    Batch writesinsertMany and updateMany are atomic across the Silt operation; MongoDB's ordinary batches can retain earlier successful writes.
    IndexesPersistent nonunique compound and multikey SQL-maintained indexes; eligible equality/range filters and lookup keys use index candidates plus exact SQL residuals. Unique secondary, text, geo, TTL, sparse and partial indexes are not implemented.
    OptionsOnly explicitly supported options are accepted. Locale collation, sessions, read/write concern, hints in the core API, Mongo error codes and exact server limits are not emulated. The ShareDB adapter retains its documented query-control conventions.

    Queries

    FamilySupported names and restrictions
    Comparison$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin; numeric/boolean separation, ordered embedded-object identity, nested arrays and type-bracketed ranges.
    Logical$and, $or, $nor, field $not; aggregation $expr predicates.
    Presence/type$exists; $type for number, string, object, array, bool, null and corresponding supported type codes. BSON int/long/double subtype tests are rejected.
    Arrays$all, $elemMatch, $size; multikey dotted traversal, indexed paths and Mongo-specific nested-array behavior. Query paths, expression paths, update paths and join keys use separate semantics.
    NumericInteger $mod; bit masks/positions within the documented representable range via $bitsAllSet, $bitsAllClear, $bitsAnySet, $bitsAnyClear. Arbitrary precision/binary bit fields are not supported.
    Regex by defaultLiterals, branch anchors, alternatives, dot, explicit/negated character classes, *, +, ? and flags m/s/u, compiled to stock SQLite. Captures, shorthand classes, lookaround, case-insensitive flags and unlisted syntax require the optional native mode; see the regex reference. JavaScript RegExp objects are not stored as BSON regex.
    Optional native regex$regex/$options with PCRE2 matching inside SQLite. Flags i, m, s, x, u, Unicode and PCRE syntax are tested. See native build and limits.
    Rejected families$where, $jsonSchema, geospatial/text/server-dependent predicates and unlisted operators.

    Field order matters for embedded-object equality. Missing/null matches and array traversal follow measured Mongo cases, including behaviors where Mingo differs. A SQL comparison helper has a captured 900-pair real-Mongo ordering corpus. That is substantial evidence, not an exhaustive proof over all JSON trees.

    Aggregation

    20 stage names and 18 accumulator names are implemented. See the detailed aggregation matrix for operand restrictions and costs.

    StatusFeatures
    Implemented stages$match, $project, $set, $addFields, $unset, $replaceRoot, $replaceWith, $sort, $skip, $limit, $count, $unwind, $group, $sortByCount, $lookup, $facet, $unionWith, $documents, $sample, $bucket
    Implemented accumulators$count, $sum, $avg, $min, $max, $push, $addToSet, $first, $last, $firstN, $lastN, $minN, $maxN, $top, $bottom, $topN, $bottomN, $mergeObjects
    Lookup formsEquality, pipeline with let/$expr, equality followed by pipeline, nested lookup, literal $documents sources, array keys and per-parent sort/limit.
    Important restrictionsLiteral positive n for N group accumulators; only homogeneous number/string $bucket boundaries; literal $documents; multiple multikey sort paths conservatively rejected; server byte/resource limits not reproduced.
    Unimplemented$setWindowFields, $graphLookup, $redact, $bucketAuto, $densify, $fill, $out, $merge, geospatial/Atlas/server metadata stages, statistical/percentile/window accumulators.

    Arrays/objects can be ordered accurately in SQL, but some paths use O(n²) ranking. Eligible equality and correlated-equality lookups use indexed probes. Other correlated lookups can scan the foreign relation once per local row. These are current performance limitations, not JS fallback behavior.

    Expressions and updates

    Expression documentation lists arithmetic, trigonometry, conditionals, scoped variables, array/map/filter/reduce, sets, objects, strings, conversion and optional native regex operators. Conversion targets and ranges are explicit. Numeric $type is rejected because JSON does not preserve BSON subtype metadata. Long conversion is restricted to safe JS integers. Date/timezone and Decimal128 semantics remain absent. Some operations involving embedded NUL strings deliberately reject inputs; other documented NUL-related limits remain.

    Update documentation covers $set, $unset, $inc, $mul, $min, $max, $rename, $setOnInsert, $push, $addToSet, $pop, $pull, $pullAll, $bit, update pipelines, numeric array paths and $[]/$[identifier] filters. Legacy positional $, $currentDate, and potentially overlapping positional paths are rejected. The narrow Mongo modifiedCount difference for removing/restoring _id in an update pipeline is documented.

    ShareDB

    The persistent adapter passes ShareDB's official DB harness, with additional integration cases for reopen persistence, atomic op/snapshot commits, tombstones, metadata, casing and live foreign lookup dependencies. See adapter documentation.

    It preserves sharedb-mingo-memory's high-level query conventions, including $aggregate results in query extra. ShareDB itself applies OT and projections to fetched snapshots. Multiple backend processes need shared PubSub to distribute live notifications. Those protocol behaviors are distinct from SQL document selection/aggregation.

    Work toward broader compatibility

    1. Validate against newer MongoDB releases and capture changed semantics; the original test environment could not initialize MongoDB 8.3.8.
    2. Keep the initial contract pure JSON; extended BSON types are intentionally deferred.
    3. Expand proven optimizer rewrites and multikey bound combinations, with exact indexed/unindexed and Mongo differential tests; benchmark representative subscription workloads.
    4. Introduce a typed SQL IR and common-subexpression reuse to reduce expensive generated SQL and replace quadratic compound sorting where possible.
    5. Implement remaining window, graph, statistical and write stages, each with full Mongo oracle cases and explicit resource handling.
    6. Broaden applicable upstream fixture imports and match Mingo's measured coverage across the expanded feature surface. Current coverage figures and passing unsupported-rejection cases must not be presented as full operator parity.