accumulator.yaml

# $schema: ../schema.json
name: $accumulator
link: https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/
type:
    - accumulator
encode: object
description: |
    Defines a custom accumulator function.
    New in MongoDB 4.4.
arguments:
    -
        name: init
        type:
            - javascript
        description: |
            Function used to initialize the state. The init function receives its arguments from the initArgs array expression. You can specify the function definition as either BSON type Code or String.
    -
        name: initArgs
        type:
            - resolvesToArray
        optional: true
        description: |
            Arguments passed to the init function.
    -
        name: accumulate
        type:
            - javascript
        description: |
            Function used to accumulate documents. The accumulate function receives its arguments from the current state and accumulateArgs array expression. The result of the accumulate function becomes the new state. You can specify the function definition as either BSON type Code or String.
    -
        name: accumulateArgs
        type:
            - resolvesToArray
        description: |
            Arguments passed to the accumulate function. You can use accumulateArgs to specify what field value(s) to pass to the accumulate function.
    -
        name: merge
        type:
            - javascript
        description: |
            Function used to merge two internal states. merge must be either a String or Code BSON type. merge returns the combined result of the two merged states. For information on when the merge function is called, see Merge Two States with $merge.
    -
        name: finalize
        type:
            - javascript
        optional: true
        description: |
            Function used to update the result of the accumulation.
    -
        name: lang
        type:
            - string
        description: |
            The language used in the $accumulator code.
tests:
    -
        name: Use $accumulator to Implement the $avg Operator
        link: https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/#use--accumulator-to-implement-the--avg-operator
        pipeline:
            -
                $group:
                    _id: $author
                    avgCopies:
                        $accumulator:
                            init:
                                $code: |-
                                    function() {
                                        return { count: 0, sum: 0 }
                                    }
                            accumulate:
                                $code: |-
                                    function(state, numCopies) {
                                        return { count: state.count + 1, sum: state.sum + numCopies }
                                    }
                            accumulateArgs:
                                - $copies
                            merge:
                                $code: |-
                                    function(state1, state2) {
                                        return {
                                            count: state1.count + state2.count,
                                            sum: state1.sum + state2.sum
                                        }
                                    }
                            finalize:
                                $code: |-
                                    function(state) {
                                        return (state.sum / state.count)
                                    }
                            lang: js
        schema:
            books:
                _id:
                    types:
                        -
                            bsonType: Number
                title:
                    types:
                        -
                            bsonType: String
                author:
                    types:
                        -
                            bsonType: String
                copies:
                    types:
                        -
                            bsonType: Number
    -
        name: Use initArgs to Vary the Initial State by Group
        link: https://www.mongodb.com/docs/manual/reference/operator/aggregation/accumulator/#use-initargs-to-vary-the-initial-state-by-group
        pipeline:
            -
                $group:
                    _id:
                        city: $city
                    restaurants:
                        $accumulator:
                            init:
                                $code: |-
                                    function(city, userProfileCity) {
                                        return { max: city === userProfileCity ? 3 : 1, restaurants: [] }
                                    }
                            initArgs:
                                - $city
                                - Bettles
                            accumulate:
                                $code: |-
                                    function(state, restaurantName) {
                                        if (state.restaurants.length < state.max) {
                                            state.restaurants.push(restaurantName);
                                        }
                                        return state;
                                    }
                            accumulateArgs:
                                - $name
                            merge:
                                $code: |-
                                    function(state1, state2) {
                                        return {
                                            max: state1.max,
                                            restaurants: state1.restaurants.concat(state2.restaurants).slice(0, state1.max)
                                        }
                                    }
                            finalize:
                                $code: |-
                                    function(state) {
                                        return state.restaurants
                                    }
                            lang: js
        schema:
            restaurants:
                _id:
                    types:
                        -
                            bsonType: Number
                name:
                    types:
                        -
                            bsonType: String
                city:
                    types:
                        -
                            bsonType: String
                cuisine:
                    types:
                        -
                            bsonType: String