Release Notes for MongoDB 8.3

Accessing Array Element Indexes in $map, $filter, and $reduce

MongoDB 8.3 improves access to array element indexes in $map, $filter, and $reduce aggregation expressions. You can use the new arrayIndexAs field to set a variable to store the index of an array element. You can also use the new $$IDX aggregation system variable to access the index of the current array element if you omit arrayIndexAs.

FTDC Statistics

Starting in MongoDB 8.3, Full Time Diagnostic Data Capture (FTDC) collects connPoolStats metrics for mongod processes.

serverStatus Output

serverStatus includes the following new fields in its output:

• aggregate.withExtension sub-field in metrics.commands.aggregate, tracking success and failure counts

• shardingStatistics.databaseCriticalSectionStatistics

• shardingStatistics.collectionCriticalSectionStatistics

• shardingStatistics.databaseVersionUpdateCounters

• metrics.query.cbr

• metrics.query.cbr.choseWinningPlan

• metrics.query.cbr.count

• metrics.query.cbr.histograms

• metrics.query.cbr.histograms.micros

• metrics.query.cbr.histograms.numPlans

• metrics.query.cbr.histograms.samplingMicros

• metrics.query.cbr.micros

• metrics.query.cbr.numPlans

• metrics.query.cbr.numPlansFailedCostEstimation

• metrics.query.cbr.numPlansTiedCostEstimation

• metrics.query.cbr.samplingMicros

• metrics.ttl.deletedKeys

• metrics.ttl.durationMicros

• metrics.ttl.examinedDocuments

• metrics.ttl.examinedKeys

• metrics.extension

• metrics.extension.totalAggStageExecMicros

• metrics.extension.apiCallSuccesses

• metrics.extension.apiCallFailures

• metrics.extension.vectorSearch

• metrics.extension.vectorSearch.legacyVectorSearchUsed

• metrics.extension.vectorSearch.extensionVectorSearchUsed

• metrics.extension.vectorSearch.onViewKickbackRetries

• metrics.extension.vectorSearch.inSubpipelineKickbackRetries

• metrics.repl.network.oplogFetcherLagSeconds

• metrics.repl.network.oplogGetMoresProcessed

• queues.execution.admissions

• queues.execution.backgroundTasksDeprioritization

• queues.execution.deprioritizationGate

• queues.execution.heuristicDeprioritization

• queues.execution.heuristicDeprioritizationThreshold

• queues.execution.totalDeprioritizations

• queues.execution.usesPrioritization

• queues.execution.usesThroughputProbing

• queues.execution.nonDeprioritizable

• queues.execution.deprioritizable

• queues.execution.read.normalPriority.totalDelinquentAcquisitions

• queues.execution.read.normalPriority.totalAcquisitionDelinquencyMillis

• queues.execution.read.normalPriority.maxAcquisitionDelinquencyMillis

• queues.execution.read.lowPriority

MongoDB 8.3 removes the service field in the serverStatus output.

Starting in MongoDB 8.3, you can exclude all optional fields from the serverStatus output by specifying none: 1. After you exclude all optional fields, you can then specify the fields you want to include.

For details, see Exclude All Optional Fields.

You can also optionally specify lockContentionMetrics: 1 in the serverStatus command to include lockContentionMetrics in the output.

String Conversion Enhancements

Starting in MongoDB 8.3, $toString can convert additional BSON types to strings, including objects, arrays, regular expressions, MaxKeys, MinKeys, and timestamps. For details, see $toString.

MongoDB 8.3 introduces the optional base argument for $convert to convert between string and numeric values using bases 2, 8, 10, and 16. For details, see $convert.

Array Conversion Enhancements

Starting in MongoDB 8.3, you can convert strings that represent arrays using $convert or the shorthand expression $toArray.

You can also convert between binData and arrays of numeric values. For details, see Convert binData to Array and Convert an Array of Numeric Values to binData.

