> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# db.collection.distinct() (mongosh method)

## Definition

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

## Compatibility

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

- [MongoDB Atlas](https://www.mongodb.com/docs/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, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

This method takes the following parameters:

| Parameter | Type | Description |
| --- | --- | --- |
| `field` | string | The field for which to return distinct values. |
| `query` | document | A query that specifies the documents from which to retrieve the distinct values. |
| `options` | document | Optional. A document that specifies the options.  See [Options.](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#std-label-distinct-method-options) |

**Note:**

Results must not be larger than the maximum [BSON size](https://www.mongodb.com/docs/manual/reference/limits.md#std-label-limit-bson-document-size). If your results exceed the maximum BSON size, use the aggregation pipeline to retrieve distinct values using the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) operator, as described in [Retrieve Distinct Values with the Aggregation Pipeline.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#std-label-aggregation-group-distinct-values)

The following diagram shows an example `distinct()` call.

![Diagram of the annotated distinct operation.](/images/distinct.bakedsvg.svg)

## Options

```javascript
{ collation: <document> }
```

| Field | Type | Description |
| --- | --- | --- |
| `collation` | document | Optional. Optional. Specifies the [collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation)  to use for the operation. [Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. The collation option has the following syntax: `collation: {
    locale: <string>,
    caseLevel: <boolean>,
    caseFirst: <string>,
    strength: <int>,
    numericOrdering: <boolean>,
    alternate: <string>,
    maxVariable: <string>,
    backwards: <boolean>
 }` When specifying collation, the `locale` field is mandatory; all other collation fields are optional. For descriptions of the fields, see [Collation Document.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields) If the collation is unspecified but the collection has a default collation (see [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection)), the operation uses the collation specified for the collection. If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons. You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort. |

## Behavior

In a [sharded cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-sharded-cluster), the [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct) command may return [orphaned documents.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document)

For [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-landing), the `distinct` command can't make efficient use of indexes. Instead, use a [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) aggregation to group documents by distinct values. For details, see [Time Series Limitations.](https://www.mongodb.com/docs/manual/core/timeseries/timeseries-limitations.md#std-label-timeseries-limitation-distinct)

### Array Fields

If the value of the specified `field` is an array, [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-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 ]`, then [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct) considers `1`, `[1]`, and `1` as separate values.

For an example, see [Return Distinct Values for an Array Field.](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#std-label-distinct-method-array)

### Index Use

When possible, [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct) operations can use indexes.

Indexes can also [cover](https://www.mongodb.com/docs/manual/core/query-optimization.md#std-label-covered-queries) [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct) operations. See [Run Covered Queries](https://www.mongodb.com/docs/manual/core/query-optimization.md#std-label-covered-queries) for more information on queries covered by indexes.

### Transactions

To perform a distinct operation within a transaction:

- For unsharded collections, you can use the [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct) method/the [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct) command as well as the aggregation pipeline with the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) stage.

- For sharded collections, you cannot use the [`db.collection.distinct()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#mongodb-method-db.collection.distinct) method or the [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct) command.

  To find the distinct values for a sharded collection, use the aggregation pipeline with the [`$group`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/group.md#mongodb-pipeline-pipe.-group) stage instead. See [Distinct Operation](https://www.mongodb.com/docs/manual/core/transactions-operations.md#std-label-transactions-operations-distinct) 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, the [denormalized data model (embedded documents and arrays)](https://www.mongodb.com/docs/manual/data-modeling/embedding.md#std-label-data-modeling-embedding) 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 also [Production Considerations.](https://www.mongodb.com/docs/manual/core/transactions-production-consideration.md#std-label-production-considerations)

### Client Disconnection

If the client that issued `distinct()` disconnects before the operation completes, MongoDB marks `distinct()` for termination using [`killOp`.](https://www.mongodb.com/docs/manual/reference/command/killOp.md#mongodb-dbcommand-dbcmd.killOp)

### Replica Set Member State Restriction

To run on a replica set member, [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct) operations require the member to be in [`PRIMARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.PRIMARY) or [`SECONDARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.SECONDARY) state. If the member is in another state, such as [`STARTUP2`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.STARTUP2), the operation errors.

### Query Settings

**New in version 8.0**

You can use query settings to set index hints, set [operation rejection filters](https://www.mongodb.com/docs/manual/tutorial/operation-rejection-filters.md#std-label-operation-rejection-filters), and other fields. The settings apply to the [query shape](https://www.mongodb.com/docs/manual/reference/operator/aggregation/queryStats.md#std-label-queryStats-queryShape) on the entire cluster. The cluster retains the settings after shutdown.

The [query optimizer](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-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, see [`setQuerySettings`.](https://www.mongodb.com/docs/manual/reference/command/setQuerySettings.md#mongodb-dbcommand-dbcmd.setQuerySettings)

You can add query settings for [`find`](https://www.mongodb.com/docs/manual/reference/command/find.md#mongodb-dbcommand-dbcmd.find), [`distinct`](https://www.mongodb.com/docs/manual/reference/command/distinct.md#mongodb-dbcommand-dbcmd.distinct), and [`aggregate`](https://www.mongodb.com/docs/manual/reference/command/aggregate.md#mongodb-dbcommand-dbcmd.aggregate) commands.

Query settings have more functionality and are preferred over deprecated [index filters.](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-index-filters)

To remove query settings, use [`removeQuerySettings`](https://www.mongodb.com/docs/manual/reference/command/removeQuerySettings.md#mongodb-dbcommand-dbcmd.removeQuerySettings). To obtain the query settings, use a [`$querySettings`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/querySettings.md#mongodb-pipeline-pipe.-querySettings) stage in an aggregation pipeline.

## Examples

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

```javascript
db.inventory.insertMany( [
   { _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" ] }
] )
```

### Return Distinct Values for a Field

The following example returns distinct values for the `dept` field:

```javascript
db.inventory.distinct( "dept" )
```

The operation returns:

```javascript
[ "A", "B" ]
```

### Return Distinct Values for an Embedded Field

The following example returns distinct values for the embedded `item.sku` field:

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

The operation returns:

```javascript
[ "111", "222", "333" ]
```

**See also:**

[Dot Notation](https://www.mongodb.com/docs/manual/core/document.md#std-label-document-dot-notation) for information on accessing fields within embedded documents

### Return Distinct Values for an Array Field

The following example returns distinct values for the `sizes` array field:

```javascript
db.inventory.distinct( "sizes" )
```

The operation returns:

```javascript
[ "M", "S", "L" ]
```

For information on `distinct()` and array fields, see the [Behavior](https://www.mongodb.com/docs/manual/reference/method/db.collection.distinct.md#std-label-distinct-method-behavior-array) section.

### Specify Query with `distinct`

The following example returns distinct values for the embedded `item.sku` field where `dept` equals `"A"`:

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

The operation returns:

```javascript
[ "111", "333" ]
```

### Specify a Collation

[Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-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:

```javascript
db.myColl.insertMany( [
   { _id: 1, category: "café", status: "A" },
   { _id: 2, category: "cafe", status: "a" },
   { _id: 3, category: "cafE", status: "a" }
] )
```

The following aggregation operation includes the [Collation](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation) option:

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

For descriptions on the collation fields, see [Collation Document.](https://www.mongodb.com/docs/manual/reference/collation.md#std-label-collation-document-fields)