in an embedded document or in an array, use dot notation.
+ -
+ name: partitionByFields
+ type:
+ - array # of string
+ optional: true
+ description: |
+ The field(s) that will be used as the partition keys.
+ -
+ name: range
+ type:
+ - object # Range
+ description: |
+ Specification for range based densification.
+tests:
+ -
+ name: 'Densify Time Series Data'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/#densify-time-series-data'
+ pipeline:
+ -
+ $densify:
+ field: 'timestamp'
+ range:
+ step: 1
+ unit: 'hour'
+ bounds:
+ - !bson_utcdatetime '2021-05-18T00:00:00.000Z'
+ - !bson_utcdatetime '2021-05-18T08:00:00.000Z'
+ -
+ name: 'Densifiction with Partitions'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/#densifiction-with-partitions'
+ pipeline:
+ -
+ $densify:
+ field: 'altitude'
+ partitionByFields:
+ - 'variety'
+ range:
+ bounds: 'full'
+ step: 200
diff --git a/generator/config/stage/documents.yaml b/generator/config/stage/documents.yaml
new file mode 100644
index 000000000..666468da8
--- /dev/null
+++ b/generator/config/stage/documents.yaml
@@ -0,0 +1,53 @@
+# $schema: ../schema.json
+name: $documents
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/'
+type:
+ - stage
+encode: single
+description: |
+ Returns literal documents from input values.
+arguments:
+ -
+ name: documents
+ type:
+ - resolvesToArray # of object
+ description: |
+ $documents accepts any valid expression that resolves to an array of objects. This includes:
+ - system variables, such as $$NOW or $$SEARCH_META
+ - $let expressions
+ - variables in scope from $lookup expressions
+ Expressions that do not resolve to a current document, like $myField or $$ROOT, will result in an error.
+tests:
+ -
+ name: 'Test a Pipeline Stage'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/#test-a-pipeline-stage'
+ pipeline:
+ -
+ $documents:
+ - { x: 10 }
+ - { x: 2 }
+ - { x: 5 }
+ -
+ $bucketAuto:
+ groupBy: '$x'
+ buckets: 4
+ -
+ name: 'Use a $documents Stage in a $lookup Stage'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/#use-a--documents-stage-in-a--lookup-stage'
+ pipeline:
+ -
+ $match: {}
+ -
+ $lookup:
+ localField: 'zip'
+ foreignField: 'zip_id'
+ as: 'city_state'
+ pipeline:
+ -
+ $documents:
+ -
+ zip_id: 94301
+ name: 'Palo Alto, CA'
+ -
+ zip_id: 10019
+ name: 'New York, NY'
diff --git a/generator/config/stage/facet.yaml b/generator/config/stage/facet.yaml
new file mode 100644
index 000000000..013163c2a
--- /dev/null
+++ b/generator/config/stage/facet.yaml
@@ -0,0 +1,51 @@
+# $schema: ../schema.json
+name: $facet
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/'
+type:
+ - stage
+encode: single
+description: |
+ Processes multiple aggregation pipelines within a single stage on the same set of input documents. Enables the creation of multi-faceted aggregations capable of characterizing data across multiple dimensions, or facets, in a single stage.
+arguments:
+ -
+ name: facet
+ type:
+ - pipeline
+ variadic: object
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/facet/#example'
+ pipeline:
+ -
+ $facet:
+ categorizedByTags:
+ -
+ # The builder uses the verbose form of the $unwind operator
+ # $unwind: '$tags'
+ $unwind:
+ path: '$tags'
+ -
+ $sortByCount: '$tags'
+ categorizedByPrice:
+ -
+ $match:
+ price:
+ # The example uses an int, but the builder requires a bool
+ # $exists: 1
+ $exists: true
+ -
+ $bucket:
+ groupBy: '$price'
+ boundaries: [0, 150, 200, 300, 400]
+ default: 'Other'
+ output:
+ count:
+ $sum: 1
+ titles:
+ $push: '$title'
+ categorizedByYears(Auto):
+ -
+ $bucketAuto:
+ groupBy: '$year'
+ buckets: 4
diff --git a/generator/config/stage/fill.yaml b/generator/config/stage/fill.yaml
new file mode 100644
index 000000000..d3a9ec390
--- /dev/null
+++ b/generator/config/stage/fill.yaml
@@ -0,0 +1,110 @@
+# $schema: ../schema.json
+name: $fill
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/'
+type:
+ - stage
+encode: object
+description: |
+ Populates null and missing field values within documents.
+arguments:
+ -
+ name: partitionBy
+ type:
+ - object # of expression
+ - string
+ optional: true
+ description: |
+ Specifies an expression to group the documents. In the $fill stage, a group of documents is known as a partition.
+ If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection.
+ partitionBy and partitionByFields are mutually exclusive.
+ -
+ name: partitionByFields
+ type:
+ - array # of string
+ optional: true
+ description: |
+ Specifies an array of fields as the compound key to group the documents. In the $fill stage, each group of documents is known as a partition.
+ If you omit partitionBy and partitionByFields, $fill uses one partition for the entire collection.
+ partitionBy and partitionByFields are mutually exclusive.
+ -
+ name: sortBy
+ type:
+ - object # SortSpec
+ optional: true
+ description: |
+ Specifies the field or fields to sort the documents within each partition. Uses the same syntax as the $sort stage.
+ -
+ name: output
+ type:
+ - object # of object{value:expression} or object{method:string}>
+ description: |
+ Specifies an object containing each field for which to fill missing values. You can specify multiple fields in the output object.
+ The object name is the name of the field to fill. The object value specifies how the field is filled.
+tests:
+ -
+ name: 'Fill Missing Field Values with a Constant Value'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/#fill-missing-field-values-with-a-constant-value'
+ pipeline:
+ -
+ $fill:
+ output:
+ bootsSold:
+ value: 0
+ sandalsSold:
+ value: 0
+ sneakersSold:
+ value: 0
+ -
+ name: 'Fill Missing Field Values with Linear Interpolation'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/#fill-missing-field-values-with-linear-interpolation'
+ pipeline:
+ -
+ $fill:
+ sortBy:
+ time: 1
+ output:
+ price:
+ method: 'linear'
+ -
+ name: 'Fill Missing Field Values Based on the Last Observed Value'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/#fill-missing-field-values-based-on-the-last-observed-value'
+ pipeline:
+ -
+ $fill:
+ sortBy:
+ date: 1
+ output:
+ score:
+ method: 'locf'
+ -
+ name: 'Fill Data for Distinct Partitions'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/#fill-data-for-distinct-partitions'
+ pipeline:
+ -
+ $fill:
+ sortBy:
+ date: 1
+ partitionBy:
+ restaurant: '$restaurant'
+ output:
+ score:
+ method: 'locf'
+ -
+ name: 'Indicate if a Field was Populated Using $fill'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/#indicate-if-a-field-was-populated-using--fill'
+ pipeline:
+ -
+ $set:
+ valueExisted:
+ $ifNull:
+ -
+ $toBool:
+ $toString: '$score'
+ - false
+ -
+ $fill:
+ sortBy:
+ date: 1
+ output:
+ score:
+ method: 'locf'
diff --git a/generator/config/stage/geoNear.yaml b/generator/config/stage/geoNear.yaml
new file mode 100644
index 000000000..c9968509d
--- /dev/null
+++ b/generator/config/stage/geoNear.yaml
@@ -0,0 +1,160 @@
+# $schema: ../schema.json
+name: $geoNear
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/'
+type:
+ - stage
+encode: object
+description: |
+ Returns an ordered stream of documents based on the proximity to a geospatial point. Incorporates the functionality of $match, $sort, and $limit for geospatial data. The output documents include an additional distance field and can include a location identifier field.
+arguments:
+ -
+ name: distanceField
+ type:
+ - string
+ description: |
+ The output field that contains the calculated distance. To specify a field within an embedded document, use dot notation.
+ -
+ name: distanceMultiplier
+ type:
+ - number
+ optional: true
+ description: |
+ The factor to multiply all distances returned by the query. For example, use the distanceMultiplier to convert radians, as returned by a spherical query, to kilometers by multiplying by the radius of the Earth.
+ -
+ name: includeLocs
+ type:
+ - string
+ optional: true
+ description: |
+ This specifies the output field that identifies the location used to calculate the distance. This option is useful when a location field contains multiple locations. To specify a field within an embedded document, use dot notation.
+ -
+ name: key
+ type:
+ - string
+ optional: true
+ description: |
+ Specify the geospatial indexed field to use when calculating the distance.
+ -
+ name: maxDistance
+ type:
+ - number
+ optional: true
+ description: |
+ The maximum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall within the specified distance from the center point.
+ Specify the distance in meters if the specified point is GeoJSON and in radians if the specified point is legacy coordinate pairs.
+ -
+ name: minDistance
+ type:
+ - number
+ optional: true
+ description: |
+ The minimum distance from the center point that the documents can be. MongoDB limits the results to those documents that fall outside the specified distance from the center point.
+ Specify the distance in meters for GeoJSON data and in radians for legacy coordinate pairs.
+ -
+ name: near
+ type:
+ - object # GeoPoint
+ - resolvesToObject
+ description: |
+ The point for which to find the closest documents.
+ -
+ name: query
+ type:
+ - query
+ optional: true
+ description: |
+ Limits the results to the documents that match the query. The query syntax is the usual MongoDB read operation query syntax.
+ You cannot specify a $near predicate in the query field of the $geoNear stage.
+ -
+ name: spherical
+ type:
+ - bool
+ optional: true
+ description: |
+ Determines how MongoDB calculates the distance between two points:
+ - When true, MongoDB uses $nearSphere semantics and calculates distances using spherical geometry.
+ - When false, MongoDB uses $near semantics: spherical geometry for 2dsphere indexes and planar geometry for 2d indexes.
+ Default: false.
+tests:
+ -
+ name: 'Maximum Distance'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/#maximum-distance'
+ pipeline:
+ -
+ $geoNear:
+ near:
+ type: 'Point'
+ coordinates:
+ - -73.99279
+ - 40.719296
+ distanceField: 'dist.calculated'
+ maxDistance: 2
+ query:
+ category: 'Parks'
+ includeLocs: 'dist.location'
+ spherical: true
+ -
+ name: 'Minimum Distance'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/#minimum-distance'
+ pipeline:
+ -
+ $geoNear:
+ near:
+ type: 'Point'
+ coordinates:
+ - -73.99279
+ - 40.719296
+ distanceField: 'dist.calculated'
+ minDistance: 2
+ query:
+ category: 'Parks'
+ includeLocs: 'dist.location'
+ spherical: true
+ -
+ name: 'with the let option'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/#-geonear-with-the-let-option'
+ pipeline:
+ -
+ $geoNear:
+ near: '$$pt'
+ distanceField: 'distance'
+ maxDistance: 2
+ query:
+ category: 'Parks'
+ includeLocs: 'dist.location'
+ spherical: true
+ -
+ name: 'with Bound let Option'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/#-geonear-with-bound-let-option'
+ pipeline:
+ -
+ $lookup:
+ from: 'places'
+ let:
+ pt: '$location'
+ pipeline:
+ -
+ $geoNear:
+ near: '$$pt'
+ distanceField: 'distance'
+ as: 'joinedField'
+ -
+ $match:
+ name: 'Sara D. Roosevelt Park'
+ -
+ name: 'Specify Which Geospatial Index to Use'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/geoNear/#specify-which-geospatial-index-to-use'
+ pipeline:
+ -
+ $geoNear:
+ near:
+ type: 'Point'
+ coordinates:
+ - -73.98142
+ - 40.71782
+ key: 'location'
+ distanceField: 'dist.calculated'
+ query:
+ category: 'Parks'
+ -
+ $limit: 5
diff --git a/generator/config/stage/graphLookup.yaml b/generator/config/stage/graphLookup.yaml
new file mode 100644
index 000000000..ae220620b
--- /dev/null
+++ b/generator/config/stage/graphLookup.yaml
@@ -0,0 +1,108 @@
+# $schema: ../schema.json
+name: $graphLookup
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/'
+type:
+ - stage
+encode: object
+description: |
+ Performs a recursive search on a collection. To each output document, adds a new array field that contains the traversal results of the recursive search for that document.
+arguments:
+ -
+ name: from
+ type:
+ - string
+ description: |
+ Target collection for the $graphLookup operation to search, recursively matching the connectFromField to the connectToField. The from collection must be in the same database as any other collections used in the operation.
+ Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded.
+ -
+ name: startWith
+ type:
+ - expression
+ - array
+ description: |
+ Expression that specifies the value of the connectFromField with which to start the recursive search. Optionally, startWith may be array of values, each of which is individually followed through the traversal process.
+ -
+ name: connectFromField
+ type:
+ - string
+ description: |
+ Field name whose value $graphLookup uses to recursively match against the connectToField of other documents in the collection. If the value is an array, each element is individually followed through the traversal process.
+ -
+ name: connectToField
+ type:
+ - string
+ description: |
+ Field name in other documents against which to match the value of the field specified by the connectFromField parameter.
+ -
+ name: as
+ type:
+ - string
+ description: |
+ Name of the array field added to each output document. Contains the documents traversed in the $graphLookup stage to reach the document.
+ -
+ name: maxDepth
+ type:
+ - int
+ optional: true
+ description: |
+ Non-negative integral number specifying the maximum recursion depth.
+ -
+ name: depthField
+ type:
+ - string
+ optional: true
+ description: |
+ Name of the field to add to each traversed document in the search path. The value of this field is the recursion depth for the document, represented as a NumberLong. Recursion depth value starts at zero, so the first lookup corresponds to zero depth.
+ -
+ name: restrictSearchWithMatch
+ type:
+ - query
+ optional: true
+ description: |
+ A document specifying additional conditions for the recursive search. The syntax is identical to query filter syntax.
+tests:
+ -
+ name: 'Within a Single Collection'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/#within-a-single-collection'
+ pipeline:
+ -
+ $graphLookup:
+ from: 'employees'
+ startWith: '$reportsTo'
+ connectFromField: 'reportsTo'
+ connectToField: 'name'
+ as: 'reportingHierarchy'
+ -
+ name: 'Across Multiple Collections'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/#across-multiple-collections'
+ pipeline:
+ -
+ $graphLookup:
+ from: 'airports'
+ startWith: '$nearestAirport'
+ connectFromField: 'connects'
+ connectToField: 'airport'
+ maxDepth: 2
+ depthField: 'numConnections'
+ as: 'destinations'
+ -
+ name: 'With a Query Filter'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/graphLookup/#with-a-query-filter'
+ pipeline:
+ -
+ $match:
+ name: 'Tanya Jordan'
+ -
+ $graphLookup:
+ from: 'people'
+ startWith: '$friends'
+ connectFromField: 'friends'
+ connectToField: 'name'
+ as: 'golfers'
+ restrictSearchWithMatch:
+ hobbies: 'golf'
+ -
+ $project:
+ name: 1
+ friends: 1
+ connections who play golf: '$golfers.name'
diff --git a/generator/config/stage/group.yaml b/generator/config/stage/group.yaml
new file mode 100644
index 000000000..3e93588e9
--- /dev/null
+++ b/generator/config/stage/group.yaml
@@ -0,0 +1,122 @@
+# $schema: ../schema.json
+name: $group
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/'
+type:
+ - stage
+encode: group
+description: |
+ Groups input documents by a specified identifier expression and applies the accumulator expression(s), if specified, to each group. Consumes all input documents and outputs one document per each distinct group. The output documents only contain the identifier field and, if specified, accumulated fields.
+arguments:
+ -
+ name: _id
+ type:
+ - expression
+ description: |
+ The _id expression specifies the group key. If you specify an _id value of null, or any other constant value, the $group stage returns a single document that aggregates values across all of the input documents.
+ -
+ name: field
+ type:
+ - accumulator
+ variadic: object
+ variadicMin: 0
+ description: |
+ Computed using the accumulator operators.
+tests:
+ -
+ name: 'Count the Number of Documents in a Collection'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#count-the-number-of-documents-in-a-collection'
+ pipeline:
+ -
+ $group:
+ _id: ~
+ count:
+ $count: {}
+ -
+ name: 'Retrieve Distinct Values'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#retrieve-distinct-values'
+ pipeline:
+ -
+ $group:
+ _id: '$item'
+ -
+ name: 'Group by Item Having'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#group-by-item-having'
+ pipeline:
+ -
+ $group:
+ _id: '$item'
+ totalSaleAmount:
+ $sum:
+ $multiply:
+ - '$price'
+ - '$quantity'
+ -
+ $match:
+ totalSaleAmount:
+ $gte: 100
+ -
+ name: 'Calculate Count Sum and Average'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#calculate-count--sum--and-average'
+ pipeline:
+ -
+ $match:
+ date:
+ $gte: !bson_utcdatetime '2014-01-01'
+ $lt: !bson_utcdatetime '2015-01-01'
+ -
+ $group:
+ _id:
+ $dateToString:
+ format: '%Y-%m-%d'
+ date: '$date'
+ totalSaleAmount:
+ $sum:
+ $multiply:
+ - '$price'
+ - '$quantity'
+ averageQuantity:
+ $avg: '$quantity'
+ count:
+ $sum: 1
+ -
+ $sort:
+ totalSaleAmount: -1
+ -
+ name: 'Group by null'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#group-by-null'
+ pipeline:
+ -
+ $group:
+ _id: ~
+ totalSaleAmount:
+ $sum:
+ $multiply:
+ - '$price'
+ - '$quantity'
+ averageQuantity:
+ $avg: '$quantity'
+ count:
+ $sum: 1
+ -
+ name: 'Pivot Data'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#pivot-data'
+ pipeline:
+ -
+ $group:
+ _id: '$author'
+ books:
+ $push: '$title'
+ -
+ name: 'Group Documents by author'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/group/#group-documents-by-author'
+ pipeline:
+ -
+ $group:
+ _id: '$author'
+ books:
+ $push: '$$ROOT'
+ -
+ $addFields:
+ totalCopies:
+ # $sum: '$books.copies'
+ $sum: ['$books.copies']
diff --git a/generator/config/stage/indexStats.yaml b/generator/config/stage/indexStats.yaml
new file mode 100644
index 000000000..178b209d8
--- /dev/null
+++ b/generator/config/stage/indexStats.yaml
@@ -0,0 +1,15 @@
+# $schema: ../schema.json
+name: $indexStats
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/'
+type:
+ - stage
+encode: object
+description: |
+ Returns statistics regarding the use of each index for the collection.
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexStats/#example'
+ pipeline:
+ -
+ $indexStats: {}
diff --git a/generator/config/stage/limit.yaml b/generator/config/stage/limit.yaml
new file mode 100644
index 000000000..fff391a01
--- /dev/null
+++ b/generator/config/stage/limit.yaml
@@ -0,0 +1,20 @@
+# $schema: ../schema.json
+name: $limit
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/'
+type:
+ - stage
+encode: single
+description: |
+ Passes the first n documents unmodified to the pipeline where n is the specified limit. For each input document, outputs either one document (for the first n documents) or zero documents (after the first n documents).
+arguments:
+ -
+ name: limit
+ type:
+ - int
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/limit/#example'
+ pipeline:
+ -
+ $limit: 5
diff --git a/generator/config/stage/listLocalSessions.yaml b/generator/config/stage/listLocalSessions.yaml
new file mode 100644
index 000000000..50dccc30e
--- /dev/null
+++ b/generator/config/stage/listLocalSessions.yaml
@@ -0,0 +1,47 @@
+# $schema: ../schema.json
+name: $listLocalSessions
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/'
+type:
+ - stage
+encode: object
+description: |
+ Lists all active sessions recently in use on the currently connected mongos or mongod instance. These sessions may have not yet propagated to the system.sessions collection.
+arguments:
+ -
+ name: users
+ type:
+ - array
+ optional: true
+ description: |
+ Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users.
+ -
+ name: allUsers
+ type:
+ - bool
+ optional: true
+ description: |
+ Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster.
+tests:
+ -
+ name: 'List All Local Sessions'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/#list-all-local-sessions'
+ pipeline:
+ -
+ $listLocalSessions:
+ allUsers: true
+ -
+ name: 'List All Local Sessions for the Specified Users'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/#list-all-local-sessions-for-the-specified-users'
+ pipeline:
+ -
+ $listLocalSessions:
+ users:
+ -
+ user: 'myAppReader'
+ db: 'test'
+ -
+ name: 'List All Local Sessions for the Current User'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listLocalSessions/#list-all-local-sessions-for-the-current-user'
+ pipeline:
+ -
+ $listLocalSessions: {}
diff --git a/generator/config/stage/listSampledQueries.yaml b/generator/config/stage/listSampledQueries.yaml
new file mode 100644
index 000000000..f767f0d04
--- /dev/null
+++ b/generator/config/stage/listSampledQueries.yaml
@@ -0,0 +1,29 @@
+# $schema: ../schema.json
+name: $listSampledQueries
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/'
+type:
+ - stage
+encode: object
+description: |
+ Lists sampled queries for all collections or a specific collection.
+arguments:
+ -
+ name: namespace
+ type:
+ - string
+ optional: true
+tests:
+ -
+ name: 'List Sampled Queries for All Collections'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/#list-sampled-queries-for-all-collections'
+ pipeline:
+ -
+ $listSampledQueries: {}
+
+ -
+ name: 'List Sampled Queries for A Specific Collection'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSampledQueries/#list-sampled-queries-for-a-specific-collection'
+ pipeline:
+ -
+ $listSampledQueries:
+ namespace: 'social.post'
diff --git a/generator/config/stage/listSearchIndexes.yaml b/generator/config/stage/listSearchIndexes.yaml
new file mode 100644
index 000000000..afc4f6d05
--- /dev/null
+++ b/generator/config/stage/listSearchIndexes.yaml
@@ -0,0 +1,44 @@
+# $schema: ../schema.json
+name: $listSearchIndexes
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/'
+type:
+ - stage
+encode: object
+description: |
+ Returns information about existing Atlas Search indexes on a specified collection.
+arguments:
+ -
+ name: id
+ type:
+ - string
+ optional: true
+ description: |
+ The id of the index to return information about.
+ -
+ name: name
+ type:
+ - string
+ optional: true
+ description: |
+ The name of the index to return information about.
+tests:
+ -
+ name: 'Return All Search Indexes'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/#return-all-search-indexes'
+ pipeline:
+ -
+ $listSearchIndexes: {}
+ -
+ name: 'Return a Single Search Index by Name'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/#return-a-single-search-index-by-name'
+ pipeline:
+ -
+ $listSearchIndexes:
+ name: 'synonym-mappings'
+ -
+ name: 'Return a Single Search Index by id'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSearchIndexes/#return-a-single-search-index-by-id'
+ pipeline:
+ -
+ $listSearchIndexes:
+ id: '6524096020da840844a4c4a7'
diff --git a/generator/config/stage/listSessions.yaml b/generator/config/stage/listSessions.yaml
new file mode 100644
index 000000000..efb56de05
--- /dev/null
+++ b/generator/config/stage/listSessions.yaml
@@ -0,0 +1,48 @@
+# $schema: ../schema.json
+name: $listSessions
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/'
+type:
+ - stage
+encode: object
+description: |
+ Lists all sessions that have been active long enough to propagate to the system.sessions collection.
+arguments:
+ -
+ name: users
+ type:
+ - array
+ optional: true
+ description: |
+ Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster to list sessions for other users.
+ -
+ name: allUsers
+ type:
+ - bool
+ optional: true
+ description: |
+ Returns all sessions for all users. If running with access control, the authenticated user must have privileges with listSessions action on the cluster.
+tests:
+ -
+ name: 'List All Sessions'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/#list-all-sessions'
+ pipeline:
+ -
+ $listSessions:
+ allUsers: true
+ -
+ name: 'List All Sessions for the Specified Users'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/#list-all-sessions-for-the-specified-users'
+ pipeline:
+ -
+ $listSessions:
+ users:
+ -
+ user: 'myAppReader'
+ db: 'test'
+ -
+ name: 'List All Sessions for the Current User'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/listSessions/#list-all-sessions-for-the-current-user'
+ pipeline:
+ -
+ $listSessions: {}
+
diff --git a/generator/config/stage/lookup.yaml b/generator/config/stage/lookup.yaml
new file mode 100644
index 000000000..b73770e47
--- /dev/null
+++ b/generator/config/stage/lookup.yaml
@@ -0,0 +1,165 @@
+# $schema: ../schema.json
+name: $lookup
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/'
+type:
+ - stage
+encode: object
+description: |
+ Performs a left outer join to another collection in the same database to filter in documents from the "joined" collection for processing.
+arguments:
+ -
+ name: from
+ type:
+ - string
+ optional: true
+ description: |
+ Specifies the collection in the same database to perform the join with.
+ from is optional, you can use a $documents stage in a $lookup stage instead. For an example, see Use a $documents Stage in a $lookup Stage.
+ Starting in MongoDB 5.1, the collection specified in the from parameter can be sharded.
+ -
+ name: localField
+ type:
+ - string
+ optional: true
+ description: |
+ Specifies the field from the documents input to the $lookup stage. $lookup performs an equality match on the localField to the foreignField from the documents of the from collection. If an input document does not contain the localField, the $lookup treats the field as having a value of null for matching purposes.
+ -
+ name: foreignField
+ type:
+ - string
+ optional: true
+ description: |
+ Specifies the field from the documents in the from collection. $lookup performs an equality match on the foreignField to the localField from the input documents. If a document in the from collection does not contain the foreignField, the $lookup treats the value as null for matching purposes.
+ -
+ name: let
+ type:
+ - object # of expression
+ optional: true
+ description: |
+ Specifies variables to use in the pipeline stages. Use the variable expressions to access the fields from the joined collection's documents that are input to the pipeline.
+ -
+ name: pipeline
+ type:
+ - pipeline
+ optional: true
+ description: |
+ Specifies the pipeline to run on the joined collection. The pipeline determines the resulting documents from the joined collection. To return all documents, specify an empty pipeline [].
+ The pipeline cannot include the $out stage or the $merge stage. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline.
+ The pipeline cannot directly access the joined document fields. Instead, define variables for the joined document fields using the let option and then reference the variables in the pipeline stages.
+ -
+ name: as
+ type:
+ - string
+ description: |
+ Specifies the name of the new array field to add to the input documents. The new array field contains the matching documents from the from collection. If the specified name already exists in the input document, the existing field is overwritten.
+tests:
+ -
+ name: 'Perform a Single Equality Join with $lookup'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#perform-a-single-equality-join-with--lookup'
+ pipeline:
+ -
+ $lookup:
+ from: 'inventory'
+ localField: 'item'
+ foreignField: 'sku'
+ as: 'inventory_docs'
+ -
+ name: 'Use $lookup with an Array'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#use--lookup-with-an-array'
+ pipeline:
+ -
+ $lookup:
+ from: 'members'
+ localField: 'enrollmentlist'
+ foreignField: 'name'
+ as: 'enrollee_info'
+ -
+ name: 'Use $lookup with $mergeObjects'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#use--lookup-with--mergeobjects'
+ pipeline:
+ -
+ $lookup:
+ from: 'items'
+ localField: 'item'
+ foreignField: 'item'
+ as: 'fromItems'
+ -
+ $replaceRoot:
+ newRoot:
+ $mergeObjects:
+ -
+ $arrayElemAt:
+ - '$fromItems'
+ - 0
+ - '$$ROOT'
+ -
+ $project:
+ fromItems: 0
+ -
+ name: 'Perform Multiple Joins and a Correlated Subquery with $lookup'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#perform-multiple-joins-and-a-correlated-subquery-with--lookup'
+ pipeline:
+ -
+ $lookup:
+ from: 'warehouses'
+ let:
+ order_item: '$item'
+ order_qty: '$ordered'
+ pipeline:
+ -
+ $match:
+ $expr:
+ $and:
+ -
+ $eq:
+ - '$stock_item'
+ - '$$order_item'
+ -
+ $gte:
+ - '$instock'
+ - '$$order_qty'
+ -
+ $project:
+ stock_item: 0
+ _id: 0
+ as: 'stockdata'
+ -
+ name: 'Perform an Uncorrelated Subquery with $lookup'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#perform-an-uncorrelated-subquery-with--lookup'
+ pipeline:
+ -
+ $lookup:
+ from: 'holidays'
+ pipeline:
+ -
+ $match:
+ year: 2018
+ -
+ $project:
+ _id: 0
+ date:
+ name: '$name'
+ date: '$date'
+ -
+ $replaceRoot:
+ newRoot: '$date'
+ as: 'holidays'
+ -
+ name: 'Perform a Concise Correlated Subquery with $lookup'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup/#perform-a-concise-correlated-subquery-with--lookup'
+ pipeline:
+ -
+ $lookup:
+ from: 'restaurants'
+ localField: 'restaurant_name'
+ foreignField: 'name'
+ let:
+ orders_drink: '$drink'
+ pipeline:
+ -
+ $match:
+ $expr:
+ $in:
+ - '$$orders_drink'
+ - '$beverages'
+ as: 'matches'
diff --git a/generator/config/stage/match.yaml b/generator/config/stage/match.yaml
new file mode 100644
index 000000000..ab0081fd0
--- /dev/null
+++ b/generator/config/stage/match.yaml
@@ -0,0 +1,40 @@
+# $schema: ../schema.json
+name: $match
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/'
+type:
+ - stage
+encode: single
+description: |
+ Filters the document stream to allow only matching documents to pass unmodified into the next pipeline stage. $match uses standard MongoDB queries. For each input document, outputs either one document (a match) or zero documents (no match).
+arguments:
+ -
+ name: query
+ type:
+ - query
+tests:
+ -
+ name: 'Equality Match'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/#equality-match'
+ pipeline:
+ -
+ $match:
+ author: 'dave'
+ -
+ name: 'Perform a Count'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/match/#perform-a-count'
+ pipeline:
+ -
+ $match:
+ $or:
+ -
+ score:
+ $gt: 70
+ $lt: 90
+ -
+ views:
+ $gte: 1000
+ -
+ $group:
+ _id: ~
+ count:
+ $sum: 1
diff --git a/generator/config/stage/merge.yaml b/generator/config/stage/merge.yaml
new file mode 100644
index 000000000..2e24ec74e
--- /dev/null
+++ b/generator/config/stage/merge.yaml
@@ -0,0 +1,180 @@
+# $schema: ../schema.json
+name: $merge
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/'
+type:
+ - stage
+encode: object
+description: |
+ Writes the resulting documents of the aggregation pipeline to a collection. The stage can incorporate (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom update pipeline) the results into an output collection. To use the $merge stage, it must be the last stage in the pipeline.
+ New in MongoDB 4.2.
+arguments:
+ -
+ name: into
+ type:
+ - string
+ - object # OutCollection
+ description: |
+ The output collection.
+ -
+ name: 'on'
+ type:
+ - string
+ - array # of string
+ optional: true
+ description: |
+ Field or fields that act as a unique identifier for a document. The identifier determines if a results document matches an existing document in the output collection.
+ -
+ name: let
+ type:
+ - object
+ optional: true
+ description: |
+ Specifies variables for use in the whenMatched pipeline.
+ -
+ name: whenMatched
+ type:
+ - string # WhenMatched
+ - pipeline
+ optional: true
+ description: |
+ The behavior of $merge if a result document and an existing document in the collection have the same value for the specified on field(s).
+ -
+ name: whenNotMatched
+ type:
+ - string # WhenNotMatched
+ optional: true
+ description: |
+ The behavior of $merge if a result document does not match an existing document in the out collection.
+tests:
+ -
+ name: 'On-Demand Materialized View Initial Creation'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#on-demand-materialized-view--initial-creation'
+ pipeline:
+ -
+ $group:
+ _id:
+ fiscal_year: '$fiscal_year'
+ dept: '$dept'
+ salaries:
+ $sum: '$salary'
+ -
+ $merge:
+ into:
+ db: 'reporting'
+ coll: 'budgets'
+ on: '_id'
+ whenMatched: 'replace'
+ whenNotMatched: 'insert'
+ -
+ name: 'On-Demand Materialized View Update Replace Data'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#on-demand-materialized-view--update-replace-data'
+ pipeline:
+ -
+ $match:
+ fiscal_year:
+ $gte: 2019
+ -
+ $group:
+ _id:
+ fiscal_year: '$fiscal_year'
+ dept: '$dept'
+ salaries:
+ $sum: '$salary'
+ -
+ $merge:
+ into:
+ db: 'reporting'
+ coll: 'budgets'
+ on: '_id'
+ whenMatched: 'replace'
+ whenNotMatched: 'insert'
+ -
+ name: 'Only Insert New Data'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#only-insert-new-data'
+ pipeline:
+ -
+ $match:
+ fiscal_year: 2019
+ -
+ $group:
+ _id:
+ fiscal_year: '$fiscal_year'
+ dept: '$dept'
+ employees:
+ $push: '$employee'
+ -
+ $project:
+ _id: 0
+ dept: '$_id.dept'
+ fiscal_year: '$_id.fiscal_year'
+ employees: 1
+ -
+ $merge:
+ into:
+ db: 'reporting'
+ coll: 'orgArchive'
+ on:
+ - 'dept'
+ - 'fiscal_year'
+ whenMatched: 'fail'
+ -
+ name: 'Merge Results from Multiple Collections'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#merge-results-from-multiple-collections'
+ pipeline:
+ -
+ $group:
+ _id: '$quarter'
+ purchased:
+ $sum: '$qty'
+ -
+ $merge:
+ into: 'quarterlyreport'
+ on: '_id'
+ whenMatched: 'merge'
+ whenNotMatched: 'insert'
+ -
+ name: 'Use the Pipeline to Customize the Merge'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#use-the-pipeline-to-customize-the-merge'
+ pipeline:
+ -
+ $match:
+ date:
+ $gte: !bson_utcdatetime '2019-05-07'
+ $lt: !bson_utcdatetime '2019-05-08'
+ -
+ $project:
+ _id:
+ $dateToString:
+ format: '%Y-%m'
+ date: '$date'
+ thumbsup: 1
+ thumbsdown: 1
+ -
+ $merge:
+ into: 'monthlytotals'
+ on: '_id'
+ whenMatched:
+ -
+ $addFields:
+ thumbsup:
+ $add:
+ - '$thumbsup'
+ - '$$new.thumbsup'
+ thumbsdown:
+ $add:
+ - '$thumbsdown'
+ - '$$new.thumbsdown'
+ whenNotMatched: 'insert'
+ -
+ name: 'Use Variables to Customize the Merge'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/merge/#use-variables-to-customize-the-merge'
+ pipeline:
+ -
+ $merge:
+ into: 'cakeSales'
+ let:
+ year: '2020'
+ whenMatched:
+ -
+ $addFields:
+ salesYear: '$$year'
diff --git a/generator/config/stage/out.yaml b/generator/config/stage/out.yaml
new file mode 100644
index 000000000..c4cc7948d
--- /dev/null
+++ b/generator/config/stage/out.yaml
@@ -0,0 +1,40 @@
+# $schema: ../schema.json
+name: $out
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/'
+type:
+ - stage
+encode: single
+description: |
+ Writes the resulting documents of the aggregation pipeline to a collection. To use the $out stage, it must be the last stage in the pipeline.
+arguments:
+ - name: coll
+ type:
+ - string
+ - object # OutCollection
+ description: |
+ Target database name to write documents from $out to.
+tests:
+ -
+ name: 'Output to Same Database'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/#output-to-same-database'
+ pipeline:
+ -
+ $group:
+ _id: '$author'
+ books:
+ $push: '$title'
+ -
+ $out: 'authors'
+ -
+ name: 'Output to a Different Database'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/out/#output-to-a-different-database'
+ pipeline:
+ -
+ $group:
+ _id: '$author'
+ books:
+ $push: '$title'
+ -
+ $out:
+ db: 'reporting'
+ coll: 'authors'
diff --git a/generator/config/stage/planCacheStats.yaml b/generator/config/stage/planCacheStats.yaml
new file mode 100644
index 000000000..995caa74e
--- /dev/null
+++ b/generator/config/stage/planCacheStats.yaml
@@ -0,0 +1,24 @@
+# $schema: ../schema.json
+name: $planCacheStats
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/'
+type:
+ - stage
+encode: object
+description: |
+ Returns plan cache information for a collection.
+tests:
+ -
+ name: 'Return Information for All Entries in the Query Cache'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/#return-information-for-all-entries-in-the-query-cache'
+ pipeline:
+ -
+ $planCacheStats: {}
+ -
+ name: 'Find Cache Entry Details for a Query Hash'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/planCacheStats/#find-cache-entry-details-for-a-query-hash'
+ pipeline:
+ -
+ $planCacheStats: {}
+ -
+ $match:
+ planCacheKey: 'B1435201'
diff --git a/generator/config/stage/project.yaml b/generator/config/stage/project.yaml
new file mode 100644
index 000000000..c7b0f7d59
--- /dev/null
+++ b/generator/config/stage/project.yaml
@@ -0,0 +1,124 @@
+# $schema: ../schema.json
+name: $project
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/'
+type:
+ - stage
+encode: single
+description: |
+ Reshapes each document in the stream, such as by adding new fields or removing existing fields. For each input document, outputs one document.
+arguments:
+ -
+ name: specification
+ type:
+ - expression
+ variadic: object
+tests:
+ -
+ name: 'Include Specific Fields in Output Documents'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#include-specific-fields-in-output-documents'
+ pipeline:
+ -
+ $project:
+ title: 1
+ author: 1
+ -
+ name: 'Suppress id Field in the Output Documents'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#suppress-_id-field-in-the-output-documents'
+ pipeline:
+ -
+ $project:
+ _id: 0
+ title: 1
+ author: 1
+ -
+ name: 'Exclude Fields from Output Documents'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#exclude-fields-from-output-documents'
+ pipeline:
+ -
+ $project:
+ lastModified: 0
+ -
+ name: 'Exclude Fields from Embedded Documents'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#exclude-fields-from-embedded-documents'
+ pipeline:
+ -
+ $project:
+ author.first: 0
+ lastModified: 0
+ -
+ $project:
+ author:
+ first: 0
+ lastModified: 0
+ -
+ name: 'Conditionally Exclude Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#conditionally-exclude-fields'
+ pipeline:
+ -
+ $project:
+ title: 1
+ author.first: 1
+ author.last: 1
+ author.middle:
+ $cond:
+ if:
+ $eq:
+ - ''
+ - '$author.middle'
+ then: '$$REMOVE'
+ else: '$author.middle'
+ -
+ name: 'Include Specific Fields from Embedded Documents'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#include-specific-fields-from-embedded-documents'
+ pipeline:
+ -
+ $project:
+ stop.title: 1
+ -
+ $project:
+ stop:
+ title: 1
+ -
+ name: 'Include Computed Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#include-computed-fields'
+ pipeline:
+ -
+ $project:
+ title: 1
+ isbn:
+ prefix:
+ $substr:
+ - '$isbn'
+ - 0
+ - 3
+ group:
+ $substr:
+ - '$isbn'
+ - 3
+ - 2
+ publisher:
+ $substr:
+ - '$isbn'
+ - 5
+ - 4
+ title:
+ $substr:
+ - '$isbn'
+ - 9
+ - 3
+ checkDigit:
+ $substr:
+ - '$isbn'
+ - 12
+ - 1
+ lastName: '$author.last'
+ copiesSold: '$copies'
+ -
+ name: 'Project New Array Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/project/#project-new-array-fields'
+ pipeline:
+ -
+ $project:
+ myArray:
+ - '$x'
+ - '$y'
diff --git a/generator/config/stage/redact.yaml b/generator/config/stage/redact.yaml
new file mode 100644
index 000000000..07698119c
--- /dev/null
+++ b/generator/config/stage/redact.yaml
@@ -0,0 +1,52 @@
+# $schema: ../schema.json
+name: $redact
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/'
+type:
+ - stage
+encode: single
+description: |
+ Reshapes each document in the stream by restricting the content for each document based on information stored in the documents themselves. Incorporates the functionality of $project and $match. Can be used to implement field level redaction. For each input document, outputs either one or zero documents.
+arguments:
+ -
+ name: expression
+ type:
+ - expression
+tests:
+ -
+ name: 'Evaluate Access at Every Document Level'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/#evaluate-access-at-every-document-level'
+ pipeline:
+ -
+ $match:
+ year: 2014
+ -
+ $redact:
+ $cond:
+ if:
+ $gt:
+ -
+ $size:
+ $setIntersection:
+ - '$tags'
+ -
+ - 'STLW'
+ - 'G'
+ - 0
+ then: '$$DESCEND'
+ else: '$$PRUNE'
+ -
+ name: 'Exclude All Fields at a Given Level'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/redact/#exclude-all-fields-at-a-given-level'
+ pipeline:
+ -
+ $match:
+ status: 'A'
+ -
+ $redact:
+ $cond:
+ if:
+ $eq:
+ - '$level'
+ - 5
+ then: '$$PRUNE'
+ else: '$$DESCEND'
diff --git a/generator/config/stage/replaceRoot.yaml b/generator/config/stage/replaceRoot.yaml
new file mode 100644
index 000000000..4de474e00
--- /dev/null
+++ b/generator/config/stage/replaceRoot.yaml
@@ -0,0 +1,71 @@
+# $schema: ../schema.json
+name: $replaceRoot
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/'
+type:
+ - stage
+encode: object
+description: |
+ Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level.
+arguments:
+ -
+ name: newRoot
+ type:
+ - resolvesToObject
+tests:
+ -
+ name: 'with an Embedded Document Field'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/#-replaceroot-with-an-embedded-document-field'
+ pipeline:
+ -
+ $replaceRoot:
+ newRoot:
+ $mergeObjects:
+ -
+ dogs: 0
+ cats: 0
+ birds: 0
+ fish: 0
+ - '$pets'
+ -
+ name: 'with a Document Nested in an Array'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/#-replaceroot-with-a-document-nested-in-an-array'
+ pipeline:
+ -
+ # The builder uses the verbose form of the $unwind operator
+ # $unwind: '$grades'
+ $unwind:
+ path: '$grades'
+ -
+ $match:
+ grades.grade:
+ $gte: 90
+ -
+ $replaceRoot:
+ newRoot: '$grades'
+ -
+ name: 'with a newly created document'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/#-replaceroot-with-a-newly-created-document'
+ pipeline:
+ -
+ $replaceRoot:
+ newRoot:
+ full_name:
+ $concat:
+ - '$first_name'
+ - ' '
+ - '$last_name'
+ -
+ name: 'with a New Document Created from $$ROOT and a Default Document'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceRoot/#-replaceroot-with-a-new-document-created-from---root-and-a-default-document'
+ pipeline:
+ -
+ $replaceRoot:
+ newRoot:
+ $mergeObjects:
+ -
+ _id: ''
+ name: ''
+ email: ''
+ cell: ''
+ home: ''
+ - '$$ROOT'
diff --git a/generator/config/stage/replaceWith.yaml b/generator/config/stage/replaceWith.yaml
new file mode 100644
index 000000000..10c5fa3a2
--- /dev/null
+++ b/generator/config/stage/replaceWith.yaml
@@ -0,0 +1,74 @@
+# $schema: ../schema.json
+name: $replaceWith
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/'
+type:
+ - stage
+encode: single
+description: |
+ Replaces a document with the specified embedded document. The operation replaces all existing fields in the input document, including the _id field. Specify a document embedded in the input document to promote the embedded document to the top level.
+ Alias for $replaceRoot.
+arguments:
+ -
+ name: expression
+ type:
+ - resolvesToObject
+tests:
+ -
+ name: 'an Embedded Document Field'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/#-replacewith-an-embedded-document-field'
+ pipeline:
+ -
+ $replaceWith:
+ $mergeObjects:
+ -
+ dogs: 0
+ cats: 0
+ birds: 0
+ fish: 0
+ - '$pets'
+ -
+ name: 'a Document Nested in an Array'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/#-replacewith-a-document-nested-in-an-array'
+ pipeline:
+ -
+ # The builder uses the verbose form of the $unwind operator
+ # $unwind: '$grades'
+ $unwind:
+ path: '$grades'
+ -
+ $match:
+ grades.grade:
+ $gte: 90
+ -
+ $replaceWith: '$grades'
+ -
+ name: 'a Newly Created Document'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/#-replacewith-a-newly-created-document'
+ pipeline:
+ -
+ $match:
+ status: 'C'
+ -
+ $replaceWith:
+ _id: '$_id'
+ item: '$item'
+ amount:
+ $multiply:
+ - '$price'
+ - '$quantity'
+ status: 'Complete'
+ asofDate: '$$NOW'
+ -
+ name: 'a New Document Created from $$ROOT and a Default Document'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/replaceWith/#-replacewith-a-new-document-created-from---root-and-a-default-document'
+ pipeline:
+ -
+ $replaceWith:
+ $mergeObjects:
+ -
+ _id: ''
+ name: ''
+ email: ''
+ cell: ''
+ home: ''
+ - '$$ROOT'
diff --git a/generator/config/stage/sample.yaml b/generator/config/stage/sample.yaml
new file mode 100644
index 000000000..757382aaf
--- /dev/null
+++ b/generator/config/stage/sample.yaml
@@ -0,0 +1,23 @@
+# $schema: ../schema.json
+name: $sample
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/'
+type:
+ - stage
+encode: object
+description: |
+ Randomly selects the specified number of documents from its input.
+arguments:
+ -
+ name: size
+ type:
+ - int
+ description: |
+ The number of documents to randomly select.
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample/#example'
+ pipeline:
+ -
+ $sample:
+ size: 3
diff --git a/generator/config/stage/search.yaml b/generator/config/stage/search.yaml
new file mode 100644
index 000000000..2531e75f6
--- /dev/null
+++ b/generator/config/stage/search.yaml
@@ -0,0 +1,41 @@
+# $schema: ../schema.json
+name: $search
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/search/'
+type:
+ - stage
+encode: single
+description: |
+ Performs a full-text search of the field or fields in an Atlas collection.
+ NOTE: $search is only available for MongoDB Atlas clusters, and is not available for self-managed deployments.
+arguments:
+ -
+ name: search
+ type:
+ - object
+
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/atlas/atlas-search/query-syntax/#aggregation-variable'
+ pipeline:
+ -
+ $search:
+ near:
+ path: 'released'
+ origin: !bson_utcdatetime '2011-09-01T00:00:00.000+00:00'
+ pivot: 7776000000
+ -
+ $project:
+ _id: 0
+ title: 1
+ released: 1
+ -
+ $limit: 5
+ -
+ $facet:
+ docs: []
+ meta:
+ -
+ $replaceWith: '$$SEARCH_META'
+ -
+ $limit: 1
diff --git a/generator/config/stage/searchMeta.yaml b/generator/config/stage/searchMeta.yaml
new file mode 100644
index 000000000..322d048eb
--- /dev/null
+++ b/generator/config/stage/searchMeta.yaml
@@ -0,0 +1,28 @@
+# $schema: ../schema.json
+name: $searchMeta
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/searchMeta/'
+type:
+ - stage
+encode: single
+description: |
+ Returns different types of metadata result documents for the Atlas Search query against an Atlas collection.
+ NOTE: $searchMeta is only available for MongoDB Atlas clusters running MongoDB v4.4.9 or higher, and is not available for self-managed deployments.
+arguments:
+ -
+ name: meta
+ type:
+ - object
+
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/atlas/atlas-search/query-syntax/#example'
+ pipeline:
+ -
+ $searchMeta:
+ range:
+ path: 'year'
+ gte: 1998
+ lt: 1999
+ count:
+ type: 'total'
diff --git a/generator/config/stage/set.yaml b/generator/config/stage/set.yaml
new file mode 100644
index 000000000..a5861aa29
--- /dev/null
+++ b/generator/config/stage/set.yaml
@@ -0,0 +1,73 @@
+# $schema: ../schema.json
+name: $set
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/'
+type:
+ - stage
+encode: single
+description: |
+ Adds new fields to documents. Outputs documents that contain all existing fields from the input documents and newly added fields.
+ Alias for $addFields.
+arguments:
+ -
+ name: field
+ type:
+ - expression
+ variadic: object
+tests:
+ -
+ name: 'Using Two $set Stages'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/#using-two--set-stages'
+ pipeline:
+ -
+ $set:
+ totalHomework:
+ # The $sum expression is always build as an array, even if the value is an array field name
+ # $sum: '$homework'
+ $sum: ['$homework']
+ totalQuiz:
+ # $sum: '$quiz'
+ $sum: ['$quiz']
+ -
+ $set:
+ totalScore:
+ $add:
+ - '$totalHomework'
+ - '$totalQuiz'
+ - '$extraCredit'
+ -
+ name: 'Adding Fields to an Embedded Document'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/#adding-fields-to-an-embedded-document'
+ pipeline:
+ -
+ $set:
+ specs.fuel_type: 'unleaded'
+ -
+ name: 'Overwriting an existing field'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/#overwriting-an-existing-field'
+ pipeline:
+ -
+ $set:
+ cats: 20
+ -
+ name: 'Add Element to an Array'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/#add-element-to-an-array'
+ pipeline:
+ -
+ $match:
+ _id: 1
+ -
+ $set:
+ homework:
+ $concatArrays:
+ - '$homework'
+ -
+ - 7
+ -
+ name: 'Creating a New Field with Existing Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/set/#creating-a-new-field-with-existing-fields'
+ pipeline:
+ -
+ $set:
+ quizAverage:
+ # $avg: '$quiz'
+ $avg: ['$quiz']
diff --git a/generator/config/stage/setWindowFields.yaml b/generator/config/stage/setWindowFields.yaml
new file mode 100644
index 000000000..fba751d03
--- /dev/null
+++ b/generator/config/stage/setWindowFields.yaml
@@ -0,0 +1,144 @@
+# $schema: ../schema.json
+name: $setWindowFields
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/'
+type:
+ - stage
+encode: object
+description: |
+ Groups documents into windows and applies one or more operators to the documents in each window.
+ New in MongoDB 5.0.
+arguments:
+ -
+ name: sortBy
+ type:
+ - object # SortSpec
+ description: |
+ Specifies the field(s) to sort the documents by in the partition. Uses the same syntax as the $sort stage. Default is no sorting.
+ -
+ name: output
+ type:
+ - object
+ description: |
+ Specifies the field(s) to append to the documents in the output returned by the $setWindowFields stage. Each field is set to the result returned by the window operator.
+ A field can contain dots to specify embedded document fields and array fields. The semantics for the embedded document dotted notation in the $setWindowFields stage are the same as the $addFields and $set stages.
+ -
+ name: partitionBy
+ type:
+ - expression
+ description: |
+ Specifies an expression to group the documents. In the $setWindowFields stage, the group of documents is known as a partition. Default is one partition for the entire collection.
+ optional: true
+tests:
+ -
+ name: 'Use Documents Window to Obtain Cumulative Quantity for Each State'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-documents-window-to-obtain-cumulative-quantity-for-each-state'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy: '$state'
+ sortBy:
+ orderDate: 1
+ output:
+ cumulativeQuantityForState:
+ $sum: '$quantity'
+ window:
+ documents: ['unbounded', 'current']
+ -
+ name: 'Use Documents Window to Obtain Cumulative Quantity for Each Year'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-documents-window-to-obtain-cumulative-quantity-for-each-year'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy:
+ # $year: '$orderDate'
+ $year:
+ date: '$orderDate'
+ sortBy:
+ orderDate: 1
+ output:
+ cumulativeQuantityForYear:
+ $sum: '$quantity'
+ window:
+ documents: ['unbounded', 'current']
+ -
+ name: 'Use Documents Window to Obtain Moving Average Quantity for Each Year'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-documents-window-to-obtain-moving-average-quantity-for-each-year'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy:
+ # $year: '$orderDate'
+ $year:
+ date: '$orderDate'
+ sortBy:
+ orderDate: 1
+ output:
+ averageQuantity:
+ $avg: '$quantity'
+ window:
+ documents: [-1, 0]
+ -
+ name: 'Use Documents Window to Obtain Cumulative and Maximum Quantity for Each Year'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-documents-window-to-obtain-cumulative-and-maximum-quantity-for-each-year'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy:
+ # $year: '$orderDate'
+ $year:
+ date: '$orderDate'
+ sortBy:
+ orderDate: 1
+ output:
+ cumulativeQuantityForYear:
+ $sum: '$quantity'
+ window:
+ documents: ['unbounded', 'current']
+ maximumQuantityForYear:
+ $max: '$quantity'
+ window:
+ documents: ['unbounded', 'unbounded']
+ -
+ name: 'Range Window Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#range-window-example'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy: '$state'
+ sortBy:
+ price: 1
+ output:
+ quantityFromSimilarOrders:
+ $sum: '$quantity'
+ window:
+ range: [-10, 10]
+ -
+ name: 'Use a Time Range Window with a Positive Upper Bound'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-a-time-range-window-with-a-positive-upper-bound'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy: '$state'
+ sortBy:
+ orderDate: 1
+ output:
+ recentOrders:
+ $push: '$orderDate'
+ window:
+ range: ['unbounded', 10]
+ unit: 'month'
+ -
+ name: 'Use a Time Range Window with a Negative Upper Bound'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/setWindowFields/#use-a-time-range-window-with-a-negative-upper-bound'
+ pipeline:
+ -
+ $setWindowFields:
+ partitionBy: '$state'
+ sortBy:
+ orderDate: 1
+ output:
+ recentOrders:
+ $push: '$orderDate'
+ window:
+ range: ['unbounded', -10]
+ unit: 'month'
diff --git a/generator/config/stage/shardedDataDistribution.yaml b/generator/config/stage/shardedDataDistribution.yaml
new file mode 100644
index 000000000..2f298ca0f
--- /dev/null
+++ b/generator/config/stage/shardedDataDistribution.yaml
@@ -0,0 +1,16 @@
+# $schema: ../schema.json
+name: $shardedDataDistribution
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/'
+type:
+ - stage
+encode: object
+description: |
+ Provides data and size distribution information on sharded collections.
+ New in MongoDB 6.0.3.
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardedDataDistribution/#examples'
+ pipeline:
+ -
+ $shardedDataDistribution: {}
diff --git a/generator/config/stage/skip.yaml b/generator/config/stage/skip.yaml
new file mode 100644
index 000000000..2128fe226
--- /dev/null
+++ b/generator/config/stage/skip.yaml
@@ -0,0 +1,20 @@
+# $schema: ../schema.json
+name: $skip
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/'
+type:
+ - stage
+encode: single
+description: |
+ Skips the first n documents where n is the specified skip number and passes the remaining documents unmodified to the pipeline. For each input document, outputs either zero documents (for the first n documents) or one document (if after the first n documents).
+arguments:
+ -
+ name: skip
+ type:
+ - int
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/skip/#example'
+ pipeline:
+ -
+ $skip: 5
diff --git a/generator/config/stage/sort.yaml b/generator/config/stage/sort.yaml
new file mode 100644
index 000000000..d35e23b63
--- /dev/null
+++ b/generator/config/stage/sort.yaml
@@ -0,0 +1,37 @@
+# $schema: ../schema.json
+name: $sort
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/'
+type:
+ - stage
+encode: single
+description: |
+ Reorders the document stream by a specified sort key. Only the order changes; the documents remain unmodified. For each input document, outputs one document.
+arguments:
+ -
+ name: sort
+ type:
+ - expression
+ - sortSpec
+ variadic: object
+tests:
+ -
+ name: 'Ascending Descending Sort'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/#ascending-descending-sort'
+ pipeline:
+ -
+ $sort:
+ age: -1
+ posts: 1
+ -
+ name: 'Text Score Metadata Sort'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort/#text-score-metadata-sort'
+ pipeline:
+ -
+ $match:
+ $text:
+ $search: 'operating'
+ -
+ $sort:
+ score:
+ $meta: 'textScore'
+ posts: -1
diff --git a/generator/config/stage/sortByCount.yaml b/generator/config/stage/sortByCount.yaml
new file mode 100644
index 000000000..a32d7aff4
--- /dev/null
+++ b/generator/config/stage/sortByCount.yaml
@@ -0,0 +1,25 @@
+# $schema: ../schema.json
+name: $sortByCount
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/'
+type:
+ - stage
+encode: single
+description: |
+ Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.
+arguments:
+ -
+ name: expression
+ type:
+ - expression
+tests:
+ -
+ name: 'Example'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/sortByCount/#example'
+ pipeline:
+ -
+ # The builder uses the verbose form of the $unwind operator
+ # $unwind: '$tags'
+ $unwind:
+ path: '$tags'
+ -
+ $sortByCount: '$tags'
diff --git a/generator/config/stage/unionWith.yaml b/generator/config/stage/unionWith.yaml
new file mode 100644
index 000000000..eafa44110
--- /dev/null
+++ b/generator/config/stage/unionWith.yaml
@@ -0,0 +1,83 @@
+# $schema: ../schema.json
+name: $unionWith
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/'
+type:
+ - stage
+encode: object
+description: |
+ Performs a union of two collections; i.e. combines pipeline results from two collections into a single result set.
+ New in MongoDB 4.4.
+arguments:
+ -
+ name: coll
+ type:
+ - string
+ description: |
+ The collection or view whose pipeline results you wish to include in the result set.
+ -
+ name: pipeline
+ type:
+ - pipeline
+ optional: true
+ description: |
+ An aggregation pipeline to apply to the specified coll.
+ The pipeline cannot include the $out and $merge stages. Starting in v6.0, the pipeline can contain the Atlas Search $search stage as the first stage inside the pipeline.
+tests:
+ -
+ name: 'Report 1 All Sales by Year and Stores and Items'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/#report-1--all-sales-by-year-and-stores-and-items'
+ pipeline:
+ -
+ $set:
+ _id: '2017'
+ -
+ $unionWith:
+ coll: 'sales_2018'
+ pipeline:
+ -
+ $set:
+ _id: '2018'
+ -
+ $unionWith:
+ coll: 'sales_2019'
+ pipeline:
+ -
+ $set:
+ _id: '2019'
+ -
+ $unionWith:
+ coll: 'sales_2020'
+ pipeline:
+ -
+ $set:
+ _id: '2020'
+ -
+ $sort:
+ _id: 1
+ store: 1
+ item: 1
+ -
+ name: 'Report 2 Aggregated Sales by Items'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unionWith/#report-2--aggregated-sales-by-items'
+ pipeline:
+ -
+ # Example uses the short form, the builder always generates the verbose form
+ # $unionWith: 'sales_2018'
+ $unionWith:
+ coll: 'sales_2018'
+ -
+ # $unionWith: 'sales_2019'
+ $unionWith:
+ coll: 'sales_2019'
+ -
+ # $unionWith: 'sales_2020'
+ $unionWith:
+ coll: 'sales_2020'
+ -
+ $group:
+ _id: '$item'
+ total:
+ $sum: '$quantity'
+ -
+ $sort:
+ total: -1
diff --git a/generator/config/stage/unset.yaml b/generator/config/stage/unset.yaml
new file mode 100644
index 000000000..cef9cdd6d
--- /dev/null
+++ b/generator/config/stage/unset.yaml
@@ -0,0 +1,42 @@
+# $schema: ../schema.json
+name: $unset
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/'
+type:
+ - stage
+encode: single
+description: |
+ Removes or excludes fields from documents.
+ Alias for $project stage that removes or excludes fields.
+arguments:
+ -
+ name: field
+ type:
+ - fieldPath
+ variadic: array
+tests:
+ -
+ name: 'Remove a Single Field'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/#remove-a-single-field'
+ pipeline:
+ -
+ # The example in the docs uses the short syntax whereas
+ # the aggregation builder always uses the equivalent array syntax.
+ # $unset: 'copies'
+ $unset: ['copies']
+ -
+ name: 'Remove Top-Level Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/#remove-top-level-fields'
+ pipeline:
+ -
+ $unset:
+ - 'isbn'
+ - 'copies'
+ -
+ name: 'Remove Embedded Fields'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unset/#remove-embedded-fields'
+ pipeline:
+ -
+ $unset:
+ - 'isbn'
+ - 'author.first'
+ - 'copies.warehouse'
diff --git a/generator/config/stage/unwind.yaml b/generator/config/stage/unwind.yaml
new file mode 100644
index 000000000..a1f93edbc
--- /dev/null
+++ b/generator/config/stage/unwind.yaml
@@ -0,0 +1,95 @@
+# $schema: ../schema.json
+name: $unwind
+link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/'
+type:
+ - stage
+encode: object
+description: |
+ Deconstructs an array field from the input documents to output a document for each element. Each output document replaces the array with an element value. For each input document, outputs n documents where n is the number of array elements and can be zero for an empty array.
+arguments:
+ -
+ name: path
+ type:
+ - arrayFieldPath
+ description: |
+ Field path to an array field.
+ -
+ name: includeArrayIndex
+ type:
+ - string
+ optional: true
+ description: |
+ The name of a new field to hold the array index of the element. The name cannot start with a dollar sign $.
+ -
+ name: preserveNullAndEmptyArrays
+ type:
+ - bool
+ optional: true
+ description: |
+ If true, if the path is null, missing, or an empty array, $unwind outputs the document.
+ If false, if path is null, missing, or an empty array, $unwind does not output a document.
+ The default value is false.
+tests:
+ -
+ name: 'Unwind Array'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#unwind-array'
+ pipeline:
+ -
+ # Example uses the short form, the builder always generates the verbose form
+ # $unwind: '$sizes'
+ $unwind:
+ path: '$sizes'
+ -
+ name: 'preserveNullAndEmptyArrays'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#preservenullandemptyarrays'
+ pipeline:
+ -
+ $unwind:
+ path: '$sizes'
+ preserveNullAndEmptyArrays: true
+ -
+ name: 'includeArrayIndex'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#includearrayindex'
+ pipeline:
+ -
+ $unwind:
+ path: '$sizes'
+ includeArrayIndex: 'arrayIndex'
+ -
+ name: 'Group by Unwound Values'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#group-by-unwound-values'
+ pipeline:
+ -
+ $unwind:
+ path: '$sizes'
+ preserveNullAndEmptyArrays: true
+ -
+ $group:
+ _id: '$sizes'
+ averagePrice:
+ $avg: '$price'
+ -
+ $sort:
+ averagePrice: -1
+ -
+ name: 'Unwind Embedded Arrays'
+ link: 'https://www.mongodb.com/docs/manual/reference/operator/aggregation/unwind/#unwind-embedded-arrays'
+ pipeline:
+ -
+ # Example uses the short form, the builder always generates the verbose form
+ # $unwind: '$items'
+ $unwind:
+ path: '$items'
+ -
+ # Example uses the short form, the builder always generates the verbose form
+ # $unwind: '$items.tags'
+ $unwind:
+ path: '$items.tags'
+ -
+ $group:
+ _id: '$items.tags'
+ totalSalesAmount:
+ $sum:
+ $multiply:
+ - '$items.price'
+ - '$items.quantity'
diff --git a/generator/generate b/generator/generate
new file mode 100755
index 000000000..d67515b70
--- /dev/null
+++ b/generator/generate
@@ -0,0 +1,17 @@
+#!/usr/bin/env php
+add(new GenerateCommand(__DIR__ . '/../', __DIR__ . '/config'));
+$application->setDefaultCommand('generate');
+$application->run();
diff --git a/generator/js2yaml.html b/generator/js2yaml.html
new file mode 100644
index 000000000..a0f8654af
--- /dev/null
+++ b/generator/js2yaml.html
@@ -0,0 +1,163 @@
+
+
+Convert JS examples into Yaml
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/generator/src/AbstractGenerator.php b/generator/src/AbstractGenerator.php
new file mode 100644
index 000000000..b0fef69aa
--- /dev/null
+++ b/generator/src/AbstractGenerator.php
@@ -0,0 +1,111 @@
+printer = new PsrPrinter();
+ }
+
+ /**
+ * Split the namespace and class name from a fully qualified class name.
+ *
+ * @return array{0: string, 1: string}
+ */
+ final protected function splitNamespaceAndClassName(string $fqcn): array
+ {
+ $parts = explode('\\', ltrim($fqcn, '\\'));
+ $className = array_pop($parts);
+
+ return [implode('\\', $parts), $className];
+ }
+
+ final protected function writeFile(PhpNamespace $namespace, bool $autoGeneratedWarning = true): void
+ {
+ $classes = $namespace->getClasses();
+ assert(count($classes) === 1, sprintf('Expected exactly one class in namespace "%s", got %d.', $namespace->getName(), count($classes)));
+
+ $filename = $this->rootDir . $this->getFileName($namespace->getName(), current($classes)->getName());
+
+ $dirname = dirname($filename);
+ if (! is_dir($dirname)) {
+ mkdir($dirname, 0755, true);
+ }
+
+ $file = new PhpFile();
+ $file->setStrictTypes();
+ if ($autoGeneratedWarning) {
+ $file->setComment('THIS FILE IS AUTO-GENERATED. ANY CHANGES WILL BE LOST!');
+ }
+
+ $file->addNamespace($namespace);
+
+ file_put_contents($filename, $this->printer->printFile($file));
+ }
+
+ final protected function readFile(string ...$fqcn): PhpFile|null
+ {
+ $filename = $this->rootDir . $this->getFileName(...$fqcn);
+
+ if (! is_file($filename)) {
+ return null;
+ }
+
+ return PhpFile::fromCode(file_get_contents($filename));
+ }
+
+ /**
+ * Thanks to PSR-4, the file name can be determined from the fully qualified class name.
+ *
+ * @param string ...$fqcn Fully qualified class name, merged if multiple parts
+ *
+ * @return string File name relative to the root directory
+ */
+ private function getFileName(string ...$fqcn): string
+ {
+ $fqcn = implode('\\', $fqcn);
+
+ // Config from composer.json autoload
+ $config = [
+ 'MongoDB\\Tests\\' => 'tests/',
+ 'MongoDB\\' => 'src/',
+ ];
+ foreach ($config as $namespace => $directory) {
+ if (str_starts_with($fqcn, $namespace)) {
+ return $directory . str_replace([$namespace, '\\'], ['', '/'], $fqcn) . '.php';
+ }
+ }
+
+ throw new InvalidArgumentException(sprintf('Could not determine file name for "%s"', $fqcn));
+ }
+}
diff --git a/generator/src/Command/GenerateCommand.php b/generator/src/Command/GenerateCommand.php
new file mode 100644
index 000000000..78482963e
--- /dev/null
+++ b/generator/src/Command/GenerateCommand.php
@@ -0,0 +1,90 @@
+setName('generate');
+ $this->setDescription('Generate code for mongodb/mongodb library');
+ $this->setHelp('Generate code for mongodb/mongodb library');
+ }
+
+ public function execute(InputInterface $input, OutputInterface $output): int
+ {
+ $output->writeln('Generating code for mongodb/mongodb library');
+
+ $expressions = $this->generateExpressionClasses($output);
+ $this->generateOperatorClasses($expressions, $output);
+
+ return Command::SUCCESS;
+ }
+
+ /** @return array */
+ private function generateExpressionClasses(OutputInterface $output): array
+ {
+ $output->writeln('Generating expression classes');
+
+ $config = require $this->configDir . '/expressions.php';
+ assert(is_array($config));
+
+ $definitions = [];
+ $generator = new ExpressionClassGenerator($this->rootDir);
+ foreach ($config as $name => $def) {
+ assert(is_array($def));
+ assert(! array_key_exists($name, $definitions), sprintf('Duplicate expression name "%s".', $name));
+ $definitions[$name] = $def = new ExpressionDefinition($name, ...$def);
+ $generator->generate($def);
+ }
+
+ $generator = new ExpressionFactoryGenerator($this->rootDir);
+ $generator->generate($definitions);
+
+ return $definitions;
+ }
+
+ /** @param array $expressions */
+ private function generateOperatorClasses(array $expressions, OutputInterface $output): void
+ {
+ $config = require $this->configDir . '/definitions.php';
+ assert(is_array($config));
+
+ foreach ($config as $def) {
+ assert(is_array($def));
+ $definition = new GeneratorDefinition(...$def);
+
+ foreach ($definition->generators as $generatorClass) {
+ $output->writeln(sprintf('Generating classes for %s with %s', basename($definition->configFiles), $generatorClass));
+ assert(is_a($generatorClass, OperatorGenerator::class, true));
+ $generator = new $generatorClass($this->rootDir, $expressions);
+ $generator->generate($definition);
+ }
+ }
+ }
+}
diff --git a/generator/src/Definition/ArgumentDefinition.php b/generator/src/Definition/ArgumentDefinition.php
new file mode 100644
index 000000000..e45ea0da3
--- /dev/null
+++ b/generator/src/Definition/ArgumentDefinition.php
@@ -0,0 +1,49 @@
+ */
+ public array $type,
+ public string|null $description = null,
+ public bool $optional = false,
+ string|null $variadic = null,
+ int|null $variadicMin = null,
+ public mixed $default = null,
+ ) {
+ assert($this->optional === false || $this->default === null, 'Optional arguments cannot have a default value');
+ if (is_array($type)) {
+ assert(array_is_list($type), 'Type must be a list or a single string');
+ foreach ($type as $t) {
+ assert(is_string($t), sprintf('Type must be a list of strings. Got %s', get_debug_type($type)));
+ }
+ }
+
+ if ($variadic) {
+ $this->variadic = VariadicType::from($variadic);
+ if ($variadicMin === null) {
+ $this->variadicMin = $optional ? 0 : 1;
+ } else {
+ $this->variadicMin = $variadicMin;
+ }
+ } else {
+ $this->variadic = null;
+ $this->variadicMin = null;
+ }
+ }
+}
diff --git a/generator/src/Definition/ExpressionDefinition.php b/generator/src/Definition/ExpressionDefinition.php
new file mode 100644
index 000000000..cbe37febc
--- /dev/null
+++ b/generator/src/Definition/ExpressionDefinition.php
@@ -0,0 +1,37 @@
+ */
+ public array $acceptedTypes,
+ /** Interface to implement for operators that resolve to this type. Generated class/enum/interface. */
+ public string|null $returnType = null,
+ public string|null $extends = null,
+ /** @var list */
+ public array $implements = [],
+ public array $values = [],
+ public PhpObject|null $generate = null,
+ ) {
+ assert($generate === PhpObject::PhpClass || ! $extends, $name . ': Cannot specify "extends" when "generate" is not "class"');
+ assert($generate === PhpObject::PhpEnum || ! $this->values, $name . ': Cannot specify "values" when "generate" is not "enum"');
+ //assert($returnType === null || interface_exists($returnType), $name . ': Return type must be an interface');
+
+ foreach ($acceptedTypes as $acceptedType) {
+ assert(is_string($acceptedType), $name . ': AcceptedTypes must be an array of strings.');
+ }
+
+ if ($generate) {
+ $this->returnType = 'MongoDB\\Builder\\Expression\\' . ucfirst($this->name);
+ }
+ }
+}
diff --git a/generator/src/Definition/GeneratorDefinition.php b/generator/src/Definition/GeneratorDefinition.php
new file mode 100644
index 000000000..2faa2fac3
--- /dev/null
+++ b/generator/src/Definition/GeneratorDefinition.php
@@ -0,0 +1,42 @@
+> */
+ public array $generators,
+ public string $namespace,
+ public string $classNameSuffix = '',
+ public array $interfaces = [],
+ public string|null $parentClass = null,
+ ) {
+ assert(str_starts_with($namespace, 'MongoDB\\'), sprintf('Namespace must start with "MongoDB\\". Got "%s"', $namespace));
+ assert(! str_ends_with($namespace, '\\'), sprintf('Namespace must not end with "\\". Got "%s"', $namespace));
+
+ assert(array_is_list($interfaces), 'Generators must be a list of class names');
+ foreach ($interfaces as $interface) {
+ assert(is_string($interface) && class_exists($interface), sprintf('Interface "%s" does not exist', $interface));
+ }
+
+ assert(array_is_list($generators), 'Generators must be a list of class names');
+ foreach ($generators as $class) {
+ assert(is_string($class) && is_subclass_of($class, OperatorGenerator::class), sprintf('Generator class "%s" must extend "%s"', $class, OperatorGenerator::class));
+ }
+ }
+}
diff --git a/generator/src/Definition/OperatorDefinition.php b/generator/src/Definition/OperatorDefinition.php
new file mode 100644
index 000000000..ce39fe4d7
--- /dev/null
+++ b/generator/src/Definition/OperatorDefinition.php
@@ -0,0 +1,73 @@
+ */
+ public readonly array $arguments;
+
+ /** @var list */
+ public readonly array $tests;
+
+ public function __construct(
+ public string $name,
+ public string $link,
+ string $encode,
+ /** @var list */
+ public array $type,
+ public string|null $description = null,
+ array $arguments = [],
+ array $tests = [],
+ ) {
+ $this->encode = match ($encode) {
+ 'single' => Encode::Single,
+ 'array' => Encode::Array,
+ 'object' => Encode::Object,
+ 'flat_object' => Encode::FlatObject,
+ 'dollar_object' => Encode::DollarObject,
+ 'group' => Encode::Group,
+ default => throw new UnexpectedValueException(sprintf('Unexpected "encode" value for operator "%s". Got "%s"', $name, $encode)),
+ };
+
+ // Convert arguments to ArgumentDefinition objects
+ // Optional arguments must be after required arguments
+ $requiredArgs = $optionalArgs = [];
+ foreach ($arguments as $arg) {
+ $arg = new ArgumentDefinition(...get_object_vars($arg));
+ if ($arg->optional) {
+ $optionalArgs[] = $arg;
+ } else {
+ $requiredArgs[] = $arg;
+ }
+ }
+
+ // "single" encode operators must have one required argument
+ if ($this->encode === Encode::Single) {
+ assert(count($requiredArgs) === 1, sprintf('Single encode operator "%s" must have one argument', $name));
+ assert(count($optionalArgs) === 0, sprintf('Single encode operator "%s" argument cannot be optional', $name));
+ }
+
+ $this->arguments = array_merge($requiredArgs, $optionalArgs);
+
+ $this->tests = array_map(
+ static fn (object $test): TestDefinition => new TestDefinition(...get_object_vars($test)),
+ array_values($tests),
+ );
+ }
+}
diff --git a/generator/src/Definition/PhpObject.php b/generator/src/Definition/PhpObject.php
new file mode 100644
index 000000000..5e815e0b6
--- /dev/null
+++ b/generator/src/Definition/PhpObject.php
@@ -0,0 +1,15 @@
+ */
+ public array $pipeline,
+ public string|null $link = null,
+ ) {
+ assert(array_is_list($pipeline), sprintf('Argument "%s" pipeline must be a list', $name));
+ }
+}
diff --git a/generator/src/Definition/VariadicType.php b/generator/src/Definition/VariadicType.php
new file mode 100644
index 000000000..091f654c9
--- /dev/null
+++ b/generator/src/Definition/VariadicType.php
@@ -0,0 +1,11 @@
+ */
+ public function read(string $dirname): array
+ {
+ $finder = new Finder();
+ $finder->files()->in($dirname)->name('*.yaml')->sortByName();
+
+ $definitions = [];
+ foreach ($finder as $file) {
+ $operator = Yaml::parseFile(
+ $file->getPathname(),
+ Yaml::PARSE_OBJECT | Yaml::PARSE_OBJECT_FOR_MAP | Yaml::PARSE_CUSTOM_TAGS,
+ );
+ $definitions[] = new OperatorDefinition(...get_object_vars($operator));
+ }
+
+ return $definitions;
+ }
+}
diff --git a/generator/src/ExpressionClassGenerator.php b/generator/src/ExpressionClassGenerator.php
new file mode 100644
index 000000000..fc9119364
--- /dev/null
+++ b/generator/src/ExpressionClassGenerator.php
@@ -0,0 +1,96 @@
+generate) {
+ return;
+ }
+
+ try {
+ $this->writeFile($this->createClassOrInterface($definition));
+ } catch (Throwable $e) {
+ throw new RuntimeException('Failed to generate expression class for ' . $definition->name, 0, $e);
+ }
+ }
+
+ public function createClassOrInterface(ExpressionDefinition $definition): PhpNamespace
+ {
+ [$namespace, $className] = $this->splitNamespaceAndClassName($definition->returnType);
+ $namespace = new PhpNamespace($namespace);
+ foreach ($definition->implements as $interface) {
+ $namespace->addUse($interface);
+ }
+
+ $types = array_map(
+ fn (string $type): string => match ($type) {
+ 'list' => 'array',
+ default => $type,
+ },
+ $definition->acceptedTypes,
+ );
+
+ if ($definition->generate === PhpObject::PhpClass) {
+ $class = $namespace->addClass($className);
+ $class->setImplements($definition->implements);
+ $class->setExtends($definition->extends);
+
+ // Replace with promoted property in PHP 8.1
+ $propertyType = Type::union(...$types);
+ $class->addProperty('name')
+ ->setType($propertyType)
+ ->setReadOnly()
+ ->setPublic();
+
+ $constructor = $class->addMethod('__construct');
+ $constructor->addParameter('name')->setType($propertyType);
+
+ $namespace->addUse(InvalidArgumentException::class);
+ $namespace->addUseFunction('sprintf');
+ $namespace->addUseFunction('str_starts_with');
+ $constructor->addBody(<<addBody('$this->name = $name;');
+ } elseif ($definition->generate === PhpObject::PhpInterface) {
+ $interface = $namespace->addInterface($className);
+ $interface->setExtends($definition->implements);
+ } elseif ($definition->generate === PhpObject::PhpEnum) {
+ $enum = $namespace->addEnum($className);
+ $enum->setType('string');
+ array_map(
+ fn (string $case) => $enum->addCase(ucfirst($case), $case),
+ $definition->values,
+ );
+ } else {
+ throw new LogicException('Unknown generate type: ' . var_export($definition->generate, true));
+ }
+
+ return $namespace;
+ }
+}
diff --git a/generator/src/ExpressionFactoryGenerator.php b/generator/src/ExpressionFactoryGenerator.php
new file mode 100644
index 000000000..b1e84c5dd
--- /dev/null
+++ b/generator/src/ExpressionFactoryGenerator.php
@@ -0,0 +1,49 @@
+ $expressions */
+ public function generate(array $expressions): void
+ {
+ $this->writeFile($this->createFactoryClass($expressions));
+ }
+
+ /** @param array $expressions */
+ private function createFactoryClass(array $expressions): PhpNamespace
+ {
+ $namespace = new PhpNamespace('MongoDB\\Builder\\Expression');
+ $trait = $namespace->addTrait('ExpressionFactoryTrait');
+ $trait->addComment('@internal');
+
+ // Pedantry requires methods to be ordered alphabetically
+ usort($expressions, fn (ExpressionDefinition $a, ExpressionDefinition $b) => $a->name <=> $b->name);
+
+ foreach ($expressions as $expression) {
+ if ($expression->generate !== PhpObject::PhpClass) {
+ continue;
+ }
+
+ $namespace->addUse($expression->returnType);
+ $expressionShortClassName = $this->splitNamespaceAndClassName($expression->returnType)[1];
+
+ $method = $trait->addMethod(lcfirst($expressionShortClassName));
+ $method->setStatic();
+ $method->addParameter('name')->setType('string');
+ $method->addBody('return new ' . $expressionShortClassName . '($name);');
+ $method->setReturnType($expression->returnType);
+ }
+
+ return $namespace;
+ }
+}
diff --git a/generator/src/FluentStageFactoryGenerator.php b/generator/src/FluentStageFactoryGenerator.php
new file mode 100644
index 000000000..ff7010f15
--- /dev/null
+++ b/generator/src/FluentStageFactoryGenerator.php
@@ -0,0 +1,134 @@
+writeFile($this->createFluentFactoryTrait($definition));
+ }
+
+ private function createFluentFactoryTrait(GeneratorDefinition $definition): PhpNamespace
+ {
+ $namespace = new PhpNamespace($definition->namespace);
+ $trait = $namespace->addTrait('FluentFactoryTrait');
+
+ $namespace->addUse(self::FACTORY_CLASS);
+ $namespace->addUse(StageInterface::class);
+ $namespace->addUse(Pipeline::class);
+ $namespace->addUse(stdClass::class);
+
+ $trait->addProperty('pipeline')
+ ->setType('array')
+ ->setComment('@var list|stdClass>')
+ ->setValue([]);
+ $trait->addMethod('getPipeline')
+ ->setReturnType(Pipeline::class)
+ ->setBody(<<<'PHP'
+ return new Pipeline(...$this->pipeline);
+ PHP);
+
+ $this->addUsesFrom(self::FACTORY_CLASS, $namespace);
+ $staticFactory = ClassType::from(self::FACTORY_CLASS);
+ assert($staticFactory instanceof ClassType);
+
+ // Import the methods customized in the factory class
+ foreach ($staticFactory->getMethods() as $method) {
+ $this->addMethod($method, $trait);
+ }
+
+ // Import the other methods provided by the generated trait
+ foreach ($staticFactory->getTraits() as $usedTrait) {
+ $this->addUsesFrom($usedTrait->getName(), $namespace);
+ $staticFactory = TraitType::from($usedTrait->getName());
+ assert($staticFactory instanceof TraitType);
+ foreach ($staticFactory->getMethods() as $method) {
+ $this->addMethod($method, $trait);
+ }
+ }
+
+ return $namespace;
+ }
+
+ private function addMethod(Method $factoryMethod, TraitType $trait): void
+ {
+ // Non-public methods are not part of the API
+ if (! $factoryMethod->isPublic()) {
+ return;
+ }
+
+ // Some methods can be overridden in the class, so we skip them
+ // when importing the methods provided by the trait.
+ if ($trait->hasMethod($factoryMethod->getName())) {
+ return;
+ }
+
+ $method = $trait->addMethod($factoryMethod->getName());
+
+ $method->setComment($factoryMethod->getComment());
+ $method->setParameters($factoryMethod->getParameters());
+
+ $args = array_map(
+ fn (Parameter $param): string => '$' . $param->getName(),
+ $factoryMethod->getParameters(),
+ );
+
+ if ($factoryMethod->isVariadic()) {
+ $method->setVariadic();
+ $args[array_key_last($args)] = '...' . $args[array_key_last($args)];
+ }
+
+ $method->setReturnType('static');
+ $method->setBody(sprintf(
+ <<<'PHP'
+ $this->pipeline[] = %s::%s(%s);
+
+ return $this;
+ PHP,
+ (new ReflectionClass(self::FACTORY_CLASS))->getShortName(),
+ $factoryMethod->getName(),
+ implode(', ', $args),
+ ));
+ }
+
+ private static function addUsesFrom(string $classLike, PhpNamespace $namespace): void
+ {
+ $file = PhpFile::fromCode(file_get_contents((new ReflectionClass($classLike))->getFileName()));
+
+ foreach ($file->getNamespaces() as $ns) {
+ foreach ($ns->getUses() as $use) {
+ $namespace->addUse($use);
+ }
+ }
+ }
+}
diff --git a/generator/src/OperatorClassGenerator.php b/generator/src/OperatorClassGenerator.php
new file mode 100644
index 000000000..73fcf09bf
--- /dev/null
+++ b/generator/src/OperatorClassGenerator.php
@@ -0,0 +1,196 @@
+getOperators($definition) as $operator) {
+ try {
+ $this->writeFile($this->createClass($definition, $operator));
+ } catch (Throwable $e) {
+ throw new RuntimeException(sprintf('Failed to generate class for operator "%s"', $operator->name), 0, $e);
+ }
+ }
+ }
+
+ public function createClass(GeneratorDefinition $definition, OperatorDefinition $operator): PhpNamespace
+ {
+ $namespace = new PhpNamespace($definition->namespace);
+
+ $interfaces = $this->getInterfaces($operator);
+ foreach ($interfaces as $interface) {
+ $namespace->addUse($interface);
+ }
+
+ $class = $namespace->addClass($this->getOperatorClassName($definition, $operator));
+ $class->setImplements($interfaces);
+ $namespace->addUse(OperatorInterface::class);
+ $class->addImplement(OperatorInterface::class);
+
+ // Expose operator metadata as constants
+ // @todo move to encoder class
+ $class->addComment($operator->description);
+ $class->addComment('@see ' . $operator->link);
+ $namespace->addUse(Encode::class);
+ $class->addConstant('ENCODE', new Literal('Encode::' . $operator->encode->name));
+
+ $constuctor = $class->addMethod('__construct');
+ foreach ($operator->arguments as $argument) {
+ $type = $this->getAcceptedTypes($argument);
+ foreach ($type->use as $use) {
+ $namespace->addUse($use);
+ }
+
+ $property = $class->addProperty($argument->name);
+ $property->setReadOnly();
+ $constuctorParam = $constuctor->addParameter($argument->name);
+ $constuctorParam->setType($type->native);
+
+ if ($argument->variadic) {
+ $constuctor->setVariadic();
+ $constuctor->addComment('@param ' . $type->doc . ' ...$' . $argument->name . rtrim(' ' . $argument->description));
+
+ if ($argument->variadicMin > 0) {
+ $namespace->addUse(InvalidArgumentException::class);
+ $constuctor->addBody(<<name}) < {$argument->variadicMin}) {
+ throw new InvalidArgumentException(\sprintf('Expected at least %d values for \${$argument->name}, got %d.', {$argument->variadicMin}, \count(\${$argument->name})));
+ }
+
+ PHP);
+ }
+
+ if ($argument->variadic === VariadicType::Array) {
+ $property->setType('array');
+ $property->addComment('@var list<' . $type->doc . '> $' . $argument->name . rtrim(' ' . $argument->description));
+ // Warn that named arguments are not supported
+ // @see https://psalm.dev/docs/running_psalm/issues/NamedArgumentNotAllowed/
+ $constuctor->addComment('@no-named-arguments');
+ $namespace->addUseFunction('array_is_list');
+ $namespace->addUse(InvalidArgumentException::class);
+ $constuctor->addBody(<<name})) {
+ throw new InvalidArgumentException('Expected \${$argument->name} arguments to be a list (array), named arguments are not supported');
+ }
+
+ PHP);
+ } elseif ($argument->variadic === VariadicType::Object) {
+ $namespace->addUse(stdClass::class);
+ $property->setType(stdClass::class);
+ $property->addComment('@var stdClass<' . $type->doc . '> $' . $argument->name . rtrim(' ' . $argument->description));
+ $namespace->addUseFunction('is_string');
+ $namespace->addUse(InvalidArgumentException::class);
+ $constuctor->addBody(<<name} as \$key => \$value) {
+ if (! is_string(\$key)) {
+ throw new InvalidArgumentException('Expected \${$argument->name} arguments to be a map (object), named arguments (:) or array unpacking ...[\'\' => ] must be used');
+ }
+ }
+
+ \${$argument->name} = (object) \${$argument->name};
+ PHP);
+ }
+ } else {
+ // Non-variadic arguments
+ $property->addComment('@var ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description));
+ $property->setType($type->native);
+ $constuctor->addComment('@param ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description));
+
+ if ($argument->optional) {
+ // We use a special Optional::Undefined type to differentiate between null and undefined
+ $constuctorParam->setDefaultValue(new Literal('Optional::Undefined'));
+ } elseif ($argument->default !== null) {
+ $constuctorParam->setDefaultValue($argument->default);
+ }
+
+ // List type must be validated with array_is_list()
+ if ($type->list) {
+ $namespace->addUseFunction('is_array');
+ $namespace->addUseFunction('array_is_list');
+ $namespace->addUse(InvalidArgumentException::class);
+ $constuctor->addBody(<<name}) && ! array_is_list(\${$argument->name})) {
+ throw new InvalidArgumentException('Expected \${$argument->name} argument to be a list, got an associative array.');
+ }
+
+ PHP);
+ }
+
+ if ($type->query) {
+ $namespace->addUseFunction('is_array');
+ $namespace->addUse(QueryObject::class);
+ $constuctor->addBody(<<name})) {
+ \${$argument->name} = QueryObject::create(\${$argument->name});
+ }
+
+ PHP);
+ }
+
+ if ($type->javascript) {
+ $namespace->addUseFunction('is_string');
+ $namespace->addUse(Javascript::class);
+ $constuctor->addBody(<<name})) {
+ \${$argument->name} = new Javascript(\${$argument->name});
+ }
+
+ PHP);
+ }
+ }
+
+ // Set property from constructor argument
+ $constuctor->addBody('$this->' . $argument->name . ' = $' . $argument->name . ';');
+ }
+
+ $class->addMethod('getOperator')
+ ->setReturnType('string')
+ ->setBody('return ' . var_export($operator->name, true) . ';');
+
+ return $namespace;
+ }
+
+ /**
+ * Operator classes interfaces are defined by their return type as a MongoDB expression.
+ *
+ * @return list
+ */
+ private function getInterfaces(OperatorDefinition $definition): array
+ {
+ $interfaces = [];
+
+ foreach ($definition->type as $type) {
+ $interfaces[] = $interface = $this->getType($type)->returnType;
+ assert(interface_exists($interface), sprintf('"%s" is not an interface.', $interface));
+ }
+
+ return $interfaces;
+ }
+}
diff --git a/generator/src/OperatorFactoryGenerator.php b/generator/src/OperatorFactoryGenerator.php
new file mode 100644
index 000000000..0bc27620f
--- /dev/null
+++ b/generator/src/OperatorFactoryGenerator.php
@@ -0,0 +1,96 @@
+writeFile($this->createFactoryTrait($definition));
+ }
+
+ private function createFactoryTrait(GeneratorDefinition $definition): PhpNamespace
+ {
+ $namespace = new PhpNamespace($definition->namespace);
+ $trait = $namespace->addTrait('FactoryTrait');
+ $trait->addComment('@internal');
+
+ // Pedantry requires methods to be ordered alphabetically
+ $operators = $this->getOperators($definition);
+ usort($operators, fn (OperatorDefinition $a, OperatorDefinition $b) => strcasecmp($a->name, $b->name));
+
+ foreach ($operators as $operator) {
+ try {
+ $this->addMethod($definition, $operator, $namespace, $trait);
+ } catch (Throwable $e) {
+ throw new RuntimeException(sprintf('Failed to generate class for operator "%s"', $operator->name), 0, $e);
+ }
+ }
+
+ return $namespace;
+ }
+
+ private function addMethod(GeneratorDefinition $definition, OperatorDefinition $operator, PhpNamespace $namespace, TraitType $trait): void
+ {
+ $operatorClassName = '\\' . $definition->namespace . '\\' . $this->getOperatorClassName($definition, $operator);
+ $namespace->addUse($operatorClassName);
+
+ $method = $trait->addMethod(ltrim($operator->name, '$'));
+ $method->setStatic();
+ $method->addComment($operator->description);
+ $method->addComment('@see ' . $operator->link);
+ $args = [];
+ foreach ($operator->arguments as $argument) {
+ $type = $this->getAcceptedTypes($argument);
+ foreach ($type->use as $use) {
+ $namespace->addUse($use);
+ }
+
+ $parameter = $method->addParameter($argument->name);
+ $parameter->setType($type->native);
+ if ($argument->variadic) {
+ if ($argument->variadic === VariadicType::Array) {
+ // Warn that named arguments are not supported
+ // @see https://psalm.dev/docs/running_psalm/issues/NamedArgumentNotAllowed/
+ $method->addComment('@no-named-arguments');
+ }
+
+ $method->setVariadic();
+ $method->addComment('@param ' . $type->doc . ' ...$' . $argument->name . rtrim(' ' . $argument->description));
+ $args[] = '...$' . $argument->name;
+ } else {
+ if ($argument->optional) {
+ $parameter->setDefaultValue(new Literal('Optional::Undefined'));
+ } elseif ($argument->default !== null) {
+ $parameter->setDefaultValue($argument->default);
+ }
+
+ $method->addComment('@param ' . $type->doc . ' $' . $argument->name . rtrim(' ' . $argument->description));
+ $args[] = '$' . $argument->name;
+ }
+ }
+
+ $operatorShortClassName = ltrim(str_replace($definition->namespace, '', $operatorClassName), '\\');
+ $method->addBody('return new ' . $operatorShortClassName . '(' . implode(', ', $args) . ');');
+ $method->setReturnType($operatorClassName);
+ }
+}
diff --git a/generator/src/OperatorGenerator.php b/generator/src/OperatorGenerator.php
new file mode 100644
index 000000000..0b9c60748
--- /dev/null
+++ b/generator/src/OperatorGenerator.php
@@ -0,0 +1,154 @@
+ */
+ private array $expressions,
+ ) {
+ parent::__construct($rootDir);
+
+ $this->yamlReader = new YamlReader();
+ }
+
+ abstract public function generate(GeneratorDefinition $definition): void;
+
+ /** @return list */
+ final protected function getOperators(GeneratorDefinition $definition): array
+ {
+ // Remove unsupported operators
+ return array_filter(
+ $this->yamlReader->read($definition->configFiles),
+ fn (OperatorDefinition $operator): bool => ! in_array($operator->name, ['$'], true),
+ );
+ }
+
+ final protected function getOperatorClassName(GeneratorDefinition $definition, OperatorDefinition $operator): string
+ {
+ return ucfirst(ltrim($operator->name, '$')) . $definition->classNameSuffix;
+ }
+
+ final protected function getType(string $type): ExpressionDefinition
+ {
+ assert(array_key_exists($type, $this->expressions), sprintf('Invalid expression type "%s".', $type));
+
+ return $this->expressions[$type];
+ }
+
+ /**
+ * Expression types can contain class names, interface, native types or "list".
+ * PHPDoc types are more precise than native types, so we use them systematically even if redundant.
+ *
+ * @return object{native:string,doc:string,use:list,list:bool,query:bool,javascript:bool}
+ */
+ final protected function getAcceptedTypes(ArgumentDefinition $arg): stdClass
+ {
+ $nativeTypes = [];
+
+ foreach ($arg->type as $type) {
+ $type = $this->getType($type);
+ $nativeTypes = array_merge($nativeTypes, $type->acceptedTypes);
+
+ if (isset($type->returnType)) {
+ $nativeTypes[] = $type->returnType;
+ }
+ }
+
+ if ($arg->optional) {
+ $use[] = '\\' . Optional::class;
+ $nativeTypes[] = Optional::class;
+ }
+
+ $docTypes = $nativeTypes = array_unique($nativeTypes);
+ $use = [];
+
+ foreach ($nativeTypes as $key => $typeName) {
+ if (interface_exists($typeName) || class_exists($typeName)) {
+ $use[] = $nativeTypes[$key] = '\\' . $typeName;
+ $docTypes[$key] = $this->splitNamespaceAndClassName($typeName)[1];
+ // A union cannot contain both object and a class type
+ if (in_array('object', $nativeTypes, true)) {
+ unset($nativeTypes[$key]);
+ }
+ }
+ }
+
+ // If an array is expected, but not an object, we can check for a list
+ $listCheck = in_array('\\' . PackedArray::class, $nativeTypes, true)
+ && ! in_array('\\' . Document::class, $nativeTypes, true);
+
+ // If the argument is a query, we need to convert it to a QueryObject
+ $isQuery = in_array('query', $arg->type, true);
+
+ // If the argument is code, we need to convert it to a Javascript object
+ $isJavascript = in_array('javascript', $arg->type, true);
+
+ // mixed can only be used as a standalone type
+ if (in_array('mixed', $nativeTypes, true)) {
+ $nativeTypes = ['mixed'];
+ }
+
+ usort($nativeTypes, self::sortTypesCallback(...));
+ usort($docTypes, self::sortTypesCallback(...));
+ sort($use);
+
+ return (object) [
+ 'native' => Type::union(...array_unique($nativeTypes)),
+ 'doc' => Type::union(...array_unique($docTypes)),
+ 'use' => array_unique($use),
+ 'list' => $listCheck,
+ 'query' => $isQuery,
+ 'javascript' => $isJavascript,
+ ];
+ }
+
+ /**
+ * usort() callback for sorting types.
+ * "Optional" is always first, for documentation of optional parameters,
+ * then types are sorted alphabetically.
+ */
+ private static function sortTypesCallback(string $type1, string $type2): int
+ {
+ if ($type1 === 'Optional' || $type1 === '\\' . Optional::class) {
+ return -1;
+ }
+
+ if ($type2 === 'Optional' || $type2 === '\\' . Optional::class) {
+ return 1;
+ }
+
+ return $type1 <=> $type2;
+ }
+}
diff --git a/generator/src/OperatorTestGenerator.php b/generator/src/OperatorTestGenerator.php
new file mode 100644
index 000000000..a8e6e91cc
--- /dev/null
+++ b/generator/src/OperatorTestGenerator.php
@@ -0,0 +1,170 @@
+createExpectedClass($definition);
+
+ foreach ($this->getOperators($definition) as $operator) {
+ // Skip operators without tests
+ if (! $operator->tests) {
+ continue;
+ }
+
+ try {
+ $this->writeFile($this->createClass($definition, $operator, $dataNamespace->getClasses()[self::DATA_ENUM]), false);
+ } catch (Throwable $e) {
+ throw new RuntimeException(sprintf('Failed to generate class for operator "%s"', $operator->name), 0, $e);
+ }
+ }
+
+ $this->writeFile($dataNamespace);
+ }
+
+ public function createExpectedClass(GeneratorDefinition $definition): PhpNamespace
+ {
+ $dataNamespace = str_replace('MongoDB', 'MongoDB\\Tests', $definition->namespace);
+
+ $namespace = new PhpNamespace($dataNamespace);
+ $enum = $namespace->addEnum(self::DATA_ENUM);
+ $enum->setType('string');
+
+ return $namespace;
+ }
+
+ public function createClass(GeneratorDefinition $definition, OperatorDefinition $operator, EnumType $dataEnum): PhpNamespace
+ {
+ $testNamespace = str_replace('MongoDB', 'MongoDB\\Tests', $definition->namespace);
+ $testClass = $this->getOperatorClassName($definition, $operator) . 'Test';
+
+ $namespace = $this->readFile($testNamespace, $testClass)?->getNamespaces()[$testNamespace] ?? null;
+ $namespace ??= new PhpNamespace($testNamespace);
+
+ $class = $namespace->getClasses()[$testClass] ?? null;
+ $class ??= $namespace->addClass($testClass);
+ $namespace->addUse(PipelineTestCase::class);
+ $class->setExtends(PipelineTestCase::class);
+ $namespace->addUse(Pipeline::class);
+ $class->setComment('Test ' . $operator->name . ' ' . basename($definition->configFiles));
+
+ foreach ($operator->tests as $test) {
+ $testName = 'test' . str_replace([' ', '-'], '', ucwords(str_replace('$', '', $test->name)));
+ $caseName = str_replace([' ', '-'], '', ucwords(str_replace('$', '', $operator->name . ' ' . $test->name)));
+
+ $pipeline = $this->convertYamlTaggedValues($test->pipeline);
+
+ // Wrap the pipeline array into a document
+ $json = Document::fromPHP(['pipeline' => $pipeline])->toCanonicalExtendedJSON();
+ // Unwrap the pipeline array and reformat for prettier JSON
+ $json = json_encode(json_decode($json)->pipeline, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
+ $case = $dataEnum->addCase($caseName, new Literal('<<<\'JSON\'' . "\n" . $json . "\n" . 'JSON'));
+ $case->setComment($test->name);
+ if ($test->link) {
+ $case->addComment('');
+ $case->addComment('@see ' . $test->link);
+ }
+
+ $caseName = self::DATA_ENUM . '::' . $caseName;
+
+ if ($class->hasMethod($testName)) {
+ $testMethod = $class->getMethod($testName);
+ } else {
+ $testMethod = $class->addMethod($testName);
+ $testMethod->setBody(<<assertSamePipeline({$caseName}, \$pipeline);
+ PHP);
+ }
+
+ $testMethod->setPublic();
+ $testMethod->setReturnType(Type::Void);
+ }
+
+ $methods = $class->getMethods();
+ ksort($methods);
+ $class->setMethods($methods);
+
+ return $namespace;
+ }
+
+ private function convertYamlTaggedValues(mixed $object): mixed
+ {
+ if ($object instanceof TaggedValue) {
+ $value = $object->getValue();
+
+ return match ($object->getTag()) {
+ 'bson_regex' => new Regex(...(array) $value),
+ 'bson_int128' => new Int64($value),
+ 'bson_decimal128' => new Decimal128($value),
+ 'bson_utcdatetime' => new UTCDateTime(is_numeric($value) ? $value : new DateTimeImmutable($value)),
+ 'bson_binary' => new Binary(base64_decode($value)),
+ default => throw new InvalidArgumentException(sprintf('Yaml tag "%s" is not supported.', $object->getTag())),
+ };
+ }
+
+ if (is_array($object)) {
+ foreach ($object as $key => $value) {
+ $object[$key] = $this->convertYamlTaggedValues($value);
+ }
+
+ return $object;
+ }
+
+ if (is_object($object)) {
+ foreach (get_object_vars($object) as $key => $value) {
+ $object->{$key} = $this->convertYamlTaggedValues($value);
+ }
+
+ return $object;
+ }
+
+ return $object;
+ }
+}
diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index ace2991ac..de542ac64 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -12,10 +12,15 @@
benchmark/src
src
examples
+ generator/src
+ generator/config
tests
tools
rector.php
+
+ src/Builder/(Accumulator|Expression|Query|Projection|Stage)/*\.php
+
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
index 8589b8024..6c323fe23 100644
--- a/psalm-baseline.xml
+++ b/psalm-baseline.xml
@@ -1,5 +1,5 @@
-
+
name]]>
+
+
+
+
+ recursiveEncode($value)]]>
+
+
+ 0]]>
+
+