- 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 a subdocument 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. 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 Covering a 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: