db.collection.distinct() (original) (raw)

db.collection.distinct(field, query, options)

Finds the distinct values for a specified field across a single collection or view and returns the results in an array.

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

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

Note

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, seeUnsupported Commands.

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

This method takes the following parameters:

Note

The following diagram shows an exampledb.collection.distinct() call.

{ collation: <document> }

In a sharded cluster, the distinct command may returnorphaned documents.

For time series collections, thedistinct command can't make efficient use of indexes. Instead, use a$group aggregation to group documents by distinct values. For details, see Time Series Limitations.

If the value of the specified field is an array,db.collection.distinct() considers each element of the array as a separate value.

For instance, if a field has as its value [ 1, [1], 1 ], thendb.collection.distinct() considers 1, [1], and 1 as separate values.

For an example, see Return Distinct Values for an Array Field.

When possible, db.collection.distinct() operations can use indexes.

Indexes can also cover db.collection.distinct() operations. See Covered Query for more information on queries covered by indexes.

To perform a distinct operation within a transaction:

• For unsharded collections, you can use thedb.collection.distinct() method/thedistinct command as well as the aggregation pipeline with the $group stage.
• For sharded collections, you cannot use thedb.collection.distinct() method or thedistinct command.
  To find the distinct values for a sharded collection, use the aggregation pipeline with the $group stage instead. See Distinct Operation for details.

Important

In most cases, a distributed transaction incurs a greater performance cost over single document writes, and the availability of distributed transactions should not be a replacement for effective schema design. For many scenarios, thedenormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for distributed transactions.

For additional transactions usage considerations (such as runtime limit and oplog size limit), see alsoProduction Considerations.

Starting in MongoDB 4.2, if the client that issued db.collection.distinct()disconnects before the operation completes, MongoDB marks db.collection.distinct()for termination using killOp.

To run on a replica set member, distinct operations require the member to be in PRIMARY or SECONDARY state. If the member is in another state, such as STARTUP2, the operation errors.

New in version 8.0.

You can use query settings to set index hints, set operation rejection filters, and other fields. The settings apply to the query shape on the entire cluster. The cluster retains the settings after shutdown.

The query optimizer uses the query settings as an additional input during query planning, which affects the plan selected to run the query. You can also use query settings to block a query shape.

To add query settings and explore examples, seesetQuerySettings.

You can add query settings for find, distinct, and aggregate commands.

Query settings have more functionality and are preferred over deprecated index filters.

To remove query settings, use removeQuerySettings. To obtain the query settings, use a $querySettings stage in an aggregation pipeline.

The examples use the inventory collection that contains the following documents:

{ "_id": 1, "dept": "A", "item": { "sku": "111", "color": "red" }, "sizes": [ "S", "M" ] }

{ "_id": 2, "dept": "A", "item": { "sku": "111", "color": "blue" }, "sizes": [ "M", "L" ] }

{ "_id": 3, "dept": "B", "item": { "sku": "222", "color": "blue" }, "sizes": "S" }

{ "_id": 4, "dept": "A", "item": { "sku": "333", "color": "black" }, "sizes": [ "S" ] }

The following example returns the distinct values for the fielddept from all documents in the inventory collection:

db.inventory.distinct( "dept" )

The method returns the following array of distinct dept values:

The following example returns the distinct values for the fieldsku, embedded in the item field, from all documents in theinventory collection:

db.inventory.distinct( "item.sku" )

The method returns the following array of distinct sku values:

See also:

Dot Notation for information on accessing fields within embedded documents

The following example returns the distinct values for the fieldsizes from all documents in the inventory collection:

db.inventory.distinct( "sizes" )

The method returns the following array of distinct sizes values:

For information on distinct() and array fields, see the Behavior section.

The following example returns the distinct values for the fieldsku, embedded in the item field, from the documents whosedept is equal to "A":

db.inventory.distinct( "item.sku", { dept: "A" } )

The method returns the following array of distinct sku values:

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

A collection myColl has the following documents:

{ _id: 1, category: "café", status: "A" }

{ _id: 2, category: "cafe", status: "a" }

{ _id: 3, category: "cafE", status: "a" }

The following aggregation operation includes the Collationoption:

db.myColl.distinct( "category", {}, { collation: { locale: "fr", strength: 1 } } )

For descriptions on the collation fields, seeCollation Document.