> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Búsqueda

> Visión general de las capacidades de búsqueda en Laravel: cómo elegir entre búsqueda de texto completo, búsqueda vectorial, rerank y Laravel Scout según tus necesidades.

## Introducción

Hay varias formas de añadir búsqueda a una aplicación en función de las necesidades. Laravel proporciona herramientas integradas que cubren desde coincidencia por palabras clave hasta búsqueda semántica con IA, sin necesidad de servicios externos.

```mermaid theme={null}
flowchart TD
    Q["Requisito de búsqueda"]
    Q --> A{"¿Basta con coincidencia por palabra clave?"}
    A -->|Sí| B["Búsqueda de texto completo<br>whereFullText"]
    A -->|No, quiero coincidencia semántica| C["Búsqueda vectorial<br>whereVectorSimilarTo"]
    Q --> D{"¿Necesitas sincronización automática de modelos?"}
    D -->|Sí| E["Laravel Scout<br>Trait Searchable"]
    Q --> F{"¿Reordenar los resultados con IA?"}
    F -->|Sí| G["Rerank<br>AI SDK Reranking"]
```

### Comparativa

| Función                | Servicio externo               | Características                                                    |
| ---------------------- | ------------------------------ | ------------------------------------------------------------------ |
| `whereFullText`        | No                             | Índice de texto completo integrado en MariaDB / MySQL / PostgreSQL |
| `whereVectorSimilarTo` | No (PostgreSQL + pgvector)     | Búsqueda por similitud semántica. Requiere AI SDK                  |
| `Reranking`            | Proveedor de IA                | Reordena cualquier conjunto de resultados por relevancia con IA    |
| Laravel Scout          | No (motor database) / opcional | Sincroniza automáticamente los modelos Eloquent con el índice      |

***

## Búsqueda de texto completo

Las consultas `LIKE` funcionan para coincidencias parciales sencillas, pero no entienden el idioma. La búsqueda de texto completo usa índices dedicados que tienen en cuenta límites de palabra, flexiones y puntuación de relevancia.

MariaDB, MySQL y PostgreSQL admiten búsqueda de texto completo integrada, sin necesidad de servicios externos.

<Warning>
  La búsqueda de texto completo está soportada en MariaDB, MySQL y PostgreSQL.
</Warning>

### Añadir un índice full-text

Añade un índice full-text a las columnas objetivo.

```php theme={null}
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();

    $table->fullText(['title', 'body']); // Índice compuesto
});
```

En PostgreSQL puedes indicar el idioma del índice. En idiomas distintos del inglés cambia el tratamiento de las flexiones.

```php theme={null}
$table->fullText('body')->language('english');
```

Consulta [Migraciones](/es/migrations) para los detalles.

<Info>
  **Notas sobre búsqueda de texto en japonés**\
  La búsqueda de texto en japonés con MySQL tiene ciertas limitaciones. En AWS RDS solo está disponible el parser N-gram y no se puede añadir el plugin de análisis morfológico (MeCab). El MySQL de Laravel Cloud probablemente tenga las mismas limitaciones. En PostgreSQL el soporte para flexiones en japonés también es limitado. Si la precisión en japonés es crítica, considera motores dedicados como Meilisearch o Typesense.
</Info>

### Ejecutar consultas full-text

Con el índice creado, busca con `whereFullText`. Laravel genera el SQL adecuado según el driver (`MATCH(...) AGAINST(...)` en MariaDB/MySQL, `to_tsvector(...) @@ plainto_tsquery(...)` en PostgreSQL).

```php theme={null}
$articles = Article::whereFullText('body', 'web developer')->get();
```

Con un índice compuesto, pasa el mismo array de columnas.

```php theme={null}
$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();
```

