Full-text search in Azure DocumentDB

Azure DocumentDB full-text search is a BM25-scored, analyzer-driven search engine exposed through MongoDB-compatible primitives. It ranks results by relevance, tolerates user typos, and combines text matching with structured conditions without a separate search cluster. Custom analyzers support prefix matching, hierarchical identifiers, and language-specific analysis.

Enable full-text search on your Azure DocumentDB cluster before creating search indexes or running $search queries. Choose one of the following methods.

Azure portal

  1. Sign in to the Azure portal and open your Azure DocumentDB cluster.
  2. Under Settings, select Features.
  3. Select Full-text search, which initially has its status set to Off.
  4. In the pane that opens on the right, review the feature information, and then select Enable.

Azure CLI

Run the following command in Bash with Azure CLI installed. Replace the resource ID placeholders with your cluster's values. The PATCH command retains the preview features read from the cluster and includes FullTextSearch exactly once.

set -euo pipefail

az login

RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/mongoClusters/<cluster-name>"
URL="https://management.azure.com${RESOURCE_ID}?api-version=2024-07-01"

# Review the current provisioning state and preview features.
az rest --method get --url "$URL" \
  --query '{state:properties.provisioningState,features:properties.previewFeatures}' \
  --output json

# Preserve other preview features and add FullTextSearch exactly once.
BODY=$(az rest --method get --url "$URL" \
  --query '{properties: {previewFeatures: [properties.previewFeatures[?@ != `"FullTextSearch"`] || `[]`, [`"FullTextSearch"`]][]}}' \
  --output json)

az rest --method patch --url "$URL" --body "$BODY"

# Check the updated configuration.
az rest --method get --url "$URL" \
  --query '{state:properties.provisioningState,features:properties.previewFeatures}' \
  --output json

Terraform

For an existing cluster, use the AzAPI provider to update properties.previewFeatures without recreating the cluster. The following example uses AzAPI 2.x and reads the current list before adding FullTextSearch.

terraform {
  required_providers {
    azapi = {
      source  = "Azure/azapi"
      version = "~> 2.0"
    }
  }
}

provider "azapi" {}

variable "cluster_resource_id" {
  type        = string
  description = "The resource ID of the existing Azure DocumentDB cluster."
}

data "azapi_resource" "cluster" {
  type        = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
  resource_id = var.cluster_resource_id

  response_export_values = {
    preview_features = "properties.previewFeatures || `[]`"
  }
}

resource "azapi_update_resource" "full_text_search" {
  type        = "Microsoft.DocumentDB/mongoClusters@2024-07-01"
  resource_id = var.cluster_resource_id

  body = {
    properties = {
      previewFeatures = distinct(concat(
        data.azapi_resource.cluster.output.preview_features,
        ["FullTextSearch"]
      ))
    }
  }
}

Set cluster_resource_id to your cluster's resource ID. Run terraform init, review terraform plan, and then run terraform apply.

If another Terraform resource manages the cluster, ensure it doesn't also manage this property. For an azurerm_mongo_cluster resource, add preview_features to its lifecycle.ignore_changes list when AzAPI owns the property. Review the plan and don't proceed if it proposes replacing the cluster.

Bicep

Update the template that manages your cluster. Add an array parameter containing every other preview feature you want to retain:

param otherPreviewFeatures array = []

In the properties object of your existing Microsoft.DocumentDB/mongoClusters resource, set:

previewFeatures: union(otherPreviewFeatures, [
  'FullTextSearch'
])

Keep the cluster's other resource properties unchanged. This is a property fragment, not a standalone template. Bicep replaces the preview-feature list with the supplied list; it doesn't automatically read and merge existing features.

Review the deployment with az deployment group what-if, and then deploy your updated template with az deployment group create.

Important

After enabling full-text search with any method, wait 10 minutes before creating a search index or running a query. Seeing FullTextSearch in the resource configuration doesn't mean activation has finished.

What's available today

