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/expressions.md.

    Aggregation expressions

    Use expressions in projection fields, $set stages, group operands, or query $expr. Start with the aggregation guide for a complete example; this page is the operator reference.

    const rows = await db
  .collection('orders')
  .aggregate([
    {
      $project: {
        total: { $multiply: ['$price', '$quantity'] },
        customer: { $ifNull: ['$customerName', 'Guest'] },
      },
    },
  ])
  .toArray();

    Expression evaluation runs in generated SQLite SQL. JavaScript validates and compiles the expression tree; it does not evaluate expressions against documents. Every intermediate value is JSON text, with SQL NULL reserved for a missing field. Arrays, booleans, embedded object key order, and numeric equality are preserved through SQL JSON operations. Dotted aggregation paths traverse arrays and compile to SQL whose size grows linearly with path depth.

    This is a finite JSON compatibility profile, not a BSON implementation. Unsupported operators throw SILT_UNSUPPORTED; invalid runtime operands fail the SQLite statement. Error messages and MongoDB numeric error codes are not reproduced. Some supported operators intentionally reject values that need BSON metadata or produce NaN/infinity.

    FamilyImplemented expression operators
    Literals and scope$literal, $let, $$ROOT, $$CURRENT, $$REMOVE, user variables, dotted paths
    Boolean and comparison$and, $or, $not, $eq, $ne, $gt, $gte, $lt, $lte, $cmp
    Conditional$cond, $ifNull, $switch
    Arithmetic$add, $subtract, $multiply, $divide, $mod, $pow, $abs, $ceil, $floor, $round, $trunc, $sqrt, $exp, $ln, $log, $log10
    Trigonometry$sin, $cos, $tan, $asin, $acos, $atan, $atan2, $sinh, $cosh, $tanh, $asinh, $acosh, $atanh, $degreesToRadians, $radiansToDegrees
    Array transformation$map, $filter, $reduce, $range, $zip, $sortArray, $reverseArray, $concatArrays, $slice
    Array inspection$isArray, $size, $arrayElemAt, $first, $last, $firstN, $lastN, $minN, $maxN, $in, $indexOfArray
    Array/scalar accumulators$sum, $avg, $min, $max (distinct from pipeline $group accumulators)
    Sets$setUnion, $setIntersection, $setDifference, $setEquals, $setIsSubset, $allElementsTrue, $anyElementTrue
    Objects$objectToArray, $arrayToObject, $mergeObjects, $getField, $setField, $unsetField
    Strings$concat, $split, $toLower, $toUpper, $strLenCP, $strLenBytes, $substrCP, $substrBytes, $substr, $indexOfCP, $indexOfBytes, $strcasecmp, $trim, $ltrim, $rtrim, $replaceOne, $replaceAll, $binarySize
    Types and conversion$type, $isNumber, $toBool, $toString, $toInt, $toLong, $toDouble, $convert
    Regular expressions$regexMatch with a constant pattern and options uses the portable SQL grammar. Dynamic patterns, $regexFind, and $regexFindAll require the optional native PCRE2 extension.

    Numeric conversions use a strict SQL lexical parser rather than SQLite's permissive cast semantics: whitespace, trailing junk, hex, and decimal/exponent syntax for integer targets are rejected. $convert supports literal bool, string, int, long, and double targets (and their BSON type codes), with lazy onNull and onError. Long conversion is restricted to the JavaScript safe-integer range. Decimal128, dates, ObjectId, binary BSON, numeric subtype identity, and dynamic conversion targets are not supported. $type on a number fails because JSON cannot recover its BSON numeric subtype.

    $round and $trunc use SQLite's extended decimal rendering of the binary64 value before decimal quantization. This avoids incorrect results from multiplying by a power of ten first. $substrBytes validates UTF-8 start and end boundaries in SQL. String case conversion follows SQLite's ASCII rules; MongoDB documents these operators as only well-defined for ASCII. Embedded NUL handling is explicitly rejected for trimming and code-point length; byte length and byte slicing retain NUL bytes. Some other SQLite text operations have additional embedded-NUL limitations; this is not full arbitrary BSON string conformance.

    $sortArray ranks each element with correlated comparisons, including embedded arrays/objects. This is quadratic in array length; it is intended for bounded document arrays. $min/$max expression selection also uses correlated comparisons. SQL is executed in SQLite, but complex generated expressions and large single-document arrays still consume SQLite memory and SQL planner resources. Collection streaming does not imply a fixed memory bound for every expression.

    Unsupported families include BSON/date expressions, bitwise numeric-subtype operators, custom JS functions/accumulators, and the newer optional parameters or operators not listed above. $replaceAll supports an empty search string using a recursive SQL walk over Unicode code points. Runtime finite-number and malformed-operand guards do not imply complete MongoDB error precedence parity.

    Validation evidence

    test/expression.test.js contains direct SQLite regressions, deterministic Mingo differential evaluations, invalid input tests, precision/conversion edge cases adjudicated against a real MongoDB 8.0.29 server, field-order tests, and a linear SQL generation check. The separately imported Mingo expression corpus contains 493 JSON cases and is adjudicated using captured MongoDB results; consult the generated audit for current compatible, rejected, and mismatched counts. The corpus is a subset of Mingo's full suite and does not establish MongoDB-wide equivalence.