<Info>
  En MariaDB/MySQL los resultados se ordenan automáticamente por relevancia. En PostgreSQL `whereFullText` solo filtra los registros que coinciden, sin ordenar por relevancia. Para orden automático por relevancia en PostgreSQL, el [motor database de Scout](#laravel-scout) es útil.
</Info>

El método `orWhereFullText` permite añadir la búsqueda como condición OR. Consulta el [query builder](/es/query-builder).

***

## Búsqueda semántica / vectorial

La búsqueda de texto completo depende de la coincidencia de palabras. La búsqueda vectorial usa un enfoque distinto: representa el *significado* del texto como un array numérico (embedding) generado por IA y busca resultados semánticamente cercanos.

Por ejemplo, la consulta "best wineries in Napa Valley" puede encontrar el artículo titulado "Top Vineyards to Visit" aunque no coincidan las palabras, porque su significado es cercano.

<Note>
  La búsqueda vectorial requiere el [AI SDK de Laravel](/es/ai-sdk) y soporta PostgreSQL (con la extensión `pgvector`) y MongoDB (con el paquete Laravel MongoDB). En [Laravel Cloud](https://laravel.com/cloud) todos los Postgres tienen `pgvector` ya preinstalado.
</Note>

### Generación de embeddings

Un embedding es un array numérico de alta dimensión (normalmente cientos o miles de dimensiones) que representa el significado del texto. Genera embeddings con `toEmbeddings` de la clase `Stringable`.

```php theme={null}
use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
```

Para procesar varias cadenas a la vez es más eficiente usar `Embeddings` (solo una llamada a la API).

```php theme={null}
use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    'Napa Valley has great wine.',
    'Laravel is a PHP framework.',
])->generate();

$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]
```

Consulta la [documentación del AI SDK](/es/ai-sdk) para la configuración de proveedores y las dimensiones.

### Almacenamiento e indexación de vectores

Para guardar los embeddings define una columna `vector` en la migración. Ajusta `dimensions` a la salida del proveedor (p. ej., `text-embedding-3-small` de OpenAI: 1536 dimensiones). Llama a `index()` para crear un índice HNSW que acelera la búsqueda por similitud en grandes volúmenes.

```php theme={null}
Schema::ensureVectorExtensionExists(); // Habilita la extensión pgvector

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});
```

En el modelo Eloquent castea la columna a `array` para automatizar la conversión entre PHP y el formato vectorial.

```php theme={null}
protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}
```

Consulta [Migraciones](/es/migrations) para los detalles de columnas e índices vectoriales.

### Búsqueda por similitud

Con embeddings guardados, busca similares con `whereVectorSimilarTo`. Se compara con similitud coseno, se filtran los resultados por debajo del umbral `minSimilarity` y se ordenan automáticamente por relevancia. El umbral va de `0.0` a `1.0` (siendo `1.0` coincidencia exacta).

```php theme={null}
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();
```

Si pasas una cadena en lugar del array de embedding, Laravel genera automáticamente el embedding. Puedes pasar directamente la consulta del usuario.

```php theme={null}
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();
```

Para más control existen `whereVectorDistanceLessThan`, `selectVectorDistance` y `orderByVectorDistance`. Consulta el [query builder](/es/query-builder) y la [documentación del AI SDK](/es/ai-sdk).

***

## Rerank

El rerank consiste en que un modelo de IA reordena un conjunto de resultados por relevancia respecto a la consulta. A diferencia de la búsqueda vectorial, no necesitas calcular y guardar embeddings; se aplica sobre cualquier colección de textos.

El patrón "**buscar → rerank**" es especialmente eficaz: filtras rápido muchos registros con full-text y luego aplicas rerank con IA. Combina la velocidad de la BD con la precisión de la IA.

```php theme={null}
use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
```

Las colecciones de Laravel tienen la macro `rerank`, que permite reordenar resultados Eloquent pasando un campo (o closure) y la consulta.

```php theme={null}
$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');
```

Consulta la [documentación del AI SDK](/es/ai-sdk) para configurar el proveedor de reranking y las opciones disponibles.

***

## Laravel Scout

Todas las técnicas anteriores llamaban directamente al query builder. [Laravel Scout](/es/scout) toma otro enfoque: al añadir el trait `Searchable` a un modelo Eloquent, Scout mantiene sincronizados los índices de búsqueda con la creación/actualización/eliminación de registros.

### Motor database

El motor database de Scout usa búsqueda full-text y consultas `LIKE` sobre la base de datos existente. No necesita servicios externos ni infraestructura adicional.

En `toSearchableArray` defines las columnas indexables. Los atributos PHP permiten indicar la estrategia por columna.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
use Laravel\Scout\Searchable;

class Article extends Model
{
    use Searchable;

    #[SearchUsingPrefix(['id'])]
    #[SearchUsingFullText(['title', 'body'])]
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}
```

| Atributo              | Estrategia                                               |
| --------------------- | -------------------------------------------------------- |
| `SearchUsingFullText` | Usa índice full-text (`MATCH...AGAINST` / `to_tsvector`) |
| `SearchUsingPrefix`   | Prefijo (`example%`)                                     |
| Ninguno               | Comodines por ambos lados (`%example%`)                  |

<Warning>
  Las columnas con `SearchUsingFullText` requieren un [índice full-text](/es/migrations).
</Warning>

Añadido el trait, busca con `search`. El motor database de Scout devuelve resultados ordenados por relevancia también en PostgreSQL.

```php theme={null}
$articles = Article::search('Laravel')->get();
```

### Motores de terceros

Scout también soporta motores de búsqueda como [Algolia](https://www.algolia.com/), [Meilisearch](https://www.meilisearch.com) o [Typesense](https://typesense.org). Ofrecen tolerancia a errores tipográficos, búsqueda facetada, geobúsqueda, ranking personalizado, etc.

Scout ofrece una API unificada, por lo que migrar del motor database a uno de terceros implica cambios de código mínimos.

<Note>
  La mayoría de aplicaciones no necesitan un motor externo. Las técnicas integradas de esta página cubren la mayor parte de los casos.
</Note>

Consulta la [guía de Laravel Scout](/es/scout).

***

## Combinación de técnicas

Las técnicas anteriores no son excluyentes; combinándolas se obtienen los mejores resultados.

### Full-text + rerank

Filtra candidatos rápido con full-text y reordénalos por relevancia semántica con rerank. Combina velocidad de la BD y precisión de la IA.

```php theme={null}
$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);
```

### Búsqueda vectorial + filtros clásicos

Combina similitud vectorial con `where` normales para acotar a un subconjunto (por equipo, categoría…) mientras haces búsqueda semántica.

```php theme={null}
$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();
```

***

## Páginas relacionadas

<Card title="Laravel Scout" icon="magnifying-glass" href="/es/scout">
  Guía completa para sincronizar automáticamente los modelos con el trait Searchable.
</Card>

<Card title="Laravel AI SDK" icon="sparkles" href="/es/ai-sdk">
  Configuración del AI SDK necesaria para embeddings y reranking.
</Card>

<Card title="Query Builder" icon="database" href="/es/query-builder">
  Detalles de whereFullText, whereVectorSimilarTo y demás métodos.
</Card>

<Card title="Migraciones" icon="table" href="/es/migrations">
  Cómo crear índices full-text y columnas vectoriales.
</Card>


## Related topics

- [Laravel Scout](/es/scout.md)
- [Basic client - Laravel Bluesky](/es/packages/laravel-bluesky/basic-client.md)
- [Actualización de Laravel — Marzo de 2026](/es/blog/changelog/202603.md)
- [Laravel AI SDK](/es/ai-sdk.md)
- [MongoDB](/es/mongodb.md)