Capability Operator or primitive
BM25 keyword search $search + text
Fuzzy (typo-tolerant) search $search + text with fuzzy.maxEdits
Phrase search and proximity matching $search + phrase + slop
Prefix search Custom analyzer with an edgeGram tokenizer or token filter
Hierarchical identifier search Custom analyzer with a pathHierarchy tokenizer
Custom text analysis Ordered tokenizer and token-filter pipelines for normalization, stemming, stop words, and pattern processing
Language-specific analysis Chinese, Japanese, Korean, and Thai analyzers and tokenizers
Multi-field identifier search One index with multiple mappings.fields entries and explicit query paths
Alternate analysis of the same field Named multi mappings
Structured and text search token, number, date, and boolean mappings with equals, range, exists, in, and compound
Inline sorting and top-N retrieval $search.sort on mapped scalar fields and downstream $limit pushdown
Hybrid keyword + vector retrieval Separate keyword and cosmosSearch queries combined with RRF

Current limitations

The following capabilities aren't currently supported:

  • Dynamic mappings, dynamic type sets, character filters, synonym definitions, and storedSource.
  • compound.minimumShouldMatch and custom score boosts.
  • The autocomplete, queryString, and near operators.
  • The regex and wildcard operators inside $search aren't supported.
  • The $searchMeta stage, $$SEARCH_META variable, counts, facets, and highlighting.
  • The objectId, uuid, embeddedDocument, autocomplete, and geo mapping types.

Use the client-side or aggregation-pipeline RRF examples in Hybrid search to fuse keyword and vector results. The $rankFusion stage isn't currently supported.

For the service-wide reference, including search-index lifecycle constraints, see Full-text search limitations.

How Azure DocumentDB full-text search works

A search index in Azure DocumentDB is a separate object from a document index. You create it with the createSearchIndexes database command, not with db.<coll>.createIndex({ field: "text" }) and not with createIndexes and a "textSearch" key type. The index definition declares which fields are searchable, their types, and the analyzer pipeline used at index time and query time.

Queries run as the first stage of an aggregation pipeline using the $search operator. By default, the engine returns documents ordered by relevance, which you can read through { $meta: "searchScore" } in a downstream $project stage. Use inline sort to order results by indexed scalar fields instead. Examples in this section use mongosh-style MongoDB Shell syntax, but the same operations work from any MongoDB-compatible driver.

Four rules apply to every Azure DocumentDB full-text search query:

  • Target an index by name with index: "<name>" inside $search. If omitted, the query targets an index named default; it doesn't choose an arbitrary index. Every query path must be present in the selected index.
  • $search is always the first stage of an aggregation pipeline so the search index narrows the candidate set before any other operator runs.
  • There is no count or limit field inside $search. Cap results with a downstream { $limit: N } stage.
  • Combine text and structured conditions with compound. Use equals, range, exists, and in on mapped scalar fields. For conditions that need a downstream $match, apply it before the final $limit so the limit applies to eligible results.

Setting dynamic: false or omitting dynamic uses static mappings. Every searchable field must be explicitly declared under mappings.fields. Setting dynamic: true causes index creation to fail with mappings.dynamic is not supported in search indexes yet. Index creation also fails if mappings.fields is missing or empty.

A single search index can cover multiple text, identifier, numeric, date, Boolean, and nested document fields.

Mode Best for Requires search index Ranked by BM25
$regex Pattern matching against field values without relevance ranking. Performance depends on the pattern and available indexes. No No
$search + text Standard keyword search on prose, descriptions, titles. Yes Yes
$search + text + fuzzy Search-as-you-type, user-facing catalog or log search where typos are common. Yes Yes
$search + phrase Multi-word product names, quoted user input, error strings where word order matters. Yes Yes
Custom analyzer + text Prefix lookups, hierarchical identifiers, normalized text, and language-specific analysis. Yes Yes
$search + compound Text retrieval with exact category, availability, numeric, or date conditions in one query. Yes Text clauses contribute to relevance
Hybrid (BM25 + vector) Catalog or knowledge-base search that mixes natural-language queries with exact identifiers; RAG retrieval. Yes (BM25 + vector) Fused score

Full-text search and text indexes

The $text operator and { field: "text" } indexes are generally available. Full-text search uses separate search indexes and $search queries and remains in preview. Enabling the preview doesn't change existing text indexes or $text queries.

To evaluate preview full-text search, create a separate search index and use $search queries. You don't need to migrate existing $text workloads to evaluate the preview.