mongodb/laravel-mongodb · error · BadMethodCallException

This method is not supported by MongoDB. Use vectorSearch()…

Error message

This method is not supported by MongoDB. Use vectorSearch() instead, which returns vectorSearchScore in the result.

What it means

selectVectorDistance selects a computed vector distance column in SQL builders; MongoDB cannot compute it as a select alias, so the builder throws BadMethodCallException and points to vectorSearch(), whose results include a vectorSearchScore field.

Solutions

Use vectorSearch() and read the vectorSearchScore field from each result instead of a distance column
Map/scale vectorSearchScore client-side if an actual distance value is required
Catch BadMethodCallException and switch the projection code to vectorSearch results

Example fix

// before
$rows = Doc::selectVectorDistance('embedding', $vec, 'distance')->get();
// after
$rows = Doc::vectorSearch('embedding', $vec)->get(); // each has $row->vectorSearchScore

Defensive patterns

Strategy: try-catch

Type guard

if ($builder instanceof MongoDB\Query\Builder) { /* use vectorSearch and read vectorSearchScore */ }

Try / catch

try { $rows = $q->selectVectorDistance($col, $vec)->get(); } catch (\BadMethodCallException $e) { $rows = $q->vectorSearch($col, $vec)->get(); }

Prevention

Consume vectorSearchScore from vectorSearch results instead of a distance alias
Handle vector-score-to-distance conversion client-side if needed
Keep projection logic connection-specific

When it happens

Trigger: Calling ->selectVectorDistance($column, $vector, $as) on a MongoDB-backed query builder.

Common situations: Ported pgvector code reading distance values per row; portable Laravel vector abstractions running against MongoDB after upgrading to Laravel >= 13.0.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of mongodb/laravel-mongodb@0634653039 (2026-09-15). Data as JSON: /api/errors/51167462fb4dd92e. Report an issue: GitHub.

Appendix: source

Thrown at src/Query/Builder.php:2053

     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.
     */
    public function orWhereVectorDistanceLessThan($column, $vector, $maxDistance)
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() with the $filter parameter instead.');
    }

    /**
     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() instead, which returns vectorSearchScore in the result.
     */
    public function selectVectorDistance($column, $vector, $as = null)
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() instead, which returns vectorSearchScore in the result.');
    }

    /**
     * Base method from Laravel >= 13.0
     * ToDo: mark as `#[Override]` when we drop support for Laravel < 13.0
     *
     * @internal This method is not supported by MongoDB. Use vectorSearch() instead, which returns results ordered by vector score.
     */
    public function orderByVectorDistance($column, $vector = [])
    {
        throw new BadMethodCallException('This method is not supported by MongoDB. Use vectorSearch() instead, which returns results ordered by vector score.');
    }
}

View on GitHub (pinned to 0634653039)