Laravel Scout

• Introducción
• Instalación
  • Colas
• Requisitos del Driver
  • Algolia
  • Meilisearch
  • Typesense
• Configuración
  • Configuración de Índices de Modelo
  • Configuración de Datos Buscables
  • Configuración del ID del Modelo
  • Configuración de Motores de Búsqueda por Modelo
  • Identificación de Usuarios
• Motores de Base de Datos / Colección
  • Motor de Base de Datos
  • Motor de Colección
• Indexación
  • Importación en Lote
  • Agregar Registros
  • Actualizar Registros
  • Eliminar Registros
  • Pausar Indexación
  • Instancias de Modelo Condicionalmente Buscables
• Búsqueda
  • Cláusulas Where
  • Paginación
  • Eliminación Suave
  • Personalización de Búsquedas en el Motor
• Motores Personalizados

#Introducción

Laravel Scout ofrece una solución simple basada en drivers para agregar búsqueda de texto completo a sus modelos Eloquent. Usando observadores de modelos, Scout mantendrá automáticamente sus índices de búsqueda sincronizados con sus registros Eloquent.

Actualmente, Scout incluye drivers para Algolia, Meilisearch, Typesense y MySQL / PostgreSQL (database). Además, Scout incluye un driver de "colección" diseñado para uso en desarrollo local que no requiere dependencias externas ni servicios de terceros. Asimismo, escribir drivers personalizados es sencillo y puede extender Scout con sus propias implementaciones de búsqueda.

#Instalación

Primero, instale Scout mediante el gestor de paquetes Composer:

composer require laravel/scout

Después de instalar Scout, debe publicar el archivo de configuración de Scout usando el comando Artisan vendor:publish. Este comando publicará el archivo de configuración scout.php en el directorio config de su aplicación:

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Finalmente, agregue el trait Laravel\Scout\Searchable al modelo que desea hacer buscable. Este trait registrará un observador de modelo que mantendrá automáticamente el modelo sincronizado con su driver de búsqueda:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

#Colas

Aunque no es estrictamente necesario para usar Scout, debería considerar seriamente configurar un driver de cola antes de usar la librería. Ejecutar un worker de cola permitirá que Scout encole todas las operaciones que sincronizan la información de su modelo con sus índices de búsqueda, proporcionando tiempos de respuesta mucho mejores para la interfaz web de su aplicación.

Una vez que haya configurado un driver de cola, establezca el valor de la opción queue en su archivo de configuración config/scout.php a true:

'queue' => true,

Incluso cuando la opción queue está configurada en false, es importante recordar que algunos drivers de Scout como Algolia y Meilisearch siempre indexan registros de forma asíncrona. Esto significa que, aunque la operación de indexación haya finalizado dentro de su aplicación Laravel, el motor de búsqueda puede no reflejar inmediatamente los registros nuevos o actualizados.

Para especificar la conexión y la cola que utilizan los trabajos de Scout, puede definir la opción de configuración queue como un arreglo:

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

Por supuesto, si personaliza la conexión y la cola que utilizan los trabajos de Scout, debe ejecutar un worker de cola para procesar los trabajos en esa conexión y cola:

php artisan queue:work redis --queue=scout

#Requisitos del Driver

#Algolia

Al usar el driver Algolia, debe configurar sus credenciales id y secret de Algolia en el archivo de configuración config/scout.php. Una vez configuradas sus credenciales, también deberá instalar el SDK PHP de Algolia mediante Composer:

composer require algolia/algoliasearch-client-php

#Meilisearch

Meilisearch es un motor de búsqueda de código abierto y extremadamente rápido. Si no sabe cómo instalar Meilisearch en su máquina local, puede usar Laravel Sail, el entorno oficial de desarrollo Docker de Laravel.

Al usar el driver Meilisearch, deberá instalar el SDK PHP de Meilisearch mediante Composer:

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

Luego, configure la variable de entorno SCOUT_DRIVER así como sus credenciales host y key de Meilisearch en el archivo .env de su aplicación:

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

Para más información sobre Meilisearch, consulte la documentación de Meilisearch.

Además, debe asegurarse de instalar una versión de meilisearch/meilisearch-php compatible con la versión binaria de Meilisearch que utiliza, revisando la documentación de Meilisearch sobre compatibilidad binaria.

#Typesense