Object Conversion Enhancements

Starting in MongoDB 8.3, you can convert strings that represent objects using $convert or the shorthand expression $toObject.

Geospatial Index Generation

Starting in MongoDB 8.3, if a document contains both GeoJSON and legacy numeric coordinate fields, geospatial index generation prioritizes GeoJSON coordinates.

If your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior, you might need to rebuild your geospatial indexes.

This change may require you to rebuild geospatial indexes if your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior. Review geospatial queries to confirm they return expected results.

Remove Shard Changes

Starting in MongoDB 8.3, the removeShard command is deprecated. This release introduces four new commands to replace removeShard and provide granular control over the shard draining and removal process.

• startShardDraining

• stopShardDraining

• shardDrainingStatus

• commitShardRemoval

MongoDB provides four additional commands to transition from an embedded config server to a dedicated config server.

• startTransitionToDedicatedConfigServer

• stopTransitionToDedicatedConfigServer

• getTransitionToDedicatedConfigServerStatus

• commitTransitionToDedicatedConfigServer

PreAuth Connection Limit Parameters

MongoDB 8.3 adds three new server parameters that limit the resource consumption of pre-auth connections:

• capMemoryConsumptionForPreAuthBuffers

• messageSizeErrorRateSec

• preAuthMaximumMessageSizeBytes

cachePressureQueryPeriodMilliseconds Parameter

MongoDB 8.3 adds the cachePressureQueryPeriodMilliseconds parameter which sets the time interval MongoDB waits between checks for storage engine cache pressure. If the storage engine is under cache pressure, MongoDB aborts the oldest transaction. For details, see cachePressureQueryPeriodMilliseconds.

diagnosticDataCollectionDirectorySizeMB Parameter

MongoDB 8.3 increases the default value of diagnosticDataCollectionDirectorySizeMB from 200 to 500 MiB.

overloadAwareServerSelectionEnabled Parameter

MongoDB 8.3 adds the overloadAwareServerSelectionEnabled parameter, which controls whether retries that target other servers in the cluster avoid members that recently returned an error labeled SystemOverloadedError. You can enable this parameter to opt in to overload-aware retargeting.

ingressRequestRateLimiterApplicationExemptions Parameter

Starting in MongoDB 8.3, the ingressRequestRateLimiterApplicationExemptions parameter lets you specify applications to exempt from ingress request rate limiting. For details, see ingressRequestRateLimiterApplicationExemptions.

Database Profiler Parameters and Metrics

MongoDB 8.3 adds two parameters that let you control the impact that the Database Profiler has on query performance:

• internalQueryGlobalProfilingLockDeadlineMs

• internalProfilingMaxAbandonedWritesPerSecondPerDb

MongoDB 8.3 also adds two related serverStatus metrics:

• profiler.totalAbandonedWrites

• profiler.dbsPastThreshold

Retry Parameters

MongoDB 8.3 adds parameters to configure how internal server-side clients (between mongos and mongod) back off when retrying operations that fail due to overload.

• defaultClientBaseBackoffMillis

• defaultClientMaxBackoffMillis

• defaultClientRetryAttempts

BSONObjectTooLarge Code for Upsert Errors

Starting in 8.3, upsert operations that produce a BSON object that is too large return the 10334 BSONObjectTooLarge error code. In earlier versions, upsert operations that produce a BSON object that is too large return the 17419 or 17420 error codes.

validate Command Updates

Starting in 8.3, MongoDB no longer automatically enables the checkBSONConformance field in the db.collection.validate() method when full is true. Additionally, the db.collection.validate() method now checks to ensure a collection doesn't have any documents that exceed 16 MB.

New Expression $subtype

MongoDB 8.3 introduces a new $subtype expression to extract the subtype of binary data objects.

New Expressions for Extended JSON Conversion

MongoDB 8.3 introduces new aggregation expressions for converting between BSON and Extended JSON (EJSON) format:

