{"record":{"id":"bbb8ddfcb6db1bd4","repo":"mongodb/laravel-mongodb","slug":"aggregating-by-group-requires-zero-or-one-columns","errorCode":null,"errorMessage":"Aggregating by group requires zero or one columns.","messagePattern":"Aggregating by group requires zero or one columns\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Query/Builder.php","lineNumber":640,"sourceCode":"        }\n\n        if (isset($results[0])) {\n            $result = (array) $results[0];\n\n            return $result['aggregate'];\n        }\n    }\n\n    /**\n     * @param string $function\n     * @param array  $columns\n     *\n     * @return mixed\n     */\n    public function aggregateByGroup(string $function, array $columns = ['*'])\n    {\n        if (count($columns) > 1) {\n            throw new InvalidArgumentException('Aggregating by group requires zero or one columns.');\n        }\n\n        return $this->aggregate($function, $columns);\n    }\n\n    /** @inheritdoc */\n    #[Override]\n    public function exists()\n    {\n        return $this->first(['id']) !== null;\n    }\n\n    /** @inheritdoc */\n    public function distinct($column = false)\n    {\n        $this->distinct = true;\n\n        if ($column) {","sourceCodeStart":622,"sourceCodeEnd":658,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/Query/Builder.php#L622-L658","documentation":"aggregateByGroup implements Laravel's group-wise aggregation on MongoDB by wrapping the aggregate call in a single group stage, so the MongoDB pipeline can only handle zero or one column; more than one column cannot be mapped to the pipeline and triggers this InvalidArgumentException. Callers like count/avg-per-group with a single column work; passing multiple columns does not.","triggerScenarios":"Calling ->groupBy('category')->aggregateByGroup('avg', ['price', 'quantity']) — count($columns) > 1.","commonSituations":"Developers trying to aggregate several fields at once per group, e.g. avg price and sum quantity in a single call.","solutions":["Pass a single column: aggregateByGroup('avg', ['price']).","Call aggregateByGroup once per aggregated field.","Or build the group pipeline manually with aggregateRaw()/addRawStage('$group', ...) to combine multiple accumulators."],"exampleFix":"// before\n->groupBy('category')->aggregateByGroup('avg', ['price', 'qty']);\n// after\n->groupBy('category')->aggregateByGroup('avg', ['price']);","handlingStrategy":"validation","validationCode":"if (is_array($columns) && count($columns) > 1) {\n    throw new InvalidArgumentException('aggregateByGroup accepts at most one column');\n}\n$query->groupBy($group)->aggregateByGroup($fn, $columns);","typeGuard":null,"tryCatchPattern":"try {\n    $value = $query->groupBy('category')->aggregateByGroup('avg', $cols);\n} catch (InvalidArgumentException $e) {\n    if (str_contains($e->getMessage(), 'zero or one columns')) {\n        $value = $query->groupBy('category')->aggregateByGroup('avg', [$cols[0]]);\n    } else { throw $e; }\n}","preventionTips":["Pass exactly one column per aggregateByGroup call","Issue separate calls for multiple metrics per group","Use a raw $group stage when combining accumulators in one pass","Validate dynamic column arrays before calling"],"tags":["aggregation","group","columns"],"backgroundTag":"invalid-argument-value","analyzedSha":"0634653039468ceb0268a69192bdac64469ed043","analyzedAt":"2026-09-15T02:56:37.067Z","contentChangedAt":"2026-09-15T02:56:37.067Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}