{"record":{"id":"ef301a26761c8e5d","repo":"mongodb/laravel-mongodb","slug":"the-query-and-model-parameters-of-vectorsearch-require","errorCode":null,"errorMessage":"The \"query\" and \"model\" parameters of vectorSearch() require mongodb/mongodb 2.4+.","messagePattern":"The \"query\" and \"model\" parameters of vectorSearch\\(\\) require mongodb/mongodb 2\\.4\\+\\.","errorType":"exception","errorClass":"BadMethodCallException","httpStatus":null,"severity":"error","filePath":"src/Query/Builder.php","lineNumber":1804,"sourceCode":"     * NOTE: $vectorSearch is only available for MongoDB Atlas clusters, and is not available for self-managed deployments.\n     *\n     * @see https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/\n     *\n     * @return Collection<object|array>\n     */\n    public function vectorSearch(\n        string $index,\n        string $path,\n        array|null $queryVector = null,\n        int $limit = 10,\n        bool $exact = false,\n        QueryInterface|array|null $filter = null,\n        int|null $numCandidates = null,\n        string|null $query = null,\n        string|null $model = null,\n    ): Collection {\n        if (($query !== null || $model !== null) && ! self::vectorSearchSupportsAutoEmbedding()) {\n            throw new BadMethodCallException('The \"query\" and \"model\" parameters of vectorSearch() require mongodb/mongodb 2.4+.');\n        }\n\n        // Forward named arguments to the vectorSearch stage, skip null values\n        $args = array_filter([\n            'index' => $index,\n            'limit' => $limit,\n            'path' => $path,\n            'model' => $model,\n            'exact' => $exact,\n            'filter' => $filter,\n            'numCandidates' => $numCandidates,\n            'queryVector' => $queryVector,\n            'query' => $query,\n        ], fn ($arg) => $arg !== null);\n\n        return $this->aggregate()\n            ->vectorSearch(...$args)\n            ->addFields(vectorSearchScore: ['$meta' => 'vectorSearchScore'])","sourceCodeStart":1786,"sourceCodeEnd":1822,"githubUrl":"https://github.com/mongodb/laravel-mongodb/blob/0634653039468ceb0268a69192bdac64469ed043/src/Query/Builder.php#L1786-L1822","documentation":"vectorSearch() supports the newer $vectorSearch 'query'/'model' auto-embedding parameters only when the underlying mongodb/mongodb PHP driver library is version 2.4 or newer. Calling with those named parameters against an older library throws BadMethodCallException before any query runs.","triggerScenarios":"composer.lock pins mongodb/mongodb < 2.4 while code calls ->vectorSearch(index: '...', query: 'find similar docs', model: 'voyage-3'); library upgraded laravel-mongodb but driver library lagging; feature-flagged code paths using auto-embedding in mixed-version environments.","commonSituations":"Missing composer update after adopting vector search with embeddings; partial dependency upgrades in monorepos; documenting/deploying code written against newer driver API.","solutions":["Run composer update mongodb/mongodb to get >= 2.4 (verify with composer show mongodb/mongodb).","Require the version explicitly: composer require mongodb/mongodb:^2.4.","Until upgraded, omit query/model and pass an explicit 'queryVector' float array so the call works on older drivers.","Check self::vectorSearchSupportsAutoEmbedding() (or version_compare on InstalledVersions) before using the parameters."],"exampleFix":"// before\n$docs = $builder->vectorSearch(index: 'vsi', path: 'embedding', query: 'find similar', model: 'voyage-3', limit: 5);\n// after\n$docs = $builder->vectorSearch(index: 'vsi', path: 'embedding', queryVector: $embedding, limit: 5);","handlingStrategy":"fallback","validationCode":"$supports = \\Composer\\InstalledVersions::satisfies(\n    new \\Composer\\Semver\\VersionParser(), 'mongodb/mongodb', '>=2.4'\n);\nif (!$supports) {\n    throw new \\RuntimeException('Upgrade mongodb/mongodb to >=2.4 for query/model vector search');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin mongodb/mongodb ^2.4 in composer.json when using auto-embedding.","Keep composer.lock and laravel-mongodb versions in sync.","Feature-flag query/model usage behind a driver version check."],"tags":["php","laravel-mongodb","vector-search","dependency-version"],"backgroundTag":"missing-optional-dependency","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"}