fix: add support for pre-computed tsvector columns

Author: alexnogueirasilva

src/Filter.php

@@ -114,6 +114,8 @@ class Filter
 
     protected bool $fullTextPrefixMatch = true;
 
+    protected bool $isTsVector = false;
+
     /**
      * Create a new filter instance
      *
@@ -618,6 +620,22 @@ public function setFullTextPrefixMatch(bool $prefixMatch): self
         return $this;
     }
 
+    /**
+     * Mark the column as a pre-computed tsvector column
+     *
+     * When enabled, the filter will use the column directly with @@ operator
+     * instead of converting it to tsvector at query time. This is much faster
+     * when you have a GIN-indexed tsvector column.
+     *
+     * @param  bool  $isTsVector  If true, treats the column as a tsvector type
+     */
+    public function useTsVector(bool $isTsVector = true): self
+    {
+        $this->isTsVector = $isTsVector;
+
+        return $this;
+    }
+
     /**
      * Get the processed value for this filter
      *
@@ -914,6 +932,14 @@ public function getFullTextPrefixMatch(): bool
         return $this->fullTextPrefixMatch;
     }
 
+    /**
+     * Check if the column is a pre-computed tsvector column
+     */
+    public function isTsVector(): bool
+    {
+        return $this->isTsVector;
+    }
+
     /**
      * Get the formatted attribute for SQL queries
      */

src/Traits/Filterable.php

@@ -466,9 +466,10 @@ private function applyFullTextSearch(Builder $builder, Filter $filter, mixed $se
         $columns = $filter->getFullTextColumns() ?? [$filter->getAttribute()];
         $language = $filter->getFullTextLanguage();
         $prefixMatch = $filter->getFullTextPrefixMatch();
+        $isTsVector = $filter->isTsVector();
 
         if ($filter->isUsingPostgreSQL()) {
-            $this->applyPostgreSQLFullTextSearch($builder, $searchTerm, $columns, $language, $prefixMatch);
+            $this->applyPostgreSQLFullTextSearch($builder, $searchTerm, $columns, $language, $prefixMatch, $isTsVector);
 
             return;
         }
@@ -481,12 +482,13 @@ private function applyFullTextSearch(Builder $builder, Filter $filter, mixed $se
      *
      * @param  array<int, string>  $columns
      */
-    private function applyPostgreSQLFullTextSearch(Builder $builder, string $searchTerm, array $columns, ?string $language, bool $prefixMatch): void
+    private function applyPostgreSQLFullTextSearch(Builder $builder, string $searchTerm, array $columns, ?string $language, bool $prefixMatch, bool $isTsVector = false): void
     {
         $lang = $language ?? Config::get('app.fulltext_language', 'simple');
 
-        if (count($columns) === 1 && $columns[0] === 'search_vector') {
-            $builder->whereRaw("search_vector @@ websearch_to_tsquery('simple', ?)", [$searchTerm]);
+        if ($isTsVector && count($columns) === 1) {
+            $column = $columns[0];
+            $builder->whereRaw("{$column} @@ websearch_to_tsquery('{$lang}', ?)", [$searchTerm]);
 
             return;
         }

tests/Unit/FilterableFullTextTest.php

@@ -122,7 +122,7 @@ class FilterableFullTextTestModel extends Model
     expect(true)->toBeTrue();
 });
 
-it('uses websearch_to_tsquery for search_vector column', function (): void {
+it('uses websearch_to_tsquery for tsvector column with useTsVector', function (): void {
     global $builder, $model;
 
     $builder->shouldReceive('whereRaw')
@@ -138,13 +138,62 @@ class FilterableFullTextTestModel extends Model
 
     $filter = Filter::fullText('search_vector', 'search')
         ->setDatabaseDriver('pgsql')
+        ->useTsVector()
         ->setValue('laravel');
 
     $model->scopeFilterable($builder, [$filter]);
 
     expect(true)->toBeTrue();
 });
 
+it('uses websearch_to_tsquery for custom tsvector column name', function (): void {
+    global $builder, $model;
+
+    $builder->shouldReceive('whereRaw')
+        ->once()
+        ->withArgs(fn ($sql, $bindings): bool => str_contains((string) $sql, 'custom_fts_column') &&
+               str_contains((string) $sql, 'websearch_to_tsquery') &&
+               $bindings[0] === 'test query')
+        ->andReturnSelf();
+
+    $builder->shouldReceive('with')
+        ->zeroOrMoreTimes()
+        ->andReturnSelf();
+
+    $filter = Filter::fullText('custom_fts_column', 'q')
+        ->setDatabaseDriver('pgsql')
+        ->useTsVector()
+        ->setValue('test query');
+
+    $model->scopeFilterable($builder, [$filter]);
+
+    expect(true)->toBeTrue();
+});
+
+it('uses configured language for tsvector column', function (): void {
+    global $builder, $model;
+
+    $builder->shouldReceive('whereRaw')
+        ->once()
+        ->withArgs(fn ($sql, $bindings): bool => str_contains((string) $sql, "'portuguese'") &&
+               str_contains((string) $sql, 'websearch_to_tsquery'))
+        ->andReturnSelf();
+
+    $builder->shouldReceive('with')
+        ->zeroOrMoreTimes()
+        ->andReturnSelf();
+
+    $filter = Filter::fullText('search_vector', 'search')
+        ->setDatabaseDriver('pgsql')
+        ->useTsVector()
+        ->setFullTextLanguage('portuguese')
+        ->setValue('teste');
+
+    $model->scopeFilterable($builder, [$filter]);
+
+    expect(true)->toBeTrue();
+});
+
 it('ignores empty search terms in full-text', function (): void {
     global $builder, $model;
 

tests/Unit/FullTextSearchTest.php

@@ -82,6 +82,35 @@
         ->and($filter->getAttribute())->toBe('search_vector');
 });
 
+it('can mark column as tsvector with useTsVector', function (): void {
+    $filter = Filter::fullText('search_vector')->useTsVector();
+
+    expect($filter->isTsVector())->toBeTrue();
+});
+
+it('defaults to non-tsvector column', function (): void {
+    $filter = Filter::fullText('content');
+
+    expect($filter->isTsVector())->toBeFalse();
+});
+
+it('can disable tsvector mode', function (): void {
+    $filter = Filter::fullText('search_vector')->useTsVector()->useTsVector(false);
+
+    expect($filter->isTsVector())->toBeFalse();
+});
+
+it('can chain useTsVector with other configuration methods', function (): void {
+    $filter = Filter::fullText('custom_fts')
+        ->useTsVector()
+        ->setFullTextLanguage('portuguese')
+        ->setDatabaseDriver('pgsql');
+
+    expect($filter->isTsVector())->toBeTrue()
+        ->and($filter->getFullTextLanguage())->toBe('portuguese')
+        ->and($filter->isUsingPostgreSQL())->toBeTrue();
+});
+
 it('can configure language after creation', function (): void {
     $filter = Filter::fullText('content');