MongoDB Atlas Search

A search index is a separate JSON index definition — created via the Atlas UI, the Atlas CLI, mongosh, or the driver/mongoTemplate’s search-index-management calls — distinct from a normal MongoDB index. It declares field mappings (`dynamic, or explicit per field) and, per field, an analyzer.

Built-in analyzers include lucene.standard (the default), lucene.simple, lucene.whitespace, lucene.keyword, and 40+ per-language analyzers (lucene.english, lucene.spanish, lucene.french, lucene.german, lucene.cjk for Chinese/Japanese/Korean, and more) — pick the one matching each field’s content language rather than relying on the standard analyzer for non-English text.

Atlas Search, Elasticsearch, and Solr all embed Apache Lucene, so the same character-filter → tokenizer → token-filter pipeline concept from Elasticsearch's "Analysis and mappings" section applies here too — just configured through the search index definition instead of the collection schema.

The text operator inside a $search stage performs analyzed full-text matching and accepts a fuzzy option (maxEdits: 1 or 2, prefixLength, maxExpansions) for typo-tolerant matching by edit distance — directly analogous to Elasticsearch’s fuzzy query (or a match query’s fuzziness parameter) and to Solr’s ~N fuzzy query syntax (or eDisMax’s fuzzy support). All three cap the edit distance at 2.

A minimal $search stage using text + fuzzy:

Facet-only queries use the separate $searchMeta stage (or a facet collector alongside $search, read back through the SEARCH_META aggregation variable) with string, number, or date facet types. This is conceptually the same job as Elasticsearch’s aggregations (terms/histogram/date_histogram) and Solr’s faceting (facet.field/facet.range). As with those two, a facet-friendly field generally needs a non-analyzed representation — Atlas Search’s stringFacet type, versus Elasticsearch’s keyword type or Solr’s un-analyzed copyField target.

A minimal $searchMeta facet query, counting documents per genre:

The result is a single metadata document (not matched documents) shaped as \{ count: \{ …​ }, facet: \{ genreFacet: \{ buckets: [ \{ _id: "fantasy", count: 2 }, …​ ] } } }.

Ordinary aggregation projection ($project after $search) works as usual, and $search adds a relevance score exposed via \{ $meta: "searchScore" } — parallel to Elasticsearch’s _score and Solr’s relevance score.

The Atlas-specific angle is returnStoredSource: marking fields stored: true in the search index definition lets $search return those values straight from the Lucene index, skipping the round-trip to the collection — equivalent in purpose to Elasticsearch’s stored fields/_source filtering and Solr’s fl parameter over stored fields.

Choose Atlas Search when the data already lives in MongoDB Atlas and a second search cluster or CDC pipeline is unwanted; choose Elasticsearch/Solr when self-hosting is required, or the data does not already live in MongoDB. For the Solr/Elasticsearch-only head-to-head, see Solr vs. Elasticsearch.

Spring Data MongoDB has no dedicated typed API for $search/$searchMeta — a proposal to add one (spring-data-mongodb#3838, tracking issue #3831) was declined upstream over commercial-feature/licensing and testability concerns.

The native MongoDB Java driver underneath Spring Data MongoDB does have one, since driver 4.7: package com.mongodb.client.model.search (SearchOperator, SearchOptions, SearchFacet, FuzzySearchOptions), plus Aggregates.search(SearchOperator, SearchOptions) / Aggregates.searchMeta(SearchCollector, SearchOptions). No extra starter or dependency is needed beyond spring-boot-starter-data-mongodb — the driver ships inside it already. (The general custom-AggregationOperation extensibility mechanism documented at Spring Data MongoDB — Aggregation Framework Support is useful background on extending aggregations in general, but the typed driver builders below are the better, current answer for $search/$searchMeta specifically.)

Obtain the native collection via mongoTemplate.getCollection(…​) — the same escape hatch Spring Data MongoDB's "execute/CollectionCallback" section documents for driver-level operations Spring Data doesn’t wrap. Results come back as raw Document, not a mapped POJO/record: this bypasses Spring Data’s MappingMongoConverter, and the driver’s default codec registry has no PojoCodecProvider registered, so aggregating into an application type here would fail with CodecConfigurationException unless one were registered separately:

Search indexes themselves are managed outside the application — via the Atlas UI/CLI, or the driver’s createSearchIndex used in the test setup below — not through @Indexed/@CompoundIndex.

Follow Unit and Integration Testing's existing @Testcontainers/@Container/@ServiceConnection house style rather than inventing a different testing convention.

Add the org.testcontainers:mongodb dependency (test scope) — the same module that provides the plain MongoDBContainer class used elsewhere for a bare MongoDB instance, just a different container type here:

MongoDBAtlasLocalContainer extends GenericContainer directly (not MongoDBContainer), but Spring Boot ships dedicated @ServiceConnection support for it specifically, so it still works without a manual @DynamicPropertySource block. Because search-index updates are eventually consistent — not synchronous with the write — the test polls with Awaitility (already this section’s suggested tool for exactly this kind of async-condition wait) until the index’s status reports "READY", then exercises fuzzy matching with its relevance score, autocomplete, and faceting — the three query shapes just introduced — against the container:

This container is for this application’s integration tests; it is not a substitute for validating against a real Atlas cluster before production — index-definition limits, resource sizing, and Atlas-specific operational behavior can still differ.