Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Structured and text search combines relevance-ranked text matching with exact values, numeric and date ranges, and other conditions in one $search stage. Map text and structured fields in the same search index, then use compound to combine the conditions.
Use this approach for product catalogs, knowledge bases, and other collections where matching text isn't enough. For example, search for a product description while requiring an in-stock item within a price range.
Note
Full-text search is in preview. Before using these examples, enable full-text search on your cluster.
Supported field mappings
Declare searchable fields under mappings.fields. Choose a type that matches the stored values and the queries you need.
| Field type | Purpose | Supported queries and ordering |
|---|---|---|
string |
Analyzed text. | text, fuzzy text, and phrase. |
document |
Container for nested fields. | Queries target its explicitly mapped leaf fields. |
token |
Exact string terms, such as identifiers and categories. | equals, range, exists, in, and inline sort. |
number |
Numeric values. | equals, range, exists, in, and inline sort. |
date |
Date values. | equals, range, exists, in, and inline sort. |
boolean |
Boolean values. | equals, exists, in, and inline sort. |
Use string for analyzed language text and token for exact string comparisons. For numeric fields, set representation to double or int64 as appropriate for your data.
Nested fields use recursive document.fields mappings. Address mapped leaf fields with dotted paths, such as details.region.
Arrays don't require a separate mapping type. Map the type of their elements. Array values are indexed when their type matches the field mapping; elements with other types aren't indexed for that field.
Create a search index for text and structured fields
The following examples use MongoDB Shell syntax and a connected Azure DocumentDB cluster with full-text search enabled. Use a new collection named products.
Add sample documents
Create the collection and add documents with text, identifiers, prices, availability, and dates.
db.createCollection("products");
db.products.insertMany([
{
_id: 1,
title: "Bracket controller",
description: "Steel mounting bracket for a controller",
partNumber: "SKU-BRACKET-001",
category: "hardware",
price: 49.0,
inStock: true,
publishedAt: ISODate("2026-09-01T00:00:00Z"),
details: { region: "west" }
},
{
_id: 2,
title: "Bracket assembly",
description: "Heavy-duty bracket for an industrial controller",
partNumber: "SKU-BRACKET-002",
category: "hardware",
price: 129.0,
inStock: true,
publishedAt: ISODate("2026-10-01T00:00:00Z"),
details: { region: "east" }
},
{
_id: 3,
title: "Lightweight bracket",
description: "Compact bracket for a controller",
partNumber: "SKU-BRACKET-003",
category: "accessories",
price: 29.0,
inStock: false,
publishedAt: ISODate("2026-10-15T00:00:00Z"),
details: { region: "west" }
}
]);
Map the searchable fields
Create one index that covers every field used by the queries.
db.runCommand({
createSearchIndexes: "products",
indexes: [
{
name: "idx_products_filters",
definition: {
mappings: {
dynamic: false,
fields: {
title: { type: "string" },
description: { type: "string" },
partNumber: { type: "token" },
category: { type: "token" },
price: { type: "number", representation: "double" },
inStock: { type: "boolean" },
publishedAt: { type: "date" },
details: {
type: "document",
fields: {
region: { type: "token" }
}
}
}
}
}
}
]
});
Confirm the index is ready
Index creation can continue after the command returns. Wait until the index reports status: "READY" and queryable: true.
db.products.aggregate([
{ $listSearchIndexes: { name: "idx_products_filters" } }
]);
Combine text and structured conditions
Use compound to combine operator documents. Each clause contains an array of conditions.
| Clause | Behavior |
|---|---|
must |
Every condition must match and contributes to relevance. |
should |
Matching conditions can improve relevance. In a query with required conditions, they don't have to match. |
mustNot |
Matching documents are excluded. |
filter |
Every condition must match. Conditions can currently affect relevance. |
The following query searches both text fields, requires an in-stock product priced from 20 through 100, and favors an exact phrase in the title:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
compound: {
must: [
{
text: {
query: "bracket controller",
path: ["title", "description"],
matchCriteria: "all"
}
}
],
should: [
{
phrase: {
query: "bracket controller",
path: "title",
slop: 0
}
}
],
filter: [
{ equals: { path: "inStock", value: true } },
{ range: { path: "price", gte: 20, lte: 100 } },
{ in: { path: "category", value: ["hardware", "accessories"] } },
{ exists: { path: "publishedAt" } }
],
mustNot: [
{ equals: { path: "details.region", value: "retired" } }
]
}
}
},
{ $limit: 10 },
{
$project: {
_id: 0,
title: 1,
partNumber: 1,
price: 1,
inStock: 1,
score: { $meta: "searchScore" }
}
}
]);
For the sample data, the query returns Bracket controller. The more expensive assembly and the out-of-stock bracket don't satisfy the required conditions.
Important
compound.minimumShouldMatch isn't currently supported. Conditions in compound.filter can contribute to relevance scoring as well as restricting matches. Don't assume that a filter leaves scores unchanged.
Use structured operators
The structured operators match indexed values rather than analyzed text. Query value types must match their field mappings.
| Operator | Purpose | Required options |
|---|---|---|
equals |
Matches an exact value. | path and value. |
range |
Matches bounded values on a number, date, or token field. |
path and at least one of gt, gte, lt, or lte. |
exists |
Matches documents with an indexed value at the path. | path. |
in |
Matches a value from a set. | path and a value array. |
For example, search for an exact part number with equals:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
equals: {
path: "partNumber",
value: "SKU-BRACKET-001"
}
}
},
{ $limit: 10 },
{ $project: { _id: 0, title: 1, partNumber: 1 } }
]);
For date ranges, use date values rather than strings:
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
range: {
path: "publishedAt",
gte: ISODate("2026-10-01T00:00:00Z"),
lt: ISODate("2026-11-01T00:00:00Z")
}
}
},
{ $limit: 10 },
{ $project: { _id: 0, title: 1, publishedAt: 1 } }
]);
Search multiple text fields
Pass an explicit array of mapped paths to search multiple fields with text. Use matchCriteria: "any" to match any analyzed query term or "all" to require all analyzed query terms.
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
text: {
query: "bracket controller",
path: ["title", "description"],
matchCriteria: "all"
}
}
},
{ $limit: 20 },
{
$project: {
_id: 0,
title: 1,
description: 1,
score: { $meta: "searchScore" }
}
}
]);
You must include every path in the selected search index. A text query accepts one nonempty query string, not an array of query strings. To search multiple identifier fields with different analysis requirements, see Custom analyzers.
Wildcard query paths aren't supported. Specify each mapped path explicitly.
Sort and limit search results
Search results are ordered by descending relevance by default. Set sort inside $search to order results by indexed scalar fields.
db.products.aggregate([
{
$search: {
index: "idx_products_filters",
text: {
query: "bracket",
path: "description"
},
sort: {
inStock: -1,
price: 1,
score: { $meta: "searchScore" }
}
}
},
{ $limit: 20 },
{
$project: {
_id: 0,
title: 1,
price: 1,
inStock: 1,
score: { $meta: "searchScore" }
}
}
]);
Inline field sort accepts 1 for ascending or -1 for descending order on mapped token, boolean, date, and number fields. Score sort is descending only. Avoid inline sorting on array-valued fields when you need the same array ordering semantics as a downstream $sort.
Place $limit immediately after $search when possible. The limit is pushed into search execution so the engine can stop after collecting the requested top results.
If a condition can't be expressed with a supported search operator, use a downstream $match before the final $limit. Limiting candidates before applying a business filter can omit eligible results.
Current limitations
The following constraints apply to structured and compound search:
- Mappings are static. You must declare every query and inline-sort path in the selected search index.
- The
objectId,uuid, andembeddedDocumentfield types aren't supported. - The
nearoperator isn't supported. - The
regexandwildcardoperators inside$searcharen't supported. - The
$searchMetastage,$$SEARCH_METAvariable, counts, facets, highlighting, and custom score boosts aren't supported. - Use the
dropIndexescommand to drop a search index. Dedicated search-index update APIs aren't part of the currently supported management surface.