Structured and text search

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, and embeddedDocument field types aren't supported.
  • The near operator isn't supported.
  • The regex and wildcard operators inside $search aren't supported.
  • The $searchMeta stage, $$SEARCH_META variable, counts, facets, highlighting, and custom score boosts aren't supported.
  • Use the dropIndexes command to drop a search index. Dedicated search-index update APIs aren't part of the currently supported management surface.