Database Manual / Reference / Database Commands / Sharding

cleanupOrphaned (database command)

Important

Starting in MongoDB 6.0.3, run an aggregation using the $shardedDataDistribution stage to confirm no orphaned documents remain. For details, see Confirm No Orphaned Documents Remain.

Definition

cleanupOrphaned

Deprecated since version 8.0.

Use this command to wait for orphaned documents in a chunk range from a shard key's MinKey to its MaxKey for MongoDB to clean up a specified namespace from a majority of a shard's members.

Note

This command does not directly clean up orphaned documents, it awaits the cleanup of orphans in a specified range. For more information on how MongoDB cleans up orphaned documents, see Sharded Cluster Balancer.

To run, issue cleanupOrphaned in the admin database directly on the mongod instance that is the primary replica set member of the shard. You do not need to disable the balancer before running cleanupOrphaned.

Note

Do not run cleanupOrphaned on a mongos instance.

Compatibility

This command is available in deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Important

This command is not supported in M0 and Flex clusters. For more information, see Unsupported Commands.

Syntax

The command has the following syntax:

db.runCommand(
   {
     cleanupOrphaned: "<database>.<collection>",
     startingFromKey: <minimumShardKeyValue>, // deprecated
     secondaryThrottle: <boolean>, // deprecated
     writeConcern: <document> // deprecated
   }
)

Command Fields

cleanupOrphaned has the following fields:

FieldTypeDescription

cleanupOrphaned

string

The namespace, i.e. both the database and the collection name, of the sharded collection for which to wait for cleanup of the orphaned data.

Behavior

Determine Range

The value of this field is not used to determine the bounds of the cleanup range. The cleanupOrphaned command waits until all orphaned documents in all ranges in the namespace are cleaned up from the shard before completing, regardless of the presence of or value of startingFromKey.

Required Access

On systems running with authorization, you must have clusterAdmin privileges to run cleanupOrphaned.

Output

Return Document

Each cleanupOrphaned command returns a document containing a subset of the following fields:

cleanupOrphaned.ok

Equal to 1 on success.

A value of 1 indicates that either:

  • No orphaned documents remain in the cleanupOrphaned namespace on the shard, or
  • The collection referenced in the cleanupOrphaned namespace is not sharded.

A value of 0 indicates that an error has occurred.