9. Stages at a glance
The 28 built-in stages, in catalogue order. .query.stages lists the same catalogue from a running node.
| Stage | Aliases | Family | Summary | Flow | Rows |
|---|---|---|---|---|---|
where | Filtering | Keeps the rows whose predicate is true | streaming | fewer | |
select | project | Shaping | Keeps the listed fields and named expressions | streaming | same |
derive | Shaping | Adds or replaces computed fields | streaming | same | |
rename | Shaping | Renames one field | streaming | same | |
drop | Shaping | Removes fields | streaming | same | |
root | Shaping | Replaces each row by one of its object fields | streaming | same | |
near | Vector | Scores rows by vector similarity | streaming | fewer | |
sort | Ordering | Orders rows by keys | blocking | same | |
limit | Paging | Keeps the first n rows | streaming | fewer | |
skip | offset | Paging | Drops the first n rows | streaming | fewer |
first | Paging | Keeps the first row | streaming | fewer | |
single | Paging | Requires exactly one row | streaming | fewer | |
sample | Sampling | Keeps n rows drawn uniformly | blocking | fewer | |
unwind | Arrays | Emits one row per array item | streaming | more | |
distinct | Deduplication | Keeps one row per distinct key | blocking | fewer | |
count | Counting | Returns the number of rows | streaming | one, terminal | |
group | Aggregation | Aggregates rows by keys | blocking | fewer | |
bucket | Aggregation | Counts rows per value range | blocking | fewer | |
fill | Analytics | Adds the rows a grid of values misses in each partition | blocking | more | |
window | Analytics | Adds values over ordered partitions | blocking | same | |
pivot | Aggregation | Cross-tabulates rows by row and column keys | blocking | one per row key | |
lookup | join | Combining | Attaches the matching rows of another collection | blocking | same |
union | Combining | Appends the rows of another pipeline | blocking | more | |
insert | Write | Inserts documents | transactional | only stage | |
set | Write | Updates fields of the matching documents | transactional | terminal | |
delete | Write | Deletes the matching documents | transactional | terminal | |
into | out | Write | Writes the rows into a collection | transactional | terminal |
load | Write | Imports or upserts documents | transactional | first, terminal |
Flow. Streaming stages handle one row at a time. Blocking stages need their whole input first (they spill to disk when it outgrows memory, chapter 14). Transactional stages write.
Choosing a stage
| I want to… | Use |
|---|---|
| keep some rows | where |
| keep some fields | select, or drop the others |
| add a computed field | derive |
| rename a field | rename, or select old as new |
| promote a sub-object | root |
| order rows | sort |
| take the top N | sort … | limit N |
| page | skip k | limit n |
| get one row, or fail | single |
| one row per array item | unwind |
| distinct values | select f | distinct, or distinct f |
| count rows | count, or group f per value |
| totals per key | group |
| histograms | bucket |
| a cross table | pivot |
| previous / next row, running totals, ranks | window |
| complete missing months | fill |
| attach related rows | lookup |
| stack two sources | union |
| copy results into a collection | into |
| bulk import, upsert | load |
| nearest vectors | near | sort _distance | limit k |
Entry layout
Every entry reads: Definition, Syntax, Behavior, Examples, Errors and limits, See also.