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.
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
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
- Sign in to the Azure portal and open your Azure DocumentDB cluster.
- Under Settings, select Features.
- Select Full-text search, which initially has its status set to Off.
- 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.minimumShouldMatchand custom score boosts.- The
autocomplete,queryString, andnearoperators. - The
regexandwildcardoperators inside$searcharen't supported. - The
$searchMetastage,$$SEARCH_METAvariable, counts, facets, and highlighting. - The
objectId,uuid,embeddedDocument,autocomplete, andgeomapping 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 nameddefault; it doesn't choose an arbitrary index. Every query path must be present in the selected index. $searchis always the first stage of an aggregation pipeline so the search index narrows the candidate set before any other operator runs.- There is no
countorlimitfield inside$search. Cap results with a downstream{ $limit: N }stage. - Combine text and structured conditions with
compound. Useequals,range,exists, andinon mapped scalar fields. For conditions that need a downstream$match, apply it before the final$limitso 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.
When to use Azure DocumentDB full-text search
| 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.