Atlas M10+ only. This operation requires MongoDB Atlas M10 or above. Shared-tier clusters (M0, M2, M5) and self-hosted MongoDB instances do not support programmatic Atlas Search index management.
When to Use
- Schema evolution after data model change: When new searchable fields are added to documents in a collection (e.g. a
brand field added to product records), a deployment workflow updates the existing Atlas Search index definition to include the new field with the appropriate type and analyzer. Documents already in the collection are re-indexed for the new field automatically.
- Search relevance tuning: An A/B test concludes that a different analyzer configuration produces better search results. A workflow applies the updated analyzer definition to the production index, replacing the old configuration. The index rebuilds while continuing to serve the prior definition, ensuring zero-downtime relevance improvement.
- Adding vector search to an existing text index: After generating embeddings for an existing document collection, update the Atlas Search index to add a
knnVector field mapping alongside existing text field mappings, enabling the collection to serve both text and semantic vector queries from a single index.
- Index definition drift correction: A monitoring workflow detects that the live index definition has drifted from the authoritative schema stored in a version-controlled configuration document. The workflow automatically applies the canonical definition via searchindex/update, restoring the expected index structure.
- Analyzer upgrade after language support addition: A SaaS product adds Japanese language support. A workflow updates the existing search index on the
products collection to include a lucene.japanese analyzer on the name and description fields alongside the existing lucene.standard analyzer.
Full definition replacement. This operation replaces the entire index definition. It is not a partial patch — you must supply the complete new mapping definition, including all fields that should be retained. To preserve existing fields while adding new ones, first retrieve the current definition using
searchindex/list, merge in the new fields, and then submit the complete merged definition.
Configuration
Connection
| Field | Required | Description |
|---|
ConnectionUri | Required | MongoDB Atlas connection string. Reference via {{ $credentials.mongodbAtlas }}. |
Database | Required | Database containing the collection with the index to update. |
Collection | Required | Collection name on which the target search index is defined. |
Operation
| Field | Required | Description |
|---|
IndexName | Required | The exact name of the existing Atlas Search index to update. The index must already exist — this operation does not create a new index if the name is not found. Use searchindex/list to verify the index name before updating. |
Definition | Optional | The complete new index definition as a JSON object. Default {} resets the index to a dynamic mapping. For production, provide the full mappings object including all fields that should be indexed — both existing fields you want to preserve and any new fields being added. Supports all Atlas Search field types and analyzer configurations. |
Sample Configuration
Update a product search index to add a brand field and a knnVector embedding field alongside existing mappings:
{
"resource": "search-index",
"operation": "update",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "ecommerce",
"Collection": "products",
"IndexName": "product_fulltext_search",
"Definition": {
"mappings": {
"dynamic": false,
"fields": {
"name": {
"type": "string",
"analyzer": "lucene.standard",
"searchAnalyzer": "lucene.standard"
},
"description": {
"type": "string",
"analyzer": "lucene.standard"
},
"category": {
"type": "string",
"analyzer": "lucene.keyword"
},
"brand": {
"type": "string",
"analyzer": "lucene.keyword"
},
"price": {
"type": "number"
},
"inStock": {
"type": "boolean"
},
"tags": {
"type": "string",
"analyzer": "lucene.standard"
},
"embedding": {
"type": "knnVector",
"dimensions": 1536,
"similarity": "cosine"
}
}
}
}
}
Validation Errors
| Error | Cause |
|---|
connectionUri is required | ConnectionUri is empty or not provided. |
database is required | Database field is empty. |
collection is required | Collection field is empty. |
indexName is required | IndexName is empty or whitespace. |
Output — Success Port
| Field | Type | Description |
|---|
success | boolean | true when MongoDB accepted the update request. The index rebuild is still in progress — poll searchindex/list to confirm status: "READY". |
status | string | Always "success" on the success port. |
resource | string | Always "search-index". |
operation | string | Always "update". |
Sample Output
{
"success": true,
"status": "success",
"resource": "search-index",
"operation": "update"
}
Expression Reference
| Expression | Returns | Description |
|---|
{{ $output.UpdateSearchIndex.success }} | boolean | Confirm the update was accepted. Branch on false to handle rejection (e.g. index name not found). |
{{ $output.UpdateSearchIndex.status }} | string | Confirm "success" for downstream conditional logic. |
Node Policies & GuardRails
| Policy | Recommendation |
|---|
| Credential storage | Always reference ConnectionUri from BizFirst Credentials Manager. Never embed raw Atlas credentials in workflow node fields. |
| Full definition — not a patch | Supply the complete new definition including all fields to retain. Any field omitted from the Definition object will no longer be indexed after the rebuild. Read the current definition first using searchindex/list and merge before submitting. |
| Verify index exists first | Run searchindex/list before updating to confirm the index name exists. An update to a non-existent index name raises an error. Use an IfCondition to handle the not-found case by routing to searchindex/create instead. |
| Zero-downtime rebuild | Atlas rebuilds the index against the new definition while the old definition continues to serve queries. During the rebuild, searches return results based on the prior definition. After READY is reached, queries use the new definition. Plan for a temporary relevance gap during the rebuild window. |
| Poll for READY after update | Always follow searchindex/update with a polling loop using searchindex/list to confirm the rebuilt index has reached status: "READY" before announcing the schema change as complete in a deployment pipeline. |
| Test definition in staging | Apply and validate new index definitions in a staging environment before running searchindex/update in production. An incorrect definition can produce a FAILED index that requires manual intervention to recover. |
| Atlas tier requirement | Confirm the cluster tier is M10+ before running this operation. A connection to a shared-tier cluster or self-hosted instance returns a driver-level error. |
Workflow Examples
Example 1 — Add New Field to Existing Index
// Step 1: List to get current definition
{
"resource": "search-index",
"operation": "list",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "ecommerce",
"Collection": "products"
}
// Step 2: Use Function node to merge new field into existing definition
// Step 3: Update with merged definition
{
"resource": "search-index",
"operation": "update",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "ecommerce",
"Collection": "products",
"IndexName": "product_fulltext_search",
"Definition": "{{ $json.mergedDefinition }}"
}
Example 2 — Drift Correction from Config Store
{
"resource": "search-index",
"operation": "update",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "{{ $json.database }}",
"Collection": "{{ $json.collection }}",
"IndexName": "{{ $json.indexName }}",
"Definition": "{{ $json.canonicalDefinition }}"
}
Example 3 — Analyzer Upgrade for Language Support
{
"resource": "search-index",
"operation": "update",
"ConnectionUri": "{{ $credentials.mongodbAtlas }}",
"Database": "catalog",
"Collection": "products",
"IndexName": "product_search",
"Definition": {
"mappings": {
"dynamic": false,
"fields": {
"name": [
{ "type": "string", "analyzer": "lucene.standard" },
{ "type": "string", "analyzer": "lucene.japanese", "name": "name_ja" }
],
"category": { "type": "string", "analyzer": "lucene.keyword" },
"price": { "type": "number" }
}
}
}
}