Typesense es un motor de búsqueda de código abierto y extremadamente rápido que soporta búsqueda por palabras clave, búsqueda semántica, búsqueda geográfica y búsqueda vectorial.

Puede autoalojar Typesense o usar Typesense Cloud.

Para comenzar a usar Typesense con Scout, instale el SDK PHP de Typesense mediante Composer:

composer require typesense/typesense-php

A continuación, establezca la variable de entorno SCOUT_DRIVER, así como las credenciales del host y la clave API de Typesense, en el archivo .env de su aplicación:

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

Si es necesario, también puede especificar el puerto, la ruta y el protocolo de su instalación:

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Configuraciones adicionales y definiciones de esquema para sus colecciones de Typesense pueden encontrarse en el archivo de configuración config/scout.php de su aplicación. Para más información sobre Typesense, consulte la documentación de Typesense.

#Preparación de Datos para Almacenamiento en Typesense

Al utilizar Typesense, su modelo buscable debe definir un método toSearchableArray que convierta la clave primaria del modelo a string y la fecha de creación a un timestamp UNIX:

/**
 * Obtener el arreglo de datos indexables para el modelo.
 *
 * @return array<string, mixed>
 */
public function toSearchableArray()
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

También debe definir los esquemas de sus colecciones Typesense en el archivo config/scout.php de su aplicación. Un esquema de colección describe los tipos de datos de cada campo que es buscable mediante Typesense. Para más información sobre todas las opciones de esquema disponibles, consulte la documentación de Typesense.

Si necesita cambiar el esquema de su colección Typesense después de haberlo definido, puede ejecutar scout:flush y scout:import, lo que eliminará todos los datos indexados existentes y recreará el esquema. O bien, puede usar la API de Typesense para modificar el esquema de la colección sin eliminar datos indexados.

Si su modelo buscable utiliza eliminación suave, debe definir un campo __soft_deleted en el esquema Typesense correspondiente dentro del archivo config/scout.php de su aplicación:

User::class => [
    'collection-schema' => [
        'fields' => [
            // ...
            [
                'name' => '__soft_deleted',
                'type' => 'int32',
                'optional' => true,
            ],
        ],
    ],
],

#Parámetros Dinámicos de Búsqueda

Typesense le permite modificar sus parámetros de búsqueda dinámicamente al realizar una operación de búsqueda mediante el método options:

use App\Models\Todo;

Todo::search('Groceries')->options([
    'query_by' => 'title, description'
])->get();

#Configuración

#Configuración de Índices de Modelo

Cada modelo Eloquent se sincroniza con un "índice" de búsqueda dado, que contiene todos los registros buscables para ese modelo. En otras palabras, puede pensar en cada índice como una tabla MySQL. Por defecto, cada modelo se persistirá en un índice que coincide con el nombre típico de la "tabla" del modelo. Normalmente, esta es la forma plural del nombre del modelo; sin embargo, puede personalizar el índice del modelo sobrescribiendo el método searchableAs en el modelo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * Obtener el nombre del índice asociado con el modelo.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

#Configuración de Datos Buscables

Por defecto, toda la forma toArray de un modelo dado se persistirá en su índice de búsqueda. Si desea personalizar los datos que se sincronizan con el índice de búsqueda, puede sobrescribir el método toSearchableArray en el modelo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * Obtener el arreglo de datos indexables para el modelo.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Personalizar el arreglo de datos...

        return $array;
    }
}

Algunos motores de búsqueda como Meilisearch solo realizarán operaciones de filtro (>, <, etc.) en datos del tipo correcto. Por lo tanto, al usar estos motores y personalizar sus datos buscables, debe asegurarse de que los valores numéricos se conviertan a su tipo correcto:

public function toSearchableArray()
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

#Configuración de Datos Filtrables y Ajustes de Índice (Meilisearch)

A diferencia de otros drivers de Scout, Meilisearch requiere que predefina configuraciones de búsqueda del índice como atributos filtrables, atributos ordenables y otros campos de configuración soportados.

Los atributos filtrables son aquellos sobre los que planea filtrar al invocar el método where de Scout, mientras que los atributos ordenables son aquellos por los que planea ordenar al invocar el método orderBy de Scout. Para definir la configuración de su índice, ajuste la sección index-settings de la entrada meilisearch en el archivo de configuración scout de su aplicación:

use App\Models\User;
use App\Models\Flight;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes'=> ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
            // Otros campos de configuración...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

Si el modelo subyacente de un índice dado es soft deletable y está incluido en el arreglo index-settings, Scout incluirá automáticamente soporte para filtrar modelos soft deleted en ese índice. Si no tiene otros atributos filtrables u ordenables para definir en un índice de modelo soft deletable, puede simplemente agregar una entrada vacía en el arreglo index-settings para ese modelo:

'index-settings' => [
    Flight::class => []
],

Después de configurar los ajustes de índice de su aplicación, debe invocar el comando Artisan scout:sync-index-settings. Este comando informará a Meilisearch sobre la configuración actual de sus índices. Para mayor comodidad, puede incluir este comando en su proceso de despliegue:

php artisan scout:sync-index-settings

#Configuración del ID del Modelo

Por defecto, Scout usará la clave primaria del modelo como el ID / clave única que se almacena en el índice de búsqueda. Si necesita personalizar este comportamiento, puede sobrescribir los métodos getScoutKey y getScoutKeyName en el modelo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class User extends Model
{
    use Searchable;

    /**
     * Obtener el valor usado para indexar el modelo.
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * Obtener el nombre de la clave usada para indexar el modelo.
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

#Configuración de Motores de Búsqueda por Modelo

Al buscar, Scout normalmente usará el motor de búsqueda predeterminado especificado en el archivo de configuración scout de su aplicación. Sin embargo, el motor de búsqueda para un modelo particular puede cambiarse sobrescribiendo el método searchableUsing en el modelo:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Engines\Engine;
use Laravel\Scout\EngineManager;
use Laravel\Scout\Searchable;

class User extends Model
{
    use Searchable;

    /**
     * Obtener el motor usado para indexar el modelo.
     */
    public function searchableUsing(): Engine
    {
        return app(EngineManager::class)->engine('meilisearch');
    }
}

#Identificación de Usuarios

Scout también permite identificar automáticamente a los usuarios al usar Algolia. Asociar al usuario autenticado con las operaciones de búsqueda puede ser útil para ver sus análisis de búsqueda dentro del panel de Algolia. Puede habilitar la identificación de usuarios definiendo una variable de entorno SCOUT_IDENTIFY como true en el archivo .env de su aplicación:

SCOUT_IDENTIFY=true

Al habilitar esta función, también se enviará la dirección IP de la solicitud y el identificador principal del usuario autenticado a Algolia para que estos datos se asocien con cualquier solicitud de búsqueda realizada por el usuario.

#Motores de Base de Datos / Colección

#Motor de Base de Datos

Si su aplicación interactúa con bases de datos pequeñas o medianas o tiene una carga ligera, puede encontrar más conveniente comenzar con el motor "database" de Scout. Este motor usará cláusulas "where like" e índices de texto completo al filtrar resultados de su base de datos existente para determinar los resultados aplicables a su consulta.

Para usar el motor de base de datos, simplemente establezca el valor de la variable de entorno SCOUT_DRIVER a database, o especifique el driver database directamente en el archivo de configuración scout de su aplicación:

SCOUT_DRIVER=database

Una vez que haya especificado el motor de base de datos como su driver preferido, debe configurar sus datos buscables. Luego, puede comenzar a ejecutar consultas de búsqueda contra sus modelos. La indexación del motor de búsqueda, como la necesaria para poblar índices de Algolia, Meilisearch o Typesense, no es necesaria al usar el motor de base de datos.

#Personalización de Estrategias de Búsqueda en Base de Datos

Por defecto, el motor de base de datos ejecutará una consulta "where like" contra cada atributo del modelo que haya configurado como buscable. Sin embargo, en algunas situaciones esto puede resultar en un rendimiento pobre. Por lo tanto, la estrategia de búsqueda del motor de base de datos puede configurarse para que algunas columnas específicas utilicen consultas de texto completo o solo usen restricciones "where like" para buscar prefijos de cadenas (example%) en lugar de buscar dentro de toda la cadena (%example%).

Para definir este comportamiento, puede asignar atributos PHP al método toSearchableArray de su modelo. Cualquier columna que no reciba un comportamiento adicional de estrategia de búsqueda continuará usando la estrategia predeterminada "where like":

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

/**
 * Obtener el arreglo de datos indexables para el modelo.
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

#Motor de Colección

Aunque puede usar los motores de búsqueda Algolia, Meilisearch o Typesense durante el desarrollo local, puede encontrar más conveniente comenzar con el motor "collection". Este motor usará cláusulas "where" y filtrado de colecciones en los resultados de su base de datos existente para determinar los resultados aplicables a su consulta. Al usar este motor, no es necesario "indexar" sus modelos buscables, ya que simplemente se recuperarán de su base de datos local.

Para usar el motor de colección, simplemente establezca el valor de la variable de entorno SCOUT_DRIVER a collection, o especifique el driver collection directamente en el archivo de configuración scout de su aplicación:

SCOUT_DRIVER=collection

Una vez que haya especificado el driver de colección como su driver preferido, puede comenzar a ejecutar consultas de búsqueda contra sus modelos. La indexación del motor de búsqueda, como la necesaria para poblar índices de Algolia, Meilisearch o Typesense, no es necesaria al usar el motor de colección.

#Diferencias con el Motor de Base de Datos

A primera vista, los motores "database" y "collection" son bastante similares. Ambos interactúan directamente con su base de datos para recuperar resultados de búsqueda. Sin embargo, el motor de colección no utiliza índices de texto completo ni cláusulas LIKE para encontrar registros coincidentes. En cambio, recupera todos los registros posibles y usa el helper Str::is de Laravel para determinar si la cadena de búsqueda existe dentro de los valores de los atributos del modelo.

El motor de colección es el motor de búsqueda más portátil ya que funciona con todas las bases de datos relacionales soportadas por Laravel (incluyendo SQLite y SQL Server); sin embargo, es menos eficiente que el motor de base de datos de Scout.

#Indexación

#Importación en Lote

Si está instalando Scout en un proyecto existente, puede que ya tenga registros en la base de datos que necesite importar a sus índices. Scout proporciona un comando Artisan scout:import que puede usar para importar todos sus registros existentes a sus índices de búsqueda:

php artisan scout:import "App\Models\Post"

El comando flush puede usarse para eliminar todos los registros de un modelo de sus índices de búsqueda:

php artisan scout:flush "App\Models\Post"

#Modificación de la Consulta de Importación

Si desea modificar la consulta que se usa para recuperar todos sus modelos para la importación en lote, puede definir un método makeAllSearchableUsing en su modelo. Este es un buen lugar para agregar cualquier carga anticipada de relaciones que pueda ser necesaria antes de importar sus modelos:

use Illuminate\Database\Eloquent\Builder;

/**
 * Modificar la consulta usada para recuperar modelos al hacer todos los modelos buscables.
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

#Agregar Registros

Una vez que haya agregado el trait Laravel\Scout\Searchable a un modelo, solo necesita save o create una instancia del modelo y se agregará automáticamente a su índice de búsqueda. Si ha configurado Scout para usar colas, esta operación se realizará en segundo plano por su worker de cola:

use App\Models\Order;

$order = new Order;

// ...

$order->save();

#Agregar Registros mediante Consulta

Si desea añadir una colección de modelos a su índice de búsqueda mediante una consulta Eloquent, puede encadenar el método searchable a la consulta Eloquent. El método searchable procesará los resultados por lotes de la consulta y añadirá los registros a su índice de búsqueda. Nuevamente, si ha configurado Scout para usar colas, todos los lotes se importarán en segundo plano por sus trabajadores de cola:

use App\Models\Order;

Order::where('price', '>', 100)->searchable();

También puede llamar al método searchable en una instancia de relación Eloquent:

$user->orders()->searchable();

O, si ya tiene una colección de modelos Eloquent en memoria, puede llamar al método searchable en la instancia de la colección para agregar las instancias del modelo a su índice correspondiente:

$orders->searchable();

#Actualizar Registros

Para actualizar un modelo buscable, solo necesita actualizar las propiedades de la instancia del modelo y save el modelo en su base de datos. Scout persistirá automáticamente los cambios en su índice de búsqueda:

use App\Models\Order;

$order = Order::find(1);

// Actualizar la orden...

$order->save();

También puede invocar el método searchable en una instancia de consulta Eloquent para actualizar una colección de modelos. Si los modelos no existen en su índice de búsqueda, serán creados:

Order::where('price', '>', 100)->searchable();

Si desea actualizar los registros del índice de búsqueda para todos los modelos en una relación, puede invocar searchable en la instancia de la relación:

$user->orders()->searchable();

O, si ya tiene una colección de modelos Eloquent en memoria, puede llamar al método searchable en la instancia de la colección para actualizar las instancias del modelo en su índice correspondiente:

$orders->searchable();

#Modificar Registros Antes de Importar

A veces puede necesitar preparar la colección de modelos antes de hacerlos buscables. Por ejemplo, puede querer cargar anticipadamente una relación para que los datos de la relación puedan agregarse eficientemente a su índice de búsqueda. Para lograr esto, defina un método makeSearchableUsing en el modelo correspondiente:

use Illuminate\Database\Eloquent\Collection;

/**
 * Modificar la colección de modelos que se están haciendo buscables.
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

#Eliminar Registros

Para eliminar un registro de su índice, simplemente puede delete el modelo de la base de datos. Esto puede hacerse incluso si está usando modelos soft deleted:

use App\Models\Order;

$order = Order::find(1);

$order->delete();

Si no desea recuperar el modelo antes de eliminar el registro, puede usar el método unsearchable en una instancia de consulta Eloquent:

Order::where('price', '>', 100)->unsearchable();

Si desea eliminar los registros del índice de búsqueda para todos los modelos en una relación, puede invocar unsearchable en la instancia de la relación:

$user->orders()->unsearchable();

O, si ya tiene una colección de modelos Eloquent en memoria, puede llamar al método unsearchable en la instancia de la colección para eliminar las instancias del modelo de su índice correspondiente:

$orders->unsearchable();

#Pausar Indexación

A veces puede necesitar realizar un lote de operaciones Eloquent en un modelo sin sincronizar los datos del modelo con su índice de búsqueda. Puede hacer esto usando el método withoutSyncingToSearch. Este método acepta un único closure que se ejecutará inmediatamente. Cualquier operación de modelo que ocurra dentro del closure no se sincronizará con el índice del modelo:

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Realizar acciones sobre el modelo...
});

#Instancias de Modelo Condicionalmente Buscables

A veces puede necesitar hacer que un modelo sea buscable solo bajo ciertas condiciones. Por ejemplo, imagine que tiene un modelo App\Models\Post que puede estar en uno de dos estados: "borrador" y "publicado". Puede querer permitir que solo los posts "publicados" sean buscables. Para lograr esto, puede definir un método shouldBeSearchable en su modelo:

/**
 * Determinar si el modelo debe ser buscable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

El método shouldBeSearchable solo se aplica cuando se manipulan modelos mediante los métodos save y create, consultas o relaciones. Hacer modelos o colecciones buscables directamente usando el método searchable anulará el resultado del método shouldBeSearchable.

#Búsqueda

Puede comenzar a buscar un modelo usando el método search. Este método acepta una cadena que se usará para buscar en sus modelos. Luego debe encadenar el método get a la consulta de búsqueda para recuperar los modelos Eloquent que coincidan con la consulta dada:

use App\Models\Order;

$orders = Order::search('Star Trek')->get();

Dado que las búsquedas de Scout devuelven una colección de modelos Eloquent, incluso puede devolver los resultados directamente desde una ruta o controlador y se convertirán automáticamente a JSON:

use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

Si desea obtener los resultados de búsqueda sin procesar antes de que se conviertan en modelos Eloquent, puede usar el método raw:

$orders = Order::search('Star Trek')->raw();

#Índices Personalizados

Las consultas de búsqueda normalmente se realizarán en el índice especificado por el método searchableAs del modelo. Sin embargo, puede usar el método within para especificar un índice personalizado que se debe buscar en su lugar:

$orders = Order::search('Star Trek')
    ->within('tv_shows_popularity_desc')
    ->get();

#Cláusulas Where

Scout le permite agregar cláusulas simples "where" a sus consultas de búsqueda. Actualmente, estas cláusulas solo soportan verificaciones básicas de igualdad numérica y son principalmente útiles para limitar consultas de búsqueda por un ID de propietario:

use App\Models\Order;

$orders = Order::search('Star Trek')->where('user_id', 1)->get();

Además, el método whereIn puede usarse para verificar que el valor de una columna dada esté contenido dentro del arreglo dado:

$orders = Order::search('Star Trek')->whereIn(
    'status', ['open', 'paid']
)->get();

El método whereNotIn verifica que el valor de la columna dada no esté contenido en el arreglo dado:

$orders = Order::search('Star Trek')->whereNotIn(
    'status', ['closed']
)->get();

Dado que un índice de búsqueda no es una base de datos relacional, cláusulas "where" más avanzadas no están soportadas actualmente.

#Paginación

Además de recuperar una colección de modelos, puede paginar sus resultados de búsqueda usando el método paginate. Este método devolverá una instancia de Illuminate\Pagination\LengthAwarePaginator tal como si hubiera paginado una consulta Eloquent tradicional:

use App\Models\Order;

$orders = Order::search('Star Trek')->paginate();

Puede especificar cuántos modelos recuperar por página pasando la cantidad como primer argumento al método paginate:

$orders = Order::search('Star Trek')->paginate(15);

Una vez que haya recuperado los resultados, puede mostrar los resultados y renderizar los enlaces de página usando Blade tal como si hubiera paginado una consulta Eloquent tradicional:

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

Por supuesto, si desea obtener los resultados de paginación como JSON, puede devolver la instancia del paginador directamente desde una ruta o controlador:

use App\Models\Order;
use Illuminate\Http\Request;

Route::get('/orders', function (Request $request) {
    return Order::search($request->input('query'))->paginate(15);
});

#Eliminación Suave

Si sus modelos indexados usan eliminación suave y necesita buscar sus modelos soft deleted, configure la opción soft_delete en el archivo de configuración config/scout.php a true:

'soft_delete' => true,

Cuando esta opción de configuración es true, Scout no eliminará los modelos soft deleted del índice de búsqueda. En su lugar, establecerá un atributo oculto __soft_deleted en el registro indexado. Luego, puede usar los métodos withTrashed o onlyTrashed para recuperar los registros soft deleted al buscar:

use App\Models\Order;

// Incluir registros eliminados al recuperar resultados...
$orders = Order::search('Star Trek')->withTrashed()->get();

// Incluir solo registros eliminados al recuperar resultados...
$orders = Order::search('Star Trek')->onlyTrashed()->get();

#Personalización de Búsquedas en el Motor

Si necesita realizar una personalización avanzada del comportamiento de búsqueda de un motor, puede pasar un closure como segundo argumento al método search. Por ejemplo, podría usar este callback para agregar datos de geolocalización a sus opciones de búsqueda antes de que la consulta se pase a Algolia:

use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;

Order::search(
    'Star Trek',
    function (SearchIndex $algolia, string $query, array $options) {
        $options['body']['query']['bool']['filter']['geo_distance'] = [
            'distance' => '1000km',
            'location' => ['lat' => 36, 'lon' => 111],
        ];

        return $algolia->search($query, $options);
    }
)->get();

#Personalización de la Consulta de Resultados Eloquent

Después de que Scout recupere una lista de modelos Eloquent coincidentes del motor de búsqueda de su aplicación, Eloquent se utiliza para obtener todos los modelos coincidentes por sus claves primarias. Puede personalizar esta consulta invocando el método query. El método query acepta una función anónima que recibirá la instancia del constructor de consultas de Eloquent como argumento:

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

Dado que este callback se invoca después de que los modelos relevantes ya han sido recuperados del motor de búsqueda de su aplicación, el método query no debe usarse para "filtrar" resultados. En su lugar, debe usar las cláusulas where de Scout.

#Motores Personalizados

#Escribir el Motor

Si uno de los motores de búsqueda integrados en Scout no se ajusta a sus necesidades, puede escribir su propio motor personalizado y registrarlo con Scout. Su motor debe extender la clase abstracta Laravel\Scout\Engines\Engine. Esta clase abstracta contiene ocho métodos que su motor personalizado debe implementar:

use Laravel\Scout\Builder;

abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

Puede ser útil revisar las implementaciones de estos métodos en la clase Laravel\Scout\Engines\AlgoliaEngine. Esta clase le proporcionará un buen punto de partida para aprender cómo implementar cada uno de estos métodos en su propio motor.

#Registrar el Motor

Una vez que haya escrito su motor personalizado, puede registrarlo con Scout usando el método extend del administrador de motores de Scout. El administrador de motores de Scout puede resolverse desde el contenedor de servicios de Laravel. Debe llamar al método extend desde el método boot de su clase App\Providers\AppServiceProvider o cualquier otro proveedor de servicios usado por su aplicación:

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

/**
 * Inicializar cualquier servicio de la aplicación.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

Una vez que su motor haya sido registrado, puede especificarlo como el driver predeterminado de Scout en el archivo de configuración config/scout.php de su aplicación:

'driver' => 'mysql',