Only for two things: managing vector search indexes (/_indexes with "type": "vectorSearch", including autoEmbed) and running $vectorSearch itself. Both are executed by mongot, not by mongod alone — you need either MongoDB Atlas or MongoDB Community/Enterprise 8.2+ with mongot installed. autoEmbed additionally needs a Voyage AI key configured on Atlas (Integrations) or passed to your mongot instance.

Everything else in this page runs on any plain MongoDB — no mongot, no Atlas, no extra setup:

In practice: you can chunk files, embed them with your own provider, and semantically search them with $vectorScan on a stock MongoDB instance with zero extra setup — and only bring in mongot once you need `$vectorSearch’s indexed, approximate-nearest-neighbor search at scale.

PUT, GET and DELETE on /_indexes handle "type": "vectorSearch" bodies automatically. No config, no enabled: true — just use it.

GET /mydb/articles/_indexes lists it alongside regular indexes; DELETE /mydb/articles/_indexes/article_vectors removes it.

Query an autoEmbed index with queryString instead of queryVector in your $vectorSearch stage — mongot embeds the query text for you.

$vectorSearch needs mongot and a vector search index. $vectorScan needs neither: it’s a brute-force aggregation stage that computes similarity directly against a plain array field, on any MongoDB — including MongoDB Community with no search component installed at all.

Use real $match/$sort stages to narrow candidates first — unlike $vectorSearch’s restricted `filter, this is full MQL. $vectorScan itself takes a path to the vector field, a queryVector, a similarity (cosine, dotProduct, or euclidean), and an optional limit:

Stages placed after $vectorScan — like the $project above — run for real against MongoDB, bridged back in via $documents (requires MongoDB 6.0+). Reranking composes automatically too: attach a rerank block exactly as in section 5 below, since it scores whatever result array the pipeline produced regardless of how it got there.

maxCandidates bounds how many documents (after $match) are scanned and scored before ranking and truncating to limit — there’s no index, so this is the whole cost control. Reach for $vectorScan when you don’t have or don’t want mongot, on candidate sets small enough that a full scan is cheap; move to $vectorSearch once you need indexed approximate-nearest-neighbor search at scale.

maxCandidates and limit are set by whoever defines the aggregation. max-candidates-cap and max-limit-cap are set by whoever runs the node, and the stage cannot exceed them: the scan uses min(what the stage asks for, cap). Scoring runs in RESTHeart, not in MongoDB, so on a node shared by many tenants the caps bound how many vectors a single query pulls into memory. Both are unset by default, which means no cap. When a request is capped, the response carries a Warning: 299 header naming the requested and the effective value, so results that differ from an uncapped run are explained (the body of an aggregation is a plain array, so there is no _warnings field to put it in). Aggregation responses list Warning in Access-Control-Expose-Headers, so a browser on another origin can read it too. A multi-tenant deployment sets the caps per request instead, attaching override-ai-max-candidates-cap and override-ai-max-limit-cap from its own interceptor; an attached value wins over the configured one, and 0 lifts the cap.

A bucket says in its chunking metadata which of its files are split into text chunks, how, and into which collection. Apache Tika extracts the text: PDF, Office, HTML, plain text, and more. The chunker only splits; the collection the chunks go to embeds them with its own vectorSearch rules, as any collection does.

Which files. The first rule a file matches is applied; a file that matches none is not chunked, and a bucket without chunking is never chunked. The filter has three keys, all optional and case-insensitive, all required to match when present: contentType, the type Tika detects, where a trailing * matches any suffix; extension, of the uploaded filename; metadata, a MongoDB filter on the file’s metadata, so your app routes a file by what it sets at upload, e.g. { "metadata": { "kind": "manual" } }. A rule without a filter matches every file.

How. chunk-size and chunk-overlap default to the interceptor’s configuration, both in characters. splitter chooses how the text is cut: auto, the default, at function and class boundaries for a recognized source file and as prose otherwise; text, always as prose, when the model embeds code better that way; code, at code boundaries whenever the language is recognized. Code gets no overlap unless the rule sets chunk-overlap.

Prose is cut the way LangChain’s RecursiveCharacterTextSplitter does: at paragraphs; a paragraph longer than chunk-size at lines, then sentences, then words; the pieces are put back together into chunks as full as chunk-size allows, and the overlap is made of whole pieces of the chunk before. A word is never cut: one longer than a chunk, a URL or a hash, is a chunk of its own. A stretch of whitespace alone, such as a blank page of a PDF, makes no chunk, and a chunk with fewer than 20 letters and digits, a page number or a running header, is joined to its neighbour. The chunk indexes have no gaps.

In the background. With async: true in the interceptor’s configuration, the upload answers as soon as the file is stored, and the file is chunked afterwards: extraction and embedding take seconds on a large PDF. What the chunker did is written on the file’s own document, beside metadata:

pending is there as soon as the upload has answered, running once the file’s turn comes; then done, with the rule applied and the number of chunks, skipped when no rule matched, or failed, with the reason in warnings. Read it with GET /mydb/docs.files?filter={"_id":…}. max-concurrent caps how many files the node chunks at once; a multi-tenant deployment can also cap one database with override-ai-chunking-max-concurrent, and turn the background on per tenant with override-ai-chunking-async. A job a node loses by stopping is not lost for good: every resume-scan-minutes the files still pending or running after resume-after-minutes are claimed, by one node each, and chunked again. Without async the upload waits, its response carries the warnings, and the status is written too.

The chunks. Each one is { "source", "fileId", "chunkIndex", "text", "filename", "contentType", "metadata", "rule" }, where metadata is the file’s own, so a search can narrow by what your app set at upload: a $match before $vectorScan, or the filter of $vectorSearch. All the chunks of a file are written in one request, so the collection’s embedding rule sees them together: with "groupBy": "fileId" and voyageContextualEmbeddingProvider, they are embedded as one document, each vector aware of the others. A collection without an embedding rule stores the chunks without vectors; one that does not exist is created. The account that uploads needs to be able to write to the bucket, not to the chunks collection.

Their lifecycle. Replacing a file with PUT replaces its chunks; deleting it, one by one or in bulk, deletes them.

Checked when written. A rule without target-collection, an unknown key, or an embedding key such as provider or model, which belongs to the chunks collection’s vectorSearch rule, is refused with a 400 that names it.

Source code is chunked as code. A filename with a recognized extension (.java, .kt, .py, .go, .rs, .ts/.tsx, .js/.jsx, .c/.cpp, .cs, .swift) is chunked at function/class boundaries instead of arbitrary character counts — and with zero overlap between chunks, unlike prose: a method is already a self-contained unit, so there’s nothing useful to carry over into the next chunk.

A large class lands in the chunks collection as one chunk per method, each still carrying the enclosing class declaration for context — so a retrieved chunk is never a floating method body with no idea which class it belongs to:

Brace counting is comment- and string-literal-aware (a { inside a "…​" or // …​ doesn’t confuse it), and a class small enough to fit in one chunk stays as a single chunk rather than being split per method for no reason.

No Atlas, no mongot, or you just want a specific model? Enable a provider and point the pieces you need at it:

Embed on write — autoEmbeddingInterceptor embeds a text field automatically whenever a document is written, once a collection opts in:

From then on, any description you write to articles gets an embedding field computed for free.

The model is a property of the vector field, from 9.9: a rule may name its own provider, model and dimensions, and they win over the provider’s configuration and over any override-ai-* the request carries. voyage-law-2 on /legal and voyage-code-4 on /src, with one key. $vectorize follows the same rule, so a question is embedded with the model of the vectors it is searched against:

provider names a configured embedding provider (voyageEmbeddingProvider, voyageContextualEmbeddingProvider, openAIEmbeddingProvider, ollamaEmbeddingProvider); dimensions applies where the provider takes a vector length.

A collection can hold more than one vector field, each with its own model: vectorSearch is then a list of rules, one per vector field. On every write, each rule whose text field the document carries embeds it; a write with only summary recomputes summaryVector and leaves bodyVector as it is. The object form above is still read, as a list of one.

The metadata is checked when it is written: a rule without textField or embeddingField, or two rules on the same embeddingField, is refused with a 400 that names the rule, not at the first document write. With more than one rule, a $vectorize has to say which vector field the question is for; an aggregation that does not is refused, with the collection’s vector fields in the message.

Embed inline in a pipeline — the $vectorize operator turns text into a vector at query time, anywhere in an aggregation:

Requires vectorizeOperator enabled with its own embedding-provider set, unless the collection’s embedding rules name a provider.

The question is embedded with the model of the vectors it is searched against. As the queryVector of a $vectorSearch or $vectorScan stage, $vectorize reads the stage’s path and uses the rule that writes that field: the aggregation above on embedding embeds with the embedding rule, one on bodyVector with the bodyVector rule, and the two questions can have different lengths. Anywhere else, in a $set or a $match on a precomputed vector, the long form names the field:

With one rule on the collection, $vectorize uses it wherever it is, as before; with none, it uses the deployment’s default provider, for vectors written by something else. A path or field that no rule writes is refused with a 400 that names it and lists the collection’s vector fields: a question embedded with the wrong model would make the search silently wrong. So is a $vectorize on a collection with several rules that says nothing about which. With a Voyage provider, $vectorize sends input_type: query unless the configuration or a request override sets one.

Refine $vectorSearch results by adding a rerank block to a predefined aggregation:

By default this calls the Atlas Reranking API (rerankingInterceptor: { enabled: true, atlas-api-key: <key> }). To use Voyage AI or Cohere instead:

Reranking scores each result’s text field against the query — this is exactly what the chunks of section 3 have, so chunking and reranking pair naturally.

Every value above can be overridden per request instead of set once for the whole server — different API keys, models, or providers per tenant. Attach override-ai-embedding-provider, override-ai-openai-api-key, override-ai-chunk-size, and so on to the request (typically from your own tenant-resolving interceptor); anything not overridden falls back to the static config shown above.

All plugins above default to enabled: false except the three index-management interceptors.