- Reference >
- Database Commands >
- Aggregation Commands >
- distinct
distinct¶
On this page
Definition¶
-
distinct
¶ Finds the distinct values for a specified field across a single collection.
distinct
returns a document that contains an array of the distinct values. The return document also contains an embedded document with query statistics and the query plan.The command takes the following form:
The command contains the following fields:
Field Type Description distinct
string The name of the collection to query for distinct values. key
string The field for which to return distinct values. query
document Optional. A query that specifies the documents from which to retrieve the distinct values. readConcern
document Optional. Specifies the read concern. The default level is
"local"
.To use a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.To ensure that a single thread can read its own writes, use
"majority"
read concern and"majority"
write concern against the primary of the replica set.New in version 3.2.
MongoDB also provides the shell wrapper method
db.collection.distinct()
for thedistinct
command. Additionally, many MongoDB drivers also provide a wrapper method. Refer to the specific driver documentation.
Behavior¶
Array Fields¶
If the value of the specified field
is an array,
distinct
considers each element of the array
as a separate value.
For instance, if a field has as its value [ 1, [1], 1 ]
, then
distinct
considers 1
, [1]
, and 1
as separate values.
For an example, see Return Distinct Values for an Array Field.
Index Use¶
When possible, distinct
operations can use indexes.
Indexes can also cover
distinct
operations. See Covered Query for more information
on queries covered by indexes.
Examples¶
The examples use the inventory
collection that contains the
following documents:
Return Distinct Values for a Field¶
The following example returns the distinct values for the field
dept
from all documents in the inventory
collection:
The command returns a document with a field named values
that
contains the distinct dept
values:
Return Distinct Values for an Embedded Field¶
The following example returns the distinct values for the field
sku
, embedded in the item
field, from all documents in the
inventory
collection:
The command returns a document with a field named values
that
contains the distinct sku
values:
See also
Dot Notation for information on accessing fields within embedded documents
Return Distinct Values for an Array Field¶
The following example returns the distinct values for the field
sizes
from all documents in the inventory
collection:
The command returns a document with a field named values
that
contains the distinct sizes
values:
For information on distinct
and array fields, see the
Behavior section.
Specify Query with distinct
¶
The following example returns the distinct values for the field
sku
, embedded in the item
field, from the documents whose
dept
is equal to "A"
:
The command returns a document with a field named values
that
contains the distinct sku
values:
Override Default Read Concern¶
To override the default read concern level of "local"
,
use the readConcern
option.
The following operation on a replica set specifies a
Read Concern of "majority"
to read the
most recent copy of the data confirmed as having been written to a
majority of the nodes.
Note
To use a read concern level of
"majority"
, you must use the WiredTiger storage engine and start themongod
instances with the--enableMajorityReadConcern
command line option (or thereplication.enableMajorityReadConcern
setting if using a configuration file).Only replica sets using
protocol version 1
support"majority"
read concern. Replica sets running protocol version 0 do not support"majority"
read concern.Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.
To ensure that a single thread can read its own writes, use
"majority"
read concern and "majority"
write concern against the primary of the replica set.