Escrevendo consultas $search: texto, frase e curinga

Atlas Search queries are written using the $search aggregation stage—a special pipeline stage that routes the query to the Lucene engine rather than the MongoDB query planner. The $search stage must be the first stage in an aggregation pipeline. Inside it, you specify an operator (like text, phrase, or wildcard) that determines how the query string is matched against indexed documents.

The text operator is the standard keyword search operator. It tokenizes the query string using the same analyzer used to build the index, then looks for documents containing those tokens. It supports multi-word queries where any word can match (OR semantics by default) and the path field specifies which indexed fields to search in—either a specific field name or all fields via { wildcard: '*' }.

The path field in a text operator can be a single field name, an array of field names, or the wildcard { wildcard: '*' } to search all indexed fields. When searching multiple fields, MongoDB combines results using the best score across fields. Searching fewer, more relevant fields typically produces better precision than searching all fields.

The phrase operator requires the query terms to appear in order and adjacent to each other in the document (like quoting a phrase in a search engine). This is more restrictive than text but much more precise—searching for 'machine learning' as a phrase will not match documents that only contain 'learning' and 'machine' in different sentences. Use slop to allow some words between terms.

The wildcard operator matches documents where the field value matches a glob-style pattern using * (matches any sequence of characters) and ? (matches any single character). It searches against the indexed token values, so the behavior depends on the analyzer. For keyword-analyzed fields, it matches the entire stored string. Set allowAnalyzedField: true to use wildcard on analyzed fields (use with care—expensive for leading wildcards).

Atlas Search computes a relevance score for each result document indicating how well it matches the query. Access this score in a $project stage using { $meta: 'searchScore' }. By default, $search returns results in descending score order (most relevant first). Projecting the score also lets you filter on it—for example, discarding low-relevance results below a threshold.

You can follow $search with a $match stage to apply additional structured filters—for example, text search for 'headphones' and then filter to products with price under $100. However, use $searchMeta or the filter clause inside $search for pre-filtering on indexed fields, as post-match $match runs after all results are fetched and may be slower than filtering within the search stage.

The range operator allows numeric or date range filtering inside the $search stage. This is more efficient than a post-search $match because Lucene applies the filter before fetching documents. Use gte, gt, lte, and lt bounds. The range operator works on fields indexed with type 'number' or 'date' in the Atlas Search index mapping.

The equals operator performs an exact equality match on a field—similar to MongoDB's standard equality filter but executed inside the Lucene engine. It works on boolean, number, date, objectId, and string fields. Using equals inside $search (rather than a post-search $match) allows Lucene to combine it with the text query efficiently using its bitset and skip-list optimizations.

Atlas Search generally outperforms MongoDB's native text indexes for complex queries because Lucene's inverted index is more sophisticated. However, for simple keyword lookups on small collections, the native $text operator may be sufficient. Key advantages of Atlas Search: better relevance scoring, per-field boosting, fuzzy matching, autocomplete, facets, and no one-text-index-per-collection limitation. Choose Atlas Search when you need any of these features.

When you have multiple Atlas Search indexes on a collection, specify the index field inside $search to select which index to use. If you omit it, Atlas Search uses the index named 'default'. Using named indexes allows different query types to use different index configurations—for example, a 'standard' index for keyword search and an 'autocomplete' index for type-ahead suggestions.

Test your understanding of MongoDB & NoSQL Databases concepts from this lesson.

In this lesson you learned: $search must be the first pipeline stage and takes an operator like text, phrase, or wildcard, the text operator matches any token from the query while phrase requires tokens to appear in order, and use the compound operator with filter clauses to combine text search with structured filters efficiently inside the Lucene engine. Next up we explore autocomplete and fuzzy matching for typo-tolerant search.