# Aggregation

`aggregate` runs MongoDB pipeline stages against the collection. Stages are
applied in order; each stage gets the documents emitted by the previous one.

## Pipeline stages

| Stage | Notes |
| --- | --- |
| `$match` | Same matcher as `find()`; can be lifted into the initial fetch's filter for index acceleration when it's the first stage |
| `$count` | Single-doc result with the named field |
| `$limit` / `$skip` | Standard semantics |
| `$sort` | Multi-field BSON cross-type sort; uses index acceleration for single-field sorts where possible |
| `$project` | Inclusion / exclusion / computed fields. `$elemMatch` projection supported |
| `$addFields` / `$set` | Add / overwrite fields (computed via expressions) |
| `$unset` | Remove paths (string or array) |
| `$unwind` | Path string or doc form (`preserveNullAndEmptyArrays`, `includeArrayIndex`) |
| `$densify` | Numeric ranges only (`bounds: "full"` / `[min, max]`, `partitionByFields`, positive `step`); date `unit` deferred |
| `$replaceRoot` / `$replaceWith` | Replace the root with a sub-document |
| `$group` | See accumulators below |
| `$lookup` | Both simple (`localField`/`foreignField`) and `let`/`pipeline` forms; uses an O(N+M) hash-join (foreign array values expanded element-wise) |
| `$sample` | `random.sample` — deterministic only if the test calls `random.seed(...)` first |
| `$sortByCount` | Equivalent to `$group` + `$sort` |
| `$facet` | Run multiple sub-pipelines in parallel |
| `$bucket` | `groupBy`, `boundaries`, `default`, `output` |
| `$merge` | `whenMatched`: `merge` (deep recursive merge), `replace`, `keepExisting`, `fail`. `whenNotMatched`: `insert`, `discard`, `fail`. `into` may be a string or `{db, coll}` |
| `$out` | Replace target collection with pipeline output |
| `$collStats` | Returns count + size metrics from the WT tables |
| `$graphLookup` | Recursive lookup with `maxDepth` |

### `$group` accumulators

`$sum`, `$count`, `$avg`, `$min`, `$max`, `$first`, `$last`, `$push`,
`$addToSet`. Group buckets are emitted in first-seen order (matches
unsharded MongoDB; sharded behaviour isn't modelled).

## Expression operators

The `$expr` operator inside `$match`, plus computed fields in `$project` /
`$addFields`, runs through a single expression evaluator
(`secantus.expressions.evaluate`).

### Field paths and variables

- `"$x.y"` — path into the current doc.
- `"$$ROOT"` / `"$$CURRENT"` — current doc.
- `"$$varname"` — user variable (set via `$let` or `$lookup`'s `let`).
- `{$literal: ...}` — bypass field-path / operator interpretation.

### Arithmetic and comparison

`$add`, `$subtract`, `$multiply`, `$divide`, `$mod`, `$abs`, `$ceil`,
`$floor`, `$exp`, `$ln`, `$log`, `$log10`, `$pow`, `$sqrt`, `$round`,
`$trunc`. Comparison: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$cmp`.

### Logical and conditional

`$and`, `$or`, `$not`, `$cond` (dict or array form), `$ifNull`, `$switch`,
`$let`.

### Strings

`$concat`, `$split`, `$trim`, `$ltrim`, `$rtrim`, `$substrCP`, `$strLenCP`,
`$indexOfCP`, `$toLower`, `$toUpper`, `$toString`, `$regexMatch`,
`$regexFind`, `$regexFindAll`.

### Arrays

`$size`, `$arrayElemAt`, `$first`, `$last`, `$slice`, `$concatArrays`,
`$reverseArray`, `$in`, `$filter`, `$map`, `$reduce`, `$range`, `$zip`,
`$arrayToObject`, `$objectToArray`.

### Documents

`$mergeObjects`, `$objectToArray`, `$arrayToObject`, `$setField`,
`$getField`, `$unsetField`.

### Dates

`$year`, `$month`, `$dayOfMonth`, `$dayOfWeek`, `$hour`, `$minute`,
`$second`, `$millisecond`, `$dateToString`, `$dateFromString`.

`$dateToString` and `$dateFromString` accept a **timezone** argument:

- IANA names: `"Europe/Dublin"`, `"America/New_York"` (via `zoneinfo`).
- UTC offsets: `"+05:30"`, `"-04:00"`, `"+0530"` (fixed-offset tzinfo).
- Aliases: `"UTC"`, `"GMT"`, `"Etc/UTC"`, `"Etc/GMT"`.

`$dateToString`: input datetime is treated as UTC if naive (matching BSON
Date semantics) and converted to the requested zone before formatting.

`$dateFromString`: when the parsed string has no zone info, the requested
timezone becomes the input's tzinfo, so the returned datetime represents
the correct UTC instant.

Unknown timezone names raise an error (no silent misinterpretation).

### Type checks and conversions

`$type`, `$toInt`, `$toLong`, `$toDouble`, `$toBool`, `$toDecimal`,
`$toString`, `$toObjectId`, `$toDate`. The `$type` operator returns the
BSON type alias for a value; the int32-vs-int64 distinction depends on
Python value range rather than the original BSON tag (which we throw away
on decode).

## What's not supported

- `$where` — needs a JavaScript runtime; out of scope.
- `$function` — same reason.
- `$densify` with `unit` (date ranges) — deferred.
- `$fill` — deferred.
- `mapReduce` — deprecated by MongoDB; not implemented.
- Text search (`$text`, `$meta: "textScore"`) — would need a full-text
  index implementation.
- Geo (`$near`, `$geoWithin`, ...) — would need geometric primitives.

## Pipeline tips

- Put `$match` first so it can be lifted into the initial fetch's filter
  and benefit from index acceleration.
- `$lookup` joins are O(N+M) in memory; use `$match` before `$lookup` to
  shrink the outer side.
- `$sort` followed by `$limit` is NOT yet a single optimised stage — sort
  runs the full collection then limit truncates. For test workloads this
  is fine; for large simulated datasets, prefer to sort by an indexed
  field so the sort itself is index-walked.