• $serializeEJSON - Converts BSON values to Extended JSON format with type wrappers. Supports both Canonical and Relaxed Extended JSON formats.

• $deserializeEJSON - Converts Extended JSON format back to native BSON values.

These expressions can be combined with $convert to parse JSON strings, transform Extended JSON values into native BSON values, and convert back to JSON format.

New Expression $createObjectId

Starting in MongoDB 8.3, you can use $createObjectId to generate new random ObjectId() values in pipelines and expression-based updates.

Pre-Epoch Dates

Starting in MongoDB 8.3, if unit is not "millisecond" in $dateAdd or $dateSubtract and the input date is before ISODate("1970-01-01T00:00:00Z"), the result will be one second greater than in previous versions of MongoDB. This also affects the results of aggregations that perform time-based calculations like $setWindowFields and $densify.

Geospatial Index Generation

MongoDB 8.3, continues the behavior introduced in MongoDB 8.2. If a document contains both GeoJSON and legacy numeric coordinate fields, geospatial index generation prioritizes GeoJSON coordinates.

If your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior, you might need to rebuild your geospatial indexes.

This change might require you to rebuild geospatial indexes if your documents contain legacy numeric coordinate values that precede GeoJSON coordinates and existing indexes rely on that behavior. Review geospatial queries to confirm they return expected results.

Subnormal Numbers in $convert Pipelines

Starting in MongoDB 8.3, the server is able to parse the full range of all representable double precision floating point numbers. This includes subnormal numbers where the most significant digit has leading zeroes and the exponent has the least possible value.

For details, see Subnormal Numbers.

chars Length Limit for $trim, $ltrim, and $rtrim

Starting in MongoDB 8.3, the length of the string you provide to chars is limited to 4096 characters. For details, see $trim Limitations.

Default Plan Selection Mechanism

Starting in MongoDB 8.3, multi-planning with a CBR backup is the default plan selection mechanism for eligible queries. For a short trial period, the multi-planner attempts to find a plan capable of returning a result set within this short timeframe. If the attempt is unsuccessful, a set of rules is applied to determine whether the multi-planner should continue or if CBR should be used to determine the optimal plan.

Window Functions

Starting in MongoDB 8.3, you can use $mergeObjects in $setWindowFields operations.

sp.process() limit Option

Starting in MongoDB 8.3, sp.process() supports the options.limit input parameter. After sp.process() returns limit documents to your terminal, the session ends.

DDL Operations for Sharded Clusters Can Only Run on mongos

Starting in MongoDB 8.3, DDL operations and applyOps can only be run on a mongos for all sharded clusters.

findShardsOnConfigTimeoutMS Parameter

MongoDB 8.3 adds the findShardsOnConfigTimeoutMS parameter which sets the timeout in milliseconds for find operations against the config.shards namespace. For details, see findShardsOnConfigTimeoutMS.

config.csrs.indexes Removed

MongoDB 8.3 removes the config.csrs.indexes namespace.

2dsphereIndexVersion

Starting in MongoDB 8.3, 2dsphereIndexVersion is set to version 4 by default.

If you need to downgrade the FCV to anything below 8.3, you must first drop the 2dsphere version 4 indexes.

Conversion to Embedded Config Shard

MongoDB 8.3 introduces the mongod --replicaSetConfigShardMaintenanceMode option.

In previous releases, converting a replica set to a sharded cluster with an embedded config shard required you to first migrate to a sharded cluster with a dedicated config server replica set.

If you restart a replica set with the --replicaSetConfigShardMaintenanceMode and --configsvr options, you can convert the primary node directly into an embedded config shard.

refineCollectionShardKey Formatting

Starting in MongoDB 8.3, refineCollectionShardKey for time-series collections only accepts shard keys specified using the collection's logical meta and time fields. MongoDB no longer supports specifying keys using the underlying buckets format.

Index Naming Restrictions

Starting in MongoDB 8.3, creating an index with the name of "_id_" or specifying a hint of "_id_" on time series collections returns an error.

timeField Naming Restrictions

Starting in MongoDB 8.3, you cannot create a timeField that starts with a $ character.

Fields to Track Use of Memory by Queries

Starting in MongoDB 8.3, you can use the following new fields to track query memory use:

Both fields appear in the following places:

• $currentOp (Aggregation Stage) output

• db.currentOp() output

• Database profiler output

• Log messages

• Slow query log messages

The peakTrackedMemBytes field also appears in the following places:

• Explain results

• PlanCache.list() output

• $planCacheStats output

Starting in 8.3, use the following new metrics in $queryStats to measure the behavior of checkForInterrupt:

• metrics.numInterruptChecksPerSec

• metrics.overdueInterruptApproxMaxMillis

Mongos Query Shape Field

Starting in MongoDB 8.3, slow query log entries have an optional originalQueryShapeHash field that contains that query shape of the following operations that originate on the mongos :

• find

• aggregate

• count

• distinct

Slow In-Progress Query Logs

MongoDB 8.3 introduces slow in-progress query log entries. Log messages on slow in-progress queries contain less information than standard slow query logs. MongoDB logs queries at most once if the query's duration surpasses the slowOpInProgressThreshold. You can set the threshold with db.setProfilingLevel() or the new mongod --defaultSlowInProgMS command line option.

Only Single-Version Downgrades are Supported

MongoDB supports single-version downgrades along adjacent versions only. You cannot downgrade to a release that is multiple versions behind your current release.

• For any versions, major or minor, you can upgrade or downgrade to its adjacent neighbors. For example, you can downgrade from 8.3 to 8.2 or upgrade from 7.0 to 8.0.

• For all versions, major or minor, you can downgrade to the immediately previous major version. For example, from 8.3 to 8.0.

• For any minor version, you can upgrade to the immediately next version. For example, from 8.2 to 8.3.

Downgrade Policy

• Binary downgrades aren't supported for MongoDB Community Edition.

• You cannot downgrade your deployment's FCV to or from a minor release version of MongoDB.

• If you upgrade or downgrade your deployment's FCV, you cannot downgrade your Enterprise deployment's binary version without assistance from support.

Backward-Incompatible Features

MongoDB 8.3 includes features that are not compatible with earlier releases. Downgrading from 8.3 to an earlier release requires that you remove data that uses these features.

For more information, see Backward-Incompatible Features.

Key Material Entries

Starting in MongoDB 8.3, deployments that use disaggregated storage can generate an internal key material oplog entry labeled op: "km". km entries record key-encryption-key (KEK) metadata that the server and any tooling that decrypts the oplog need to decrypt future oplog entries during point-in-time restore workflows. They do not represent application-level CRUD or DDL operations.

If you run custom tooling that tails the oplog directly on a disaggregated storage deployment, for example, for change capture, auditing, or backup, you can either:

• Read op: "km" entries and use their KEK metadata to decrypt subsequent oplog entries if your tooling needs to decrypt or interpret those entries.

• Treat them as internal key-management metadata and not as logical data changes.

Sharded Clusters

Starting in MongoDB 8.3, if you run explain() against a database that does not exist on a sharded cluster, the execution stage reaches the end-of-stream and the operation does not create the database. For more information on end-of-stream execution stats, see explain.executionStats.executionStages.isEOF.

SCRAM-SHA-1 and FIPS Mode

Starting in MongoDB 8.3, you cannot specify SCRAM-SHA-1 for authenticationMechanisms while also specifying mongod --tlsFIPSMode or mongos --tlsFIPSMode.

If you try to specify SCRAM-SHA-1 for authenticationMechanisms while also specifying --tlsFIPSMode, the server throws an error and logs a message similar to the following:

SCRAM-SHA-1 is not allowed in FIPS mode.