- Reference >
- Database Commands >
- Aggregation Commands >
- aggregate
aggregate¶
On this page
- aggregate¶
Performs aggregation operation using the aggregation pipeline. The pipeline allows users to process data from a collection with a sequence of stage-based manipulations.
The command has following syntax:
在 3.4 版更改.
{ aggregate: "<collection>", pipeline: [ <stage>, <...> ], explain: <boolean>, allowDiskUse: <boolean>, cursor: <document>, bypassDocumentValidation: <boolean>, readConcern: <document>, collation: <document> }
The aggregate command takes the following fields as arguments:
Field Type Description aggregate string The name of the collection to as the input for the aggregation pipeline. pipeline array An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline. explain boolean Optional. Specifies to return the information on the processing of the pipeline.
2.6 新版功能.
allowDiskUse boolean Optional. Enables writing to temporary files. When set to true, aggregation stages can write data to the _tmp subdirectory in the dbPath directory.
2.6 新版功能.
cursor document Specify a document that contains options that control the creation of the cursor object.
在 3.4 版更改: MongoDB 3.4 deprecates the use of aggregate command without the cursor option, unless the pipeline includes the explain option. When returning aggregation results inline using the aggregate command, specify the cursor option using the default batch size cursor: {} or specify the batch size in the cursor option cursor: { batchSize: <num> }.
2.6 新版功能.
bypassDocumentValidation boolean Optional. Available only if you specify the $out aggregation operator.
Enables aggregate to bypass document validation during the operation. This lets you insert documents that do not meet the validation requirements.
3.2 新版功能.
readConcern document Optional. Specifies the read concern. The option has the following syntax:
readConcern: { level: <value> }
Possible read concern values are:
- "local". This is the default read concern level.
- "majority". Available for replica sets that use WiredTiger storage engine.
- "linearizable". Available for read operations on the primary only.
For more formation on the read concern levels, see Read Concern Levels.
collation document Optional.
Specifies the collation to use for the operation.
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.
If the collation is unspecified but the collection has a default collation (see 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.
3.4 新版功能.
在 3.4 版更改: MongoDB 3.4 deprecates the use of aggregate command without the cursor option, unless the pipeline includes the explain option. When returning aggregation results inline using the aggregate command, specify the cursor option using the default batch size cursor: {} or specify the batch size in the cursor option cursor: { batchSize: <num> }.
在 2.6 版更改: aggregation pipeline introduces the $out operator to allow aggregate command to store results to a collection.
For more information about the aggregation pipeline 聚合管道, 聚合指南, and 聚合管道的限制.
Example¶
在 3.4 版更改: MongoDB 3.4 deprecates the use of aggregate command without the cursor option, unless the pipeline includes the explain option. When returning aggregation results inline using the aggregate command, specify the cursor option using the default batch size cursor: {} or specify the batch size in the cursor option cursor: { batchSize: <num> }.
Rather than run the aggregate command directly, most users should use the db.collection.aggregate() helper provided in the mongo shell or the equivalent helper in their driver. In 2.6 and later, the db.collection.aggregate() helper always returns a cursor.
Except for the first example which demonstrates the command syntax, the examples in this page use the db.collection.aggregate() helper.
Aggregate Data with Multi-Stage Pipeline¶
A collection articles contains documents such as the following:
{
_id: ObjectId("52769ea0f3dc6ead47c9a1b2"),
author: "abc123",
title: "zzz",
tags: [ "programming", "database", "mongodb" ]
}
The following example performs an aggregate operation on the articles collection to calculate the count of each distinct element in the tags array that appears in the collection.
db.runCommand( {
aggregate: "articles",
pipeline: [
{ $project: { tags: 1 } },
{ $unwind: "$tags" },
{ $group: { _id: "$tags", count: { $sum : 1 } } }
],
cursor: { }
} )
In the mongo shell, this operation can use the db.collection.aggregate() helper as in the following:
db.articles.aggregate( [
{ $project: { tags: 1 } },
{ $unwind: "$tags" },
{ $group: { _id: "$tags", count: { $sum : 1 } } }
] )
Return Information on the Aggregation Operation¶
The following aggregation operation sets the optional field explain to true to return information about the aggregation operation.
db.orders.aggregate([
{ $match: { status: "A" } },
{ $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
{ $sort: { total: -1 } }
],
{ explain: true }
)
注解
The explain output is subject to change between releases.
参见
db.collection.aggregate() method
Aggregate Data using External Sort¶
Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set allowDiskUse option to true to enable writing data to temporary files, as in the following example:
db.stocks.aggregate( [
{ $project : { cusip: 1, date: 1, price: 1, _id: 0 } },
{ $sort : { cusip : 1, date: 1 } }
],
{ allowDiskUse: true }
)
Aggregate Data Specifying Batch Size¶
To specify an initial batch size, specify the batchSize in the cursor field, as in the following example:
db.orders.aggregate( [
{ $match: { status: "A" } },
{ $group: { _id: "$cust_id", total: { $sum: "$amount" } } },
{ $sort: { total: -1 } },
{ $limit: 2 }
],
{ cursor: { batchSize: 0 } }
)
The {batchSize: 0 } document specifies the size of the initial batch size only. Specify subsequent batch sizes to OP_GET_MORE operations as with other MongoDB cursors. A batchSize of 0 means an empty first batch and is useful if you want to quickly get back a cursor or failure message, without doing significant server-side work.
Specify a Collation¶
3.4 新版功能.
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 Collation option:
db.myColl.aggregate(
[ { $match: { status: "A" } }, { $group: { _id: "$category", count: { $sum: 1 } } } ],
{ collation: { locale: "fr", strength: 1 } }
);
For descriptions on the collation fields, see Collation Document.
Override Default Read Concern¶
To override the default read concern level of "local", use the readConcern option. The getMore command uses the readConcern level specified in the originating aggregate command.s
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.
重要
- To use read concern level of "majority",
- you must start the mongod instances with the --enableMajorityReadConcern command line option (or the replication.enableMajorityReadConcern set to true if using a configuration file).
- replica sets must use WiredTiger storage engine and election protocol version 1.
- To use a read concern level of "majority", you cannot include the $out stage.
- 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.
db.restaurants.aggregate(
[ { $match: { rating: { $lt: 5 } } } ],
{ readConcern: { level: "majority" } }
)
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.