バージョン: 10.x

Laravel Scout (Laravel Scout)

Introduction
Installation
- Queueing
ドライバの前提条件
Configuration
データベース / コレクションエンジン
- データベースエンジン
- 収集エンジン
Indexing
Searching
カスタムエンジン

導入 (Introduction)

Laravel Scout は、Eloquent モデルに全文検索を追加するためのシンプルなドライバベースのソリューションを提供します。 Scout はモデルオブザーバを使用して、検索インデックスを Eloquent レコードと自動的に同期させます。

現在、Scout には、Algolia、Meilisearch、Typesense、および MySQL / PostgreSQL (database) ドライバが同梱されています。さらに、Scout には、ローカル開発用途向けに設計された「コレクション」ドライバが含まれており、外部の依存関係やサードパーティのサービスを必要としません。さらに、カスタムドライバの作成は簡単で、独自の検索実装を使用して Scout を自由に拡張できます。

インストール (Installation)

まず、Composer パッケージマネージャーを介して Scout をインストールします。

composer require laravel/scout

Scout をインストールした後、vendor:publish Artisan コマンドを使用して Scout 構成ファイルを公開する必要があります。このコマンドは、scout.php 構成ファイルをアプリケーションの config ディレクトリに公開します。

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

最後に、検索可能にしたいモデルに Laravel\Scout\Searchable トレイトを追加します。このトレイトは、モデルと検索ドライバの同期を自動的に維持するモデルオブザーバを登録します。

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

キューイング

Scout を使用することが厳密に必須ではありませんが、ライブラリを使用する前にキュードライバを構成することを強く検討する必要があります。キューワーカーを実行すると、Scout はモデル情報を検索インデックスに同期するすべての操作をキューに入れることができるため、アプリケーションの Web インターフェイスの応答時間が大幅に向上します。

キュードライバを構成したら、config/scout.php 構成ファイルの queue オプションの値を true に設定します。

'queue' => true,

queue オプションが false に設定されている場合でも、Algolia や Meilisearch などの一部の Scout ドライバは常に非同期でレコードのインデックスを作成することに留意することが重要です。つまり、Laravel アプリケーション内でインデックス操作が完了したとしても、検索エンジン自体には新しいレコードや更新されたレコードがすぐに反映されない可能性があります。

Scout ジョブが使用する接続とキューを指定するには、queue 構成オプションを配列として定義できます。

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

もちろん、Scout ジョブが使用する接続とキューをカスタマイズする場合は、キューワーカーを実行して、その接続とキューでジョブを処理する必要があります。

php artisan queue:work redis --queue=scout

ドライバの前提条件 (Driver Prerequisites)

アルゴリア

Algolia ドライバを使用する場合は、config/scout.php 構成ファイルで Algolia id および secret 資格情報を構成する必要があります。認証情報を設定したら、Composer パッケージマネージャーを介して Algolia PHP SDK をインストールする必要もあります。

composer require algolia/algoliasearch-client-php

メイリサーチ

Meilisearch は、非常に高速なオープンソースの検索エンジンです。 Meilisearch をローカルマシンにインストールする方法がわからない場合は、Laravel が公式にサポートする Docker 開発環境である Laravel Sail を使用できます。

Meilisearch ドライバを使用する場合は、Composer パッケージマネージャーを介して Meilisearch PHP SDK をインストールする必要があります。

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

次に、アプリケーションの .env ファイル内で、SCOUT_DRIVER 環境変数と Meilisearch host および key 資格情報を設定します。

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

Meilisearch の詳細については、Meilisearch ドキュメントを参照してください。

さらに、バイナリ互換性に関する Meilisearch のドキュメントを確認して、Meilisearch バイナリバージョンと互換性のある meilisearch/meilisearch-php のバージョンをインストールしていることを確認する必要があります。

Meilisearch を利用するアプリケーションで Scout をアップグレードする場合は、常に Meilisearch サービス自体に追加の重大な変更を確認するを実行する必要があります。

Typesense

Typesense は超高速のオープンソース検索エンジンで、キーワード検索、セマンティック検索、地理検索、ベクトル検索をサポートしています。

self-host Typesense または Typesense Cloud を使用できます。

Scout で Typesense の使用を開始するには、Composer パッケージマネージャーを介して Typesense PHP SDK をインストールします。

composer require typesense/typesense-php

次に、アプリケーションの .env ファイル内で SCOUT_DRIVER 環境変数と Typesense ホストおよび API キーの資格情報を設定します。

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

必要に応じて、インストールのポート、パス、プロトコルを指定することもできます。

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Typesense コレクションの追加の設定とスキーマ定義は、アプリケーションの config/scout.php 構成ファイル内にあります。 Typesense の詳細については、Typesense ドキュメントを参照してください。

Typesense でのストレージ用のデータの準備

Typesense を利用する場合、検索可能なモデルは、モデルの主キーを文字列にキャストし、作成日を UNIX タイムスタンプにキャストする toSearchableArray メソッドを定義する必要があります。

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
public function toSearchableArray()
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

また、アプリケーションの config/scout.php ファイルで Typesense コレクションスキーマを定義する必要があります。コレクションスキーマは、Typesense を介して検索可能な各フィールドのデータ型を記述します。利用可能なすべてのスキーマオプションの詳細については、Typesense ドキュメントを参照してください。

Typesense コレクションのスキーマを定義した後に変更する必要がある場合は、scout:flush および scout:import を実行します。これにより、既存のインデックス付きデータがすべて削除され、スキーマが再作成されます。または、Typesense の API を使用して、インデックス付きデータを削除せずにコレクションのスキーマを変更することもできます。

検索可能なモデルが論理的に削除可能な場合は、アプリケーションの config/scout.php 構成ファイル内のモデルに対応する Typesense スキーマで __soft_deleted フィールドを定義する必要があります。

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

動的検索パラメータ

Typesense を使用すると、options メソッド経由で検索操作を実行するときに、検索パラメータを動的に変更できます。

use App\Models\Todo;

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

構成 (Configuration)

モデルインデックスの構成

各 Eloquent モデルは、そのモデルの検索可能なすべてのレコードを含む特定の検索「インデックス」と同期されます。つまり、各インデックスを MySQL テーブルのように考えることができます。デフォルトでは、各モデルは、モデルの一般的な「テーブル」名に一致するインデックスに保存されます。通常、これはモデル名の複数形です。ただし、モデルの searchableAs メソッドをオーバーライドすることで、モデルのインデックスを自由にカスタマイズできます。

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

検索可能なデータの構成

デフォルトでは、特定のモデルの toArray フォーム全体が検索インデックスに保存されます。検索インデックスに同期されるデータをカスタマイズしたい場合は、モデルの toSearchableArray メソッドをオーバーライドできます。

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the indexable data array for the model.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Customize the data array...

        return $array;
    }
}

Meilisearch などの一部の検索エンジンは、正しいタイプのデータに対してフィルター操作 (>、< など) のみを実行します。したがって、これらの検索エンジンを使用し、検索可能なデータをカスタマイズするときは、数値が正しい型にキャストされていることを確認する必要があります。

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

フィルタリング可能なデータとインデックスの設定を構成する (Meilisearch)

Scout の他のドライバとは異なり、Meilisearch では、フィルター可能な属性、並べ替え可能な属性、その他のサポートされている設定フィールドなどのインデックス検索設定を事前に定義する必要があります。

フィルター可能な属性は、Scout の where メソッドを呼び出すときにフィルター処理する予定の属性であり、並べ替え可能な属性は、Scout の orderBy メソッドを呼び出すときに並べ替える予定の属性です。インデックス設定を定義するには、アプリケーションの scout 構成ファイル内の meilisearch 構成エントリの index-settings 部分を調整します。

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'],
            // Other settings fields...
        ],
        Flight::class => [
            'filterableAttributes'=> ['id', 'destination'],
            'sortableAttributes' => ['updated_at'],
        ],
    ],
],

特定のインデックスの基礎となるモデルが論理的に削除可能で、index-settings 配列に含まれている場合、Scout はそのインデックス上の論理的に削除されたモデルのフィルター処理のサポートを自動的に組み込みます。ソフト削除可能なモデルインデックスに対して定義するフィルター可能または並べ替え可能な属性が他にない場合は、そのモデルの index-settings 配列に空のエントリを追加するだけで済みます。

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

アプリケーションのインデックス設定を構成した後、scout:sync-index-settings Artisan コマンドを呼び出す必要があります。このコマンドは、Meilisearch に現在構成されているインデックス設定を通知します。便宜上、このコマンドを展開プロセスの一部にするとよいでしょう。

php artisan scout:sync-index-settings

モデルIDの構成

デフォルトでは、Scout はモデルの主キーを、検索インデックスに保存されるモデルの一意の ID/キーとして使用します。この動作をカスタマイズする必要がある場合は、モデルの getScoutKey メソッドと getScoutKeyName メソッドをオーバーライドできます。

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * Get the value used to index the model.
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * Get the key name used to index the model.
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

モデルごとの検索エンジンの構成

検索する場合、Scout は通常、アプリケーションの scout 構成ファイルで指定されたデフォルトの検索エンジンを使用します。ただし、特定のモデルの検索エンジンは、モデルの searchableUsing メソッドをオーバーライドすることで変更できます。

<?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;

    /**
     * Get the engine used to index the model.
     */
    public function searchableUsing(): Engine
    {
        return app(EngineManager::class)->engine('meilisearch');
    }
}

ユーザーの識別

Scout では、Algolia を使用するときにユーザーを自動識別することもできます。認証されたユーザーを検索操作に関連付けると、Algolia のダッシュボード内で検索分析を表示するときに役立つ場合があります。ユーザー識別を有効にするには、アプリケーションの .env ファイルで SCOUT_IDENTIFY 環境変数を true として定義します。

SCOUT_IDENTIFY=true

この機能を有効にすると、リクエストの IP アドレスと認証されたユーザーのプライマリ識別子も Algolia に渡されるため、このデータはユーザーが行った検索リクエストに関連付けられます。

データベース / コレクションエンジン (Database / Collection Engines)

データベースエンジン

データベースエンジンは現在、MySQL と PostgreSQL をサポートしています。

アプリケーションが小規模から中規模のデータベースと対話する場合、またはワークロードが軽い場合は、Scout の「データベース」エンジンを使い始めるほうが便利であると思われる場合があります。データベースエンジンは、既存のデータベースからの結果をフィルタリングするときに「where like」句と全文インデックスを使用して、クエリに該当する検索結果を決定します。

データベースエンジンを使用するには、単に SCOUT_DRIVER 環境変数の値を database に設定するか、アプリケーションの scout 構成ファイルで database ドライバを直接指定します。

SCOUT_DRIVER=database

データベースエンジンを優先ドライバとして指定したら、検索可能なデータを構成するを実行する必要があります。その後、モデルに対して検索クエリの実行を開始できます。データベースエンジンを使用する場合、Algolia、Meilisearch、または Typesense インデックスのシードに必要なインデックス作成などの検索エンジンのインデックス作成は不要です。

データベース検索戦略のカスタマイズ

デフォルトでは、データベースエンジンは、検索可能として設定されているを持つすべてのモデル属性に対して「where like」クエリを実行します。ただし、状況によっては、パフォーマンスが低下する可能性があります。したがって、データベースエンジンの検索戦略は、指定された一部の列で全文検索クエリを使用するか、文字列全体 (%example%) 内を検索するのではなく、文字列のプレフィックス (example%) を検索するために「類似箇所」制約のみを使用するように構成できます。

この動作を定義するには、モデルの toSearchableArray メソッドに PHP 属性を割り当てることができます。追加の検索戦略動作が割り当てられていない列は、引き続きデフォルトの「where like」戦略を使用します。

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

/**
 * Get the indexable data array for the model.
 *
 * @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,
    ];
}

列でフルテキストクエリ制約を使用するように指定する前に、列に全文インデックスが割り当てられていることを確認してください。

収集エンジン

ローカル開発中は Algolia、Meilisearch、または Typesense 検索エンジンを自由に使用できますが、「コレクション」エンジンから始めるほうが便利な場合があります。収集エンジンは、「where」句と既存のデータベースからの結果に対するコレクションフィルタリングを使用して、クエリに該当する検索結果を決定します。このエンジンを使用する場合、検索可能なモデルはローカルデータベースから取得されるだけなので、検索可能なモデルに「インデックス」を付ける必要はありません。

収集エンジンを使用するには、単に SCOUT_DRIVER 環境変数の値を collection に設定するか、アプリケーションの scout 構成ファイルで collection ドライバを直接指定します。

SCOUT_DRIVER=collection

コレクションドライバを優先ドライバとして指定したら、モデルに対して検索クエリの実行を開始できます。コレクションエンジンを使用する場合、Algolia、Meilisearch、または Typesense インデックスのシードに必要なインデックス作成などの検索エンジンのインデックス作成は不要です。

データベースエンジンとの違い

一見すると、「データベース」エンジンと「コレクション」エンジンはかなり似ています。どちらもデータベースと直接対話して検索結果を取得します。ただし、収集エンジンは、一致するレコードを検索するためにフルテキストインデックスや LIKE 句を利用しません。代わりに、考えられるすべてのレコードを取得し、Laravel の Str::is ヘルパを使用して、検索文字列がモデル属性値内に存在するかどうかを判断します。

コレクションエンジンは、Laravel でサポートされるすべてのリレーショナルデータベース (SQLite および SQL Server を含む) で動作するため、最も移植性の高い検索エンジンです。ただし、Scout のデータベースエンジンよりも効率は劣ります。

インデックス作成 (Indexing)

バッチインポート

既存のプロジェクトに Scout をインストールする場合は、インデックスにインポートする必要があるデータベースレコードがすでに存在する可能性があります。 Scout は、既存のすべてのレコードを検索インデックスにインポートするために使用できる scout:import Artisan コマンドを提供します。

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

flush コマンドを使用して、モデルのすべてのレコードを検索インデックスから削除できます。

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

インポートクエリの変更

バッチインポート用にすべてのモデルを取得するために使用されるクエリを変更したい場合は、モデルに makeAllSearchableUsing メソッドを定義できます。ここは、モデルをインポートする前に必要となる可能性のある積極的な関係の読み込みを追加するのに最適な場所です。

use Illuminate\Database\Eloquent\Builder;

/**
 * Modify the query used to retrieve models when making all of the models searchable.
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

makeAllSearchableUsing メソッドは、キューを使用してモデルをバッチインポートする場合には適用できない場合があります。モデルコレクションがジョブによって処理される場合、関係は復元されていないになります。

レコードの追加

Laravel\Scout\Searchable トレイトをモデルに追加したら、モデルインスタンスに save または create を追加するだけで、検索インデックスに自動的に追加されます。 Scout をキューを使用するに構成した場合、この操作はキューワーカーによってバックグラウンドで実行されます。

use App\Models\Order;

$order = new Order;

// ...

$order->save();

クエリによるレコードの追加

Eloquent クエリを介してモデルのコレクションを検索インデックスに追加したい場合は、searchable メソッドを Eloquent クエリにチェーンできます。 searchable メソッドは、クエリの結果をチャンク化するを実行し、レコードを検索インデックスに追加します。繰り返しますが、キューを使用するように Scout を構成している場合、すべてのチャンクがキューワーカーによってバックグラウンドでインポートされます。

use App\Models\Order;

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

Eloquent リレーションシップインスタンスで searchable メソッドを呼び出すこともできます。

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

または、メモリ内に Eloquent モデルのコレクションがすでにある場合は、コレクションインスタンスで searchable メソッドを呼び出して、モデルインスタンスを対応するインデックスに追加することもできます。

$orders->searchable();

searchable メソッドは、「upsert」操作とみなすことができます。つまり、モデルレコードがすでにインデックスに存在する場合、それは更新されます。検索インデックスに存在しない場合は、インデックスに追加されます。

記録の更新

検索可能なモデルを更新するには、モデルインスタンスのプロパティとデータベースのモデルを save 更新するだけです。 Scout は、検索インデックスへの変更を自動的に永続化します。

use App\Models\Order;

$order = Order::find(1);

// Update the order...

$order->save();

Eloquent クエリインスタンスで searchable メソッドを呼び出して、モデルのコレクションを更新することもできます。モデルが検索インデックスに存在しない場合は、作成されます。

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

関係内のすべてのモデルの検索インデックスレコードを更新したい場合は、関係インスタンスで searchable を呼び出します。

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

または、メモリ内に Eloquent モデルのコレクションがすでにある場合は、コレクションインスタンスで searchable メソッドを呼び出して、対応するインデックス内のモデルインスタンスを更新することもできます。

$orders->searchable();

インポート前のレコードの変更

場合によっては、モデルのコレクションを検索可能にする前に準備する必要がある場合があります。たとえば、関係データを検索インデックスに効率的に追加できるように、関係を一括ロードすることができます。これを実現するには、対応するモデルで makeSearchableUsing メソッドを定義します。

use Illuminate\Database\Eloquent\Collection;

/**
 * Modify the collection of models being made searchable.
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

レコードの削除

インデックスからレコードを削除するには、データベースからモデルを delete するだけです。これは、ソフト削除されましたモデルを使用している場合でも実行できます。

use App\Models\Order;

$order = Order::find(1);

$order->delete();

レコードを削除する前にモデルを取得したくない場合は、Eloquent クエリインスタンスで unsearchable メソッドを使用できます。

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

関係内のすべてのモデルの検索インデックスレコードを削除したい場合は、関係インスタンスで unsearchable を呼び出します。

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

または、メモリ内に Eloquent モデルのコレクションがすでにある場合は、コレクションインスタンスで unsearchable メソッドを呼び出して、対応するインデックスからモデルインスタンスを削除することもできます。

$orders->unsearchable();

インデックス作成の一時停止

場合によっては、モデルデータを検索インデックスに同期せずに、モデルに対して Eloquent 操作のバッチを実行する必要がある場合があります。これは、withoutSyncingToSearch メソッドを使用して行うことができます。このメソッドは、ただちに実行される単一のクロージャを受け入れます。クロージャ内で発生するモデル操作はモデルのインデックスに同期されません。

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Perform model actions...
});

条件付きで検索可能なモデルインスタンス

場合によっては、特定の条件下でのみモデルを検索可能にすることが必要な場合があります。たとえば、「ドラフト」と「公開」の 2 つの状態のいずれかにある App\Models\Post モデルがあるとします。「公開された」投稿のみを検索可能にしたい場合があります。これを実現するには、モデルに shouldBeSearchable メソッドを定義します。

/**
 * Determine if the model should be searchable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable メソッドは、save および create メソッド、クエリ、または関係を通じてモデルを操作する場合にのみ適用されます。 searchable メソッドを使用してモデルまたはコレクションを直接検索可能にすると、shouldBeSearchable メソッドの結果がオーバーライドされます。

検索可能なすべてのデータは常にデータベースに保存されるため、Scout の「データベース」エンジンを使用する場合、shouldBeSearchable メソッドは適用できません。データベースエンジンを使用するときに同様の動作を実現するには、代わりに where 句を使用する必要があります。

検索中 (Searching)

search メソッドを使用してモデルの検索を開始できます。検索メソッドは、モデルの検索に使用される単一の文字列を受け入れます。次に、get メソッドを検索クエリに連鎖させて、指定された検索クエリに一致する Eloquent モデルを取得する必要があります。

use App\Models\Order;

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

Scout 検索では Eloquent モデルのコレクションが返されるため、ルートまたはコントローラから直接結果を返すこともでき、結果は自動的に JSON に変換されます。

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

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

Eloquent モデルに変換される前に生の検索結果を取得したい場合は、raw メソッドを使用できます。

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

カスタムインデックス

検索クエリは通常、モデルの searchableAs メソッドで指定されたインデックスに対して実行されます。ただし、代わりに within メソッドを使用して、検索するカスタムインデックスを指定することもできます。

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

Where句

Scout を使用すると、検索クエリに単純な「where」句を追加できます。現在、これらの句は基本的な数値の等価性チェックのみをサポートしており、主に所有者 ID による検索クエリの範囲を指定する場合に役立ちます。

use App\Models\Order;

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

さらに、whereIn メソッドを使用して、指定された列の値が指定された配列内に含まれていることを確認できます。

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

whereNotIn メソッドは、指定された列の値が指定された配列に含まれていないことを検証します。

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

検索インデックスはリレーショナルデータベースではないため、より高度な "where" 句は現在サポートされていません。

アプリケーションが Meilisearch を使用している場合は、Scout の「where」句を使用する前に、アプリケーションのフィルタリング可能な属性を構成する必要があります。

ページネーション

モデルのコレクションを取得するだけでなく、paginate メソッドを使用して検索結果をページ分割することもできます。このメソッドは、従来の Eloquent クエリのページ分割がある場合と同様に、Illuminate\Pagination\LengthAwarePaginator インスタンスを返します。

use App\Models\Order;

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

paginate メソッドの最初の引数として量を渡すことで、ページごとに取得するモデルの数を指定できます。

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

結果を取得したら、従来の Eloquent クエリをページ分割した場合と同じように、Blade を使用して結果を表示し、ページリンクをレンダリングできます。

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

{{ $orders->links() }}

もちろん、ページネーションの結果を JSON として取得したい場合は、ルートまたはコントローラから直接ページネータインスタンスを返すこともできます。

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

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

検索エンジンは Eloquent モデルのグローバルスコープ定義を認識しないため、Scout ページネーションを利用するアプリケーションではグローバルスコープを利用しないでください。または、Scout 経由で検索するときに、グローバルスコープの制約を再作成する必要があります。

ソフト削除

インデックス付きモデルがソフト削除で、論理的に削除されたモデルを検索する必要がある場合は、config/scout.php 構成ファイルの soft_delete オプションを true に設定します。

'soft_delete' => true,

この構成オプションが true の場合、Scout は検索インデックスから論理的に削除されたモデルを削除しません。代わりに、インデックス付きレコードに非表示の __soft_deleted 属性を設定します。次に、検索時に withTrashed メソッドまたは onlyTrashed メソッドを使用して、論理的に削除されたレコードを取得できます。

use App\Models\Order;

// Include trashed records when retrieving results...
$orders = Order::search('Star Trek')->withTrashed()->get();

// Only include trashed records when retrieving results...
$orders = Order::search('Star Trek')->onlyTrashed()->get();

論理的に削除されたモデルが forceDelete を使用して完全に削除されると、Scout はそのモデルを検索インデックスから自動的に削除します。

エンジン検索のカスタマイズ

エンジンの検索動作の高度なカスタマイズを実行する必要がある場合は、search メソッドの 2 番目の引数としてクロージャーを渡すことができます。たとえば、このコールバックを使用して、検索クエリが 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();

Eloquent 結果クエリのカスタマイズ

Scout がアプリケーションの検索エンジンから一致する Eloquent モデルのリストを取得した後、Eloquent を使用して主キーによって一致するすべてのモデルを取得します。 query メソッドを呼び出して、このクエリをカスタマイズできます。 query メソッドは、Eloquent クエリビルダインスタンスを引数として受け取るクロージャを受け入れます。

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

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

このコールバックは、関連するモデルがアプリケーションの検索エンジンからすでに取得された後に呼び出されるため、結果の「フィルタリング」には query メソッドを使用しないでください。代わりに、where 句を調べるを使用する必要があります。

カスタムエンジン (Custom Engines)

エンジンを書く

組み込みの Scout 検索エンジンの 1 つがニーズに合わない場合は、独自のカスタムエンジンを作成して Scout に登録できます。エンジンは Laravel\Scout\Engines\Engine 抽象クラスを拡張する必要があります。この抽象クラスには、カスタムエンジンが実装する必要がある 8 つのメソッドが含まれています。

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);

Laravel\Scout\Engines\AlgoliaEngine クラスでのこれらのメソッドの実装を確認すると役立つ場合があります。このクラスは、これらの各メソッドを独自のエンジンに実装する方法を学習するための良い出発点となります。

エンジンの登録

カスタムエンジンを作成したら、Scout エンジンマネージャーの extend メソッドを使用して、Scout に登録できます。 Scout のエンジンマネージャーは、Laravel サービスコンテナーから解決される場合があります。 App\Providers\AppServiceProvider クラスの boot メソッド、またはアプリケーションで使用される他のサービスプロバイダから extend メソッドを呼び出す必要があります。

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

エンジンが登録されたら、アプリケーションの config/scout.php 構成ファイルでデフォルトの Scout driver として指定できます。

'driver' => 'mysql',

導入 (Introduction)​

インストール (Installation)​

キューイング​

ドライバの前提条件 (Driver Prerequisites)​

アルゴリア​

メイリサーチ​

Typesense​

Typesense でのストレージ用のデータの準備​

動的検索パラメータ​

構成 (Configuration)​

モデルインデックスの構成​

検索可能なデータの構成​

フィルタリング可能なデータとインデックスの設定を構成する (Meilisearch)​

モデルIDの構成​

モデルごとの検索エンジンの構成​

ユーザーの識別​

データベース / コレクション エンジン (Database / Collection Engines)​

データベースエンジン​

データベース検索戦略のカスタマイズ​

収集エンジン​

データベースエンジンとの違い​

インデックス作成 (Indexing)​

バッチインポート​

インポートクエリの変更​

レコードの追加​

クエリによるレコードの追加​

記録の更新​

インポート前のレコードの変更​

レコードの削除​

インデックス作成の一時停止​

条件付きで検索可能なモデル インスタンス​

検索中 (Searching)​

カスタムインデックス​

Where句​

ページネーション​

ソフト削除​

エンジン検索のカスタマイズ​

Eloquent 結果クエリのカスタマイズ​

カスタムエンジン (Custom Engines)​

エンジンを書く​

エンジンの登録​

導入 (Introduction)

インストール (Installation)

キューイング

ドライバの前提条件 (Driver Prerequisites)

アルゴリア

メイリサーチ

Typesense

Typesense でのストレージ用のデータの準備

動的検索パラメータ

構成 (Configuration)

モデルインデックスの構成

検索可能なデータの構成

フィルタリング可能なデータとインデックスの設定を構成する (Meilisearch)

モデルIDの構成

モデルごとの検索エンジンの構成

ユーザーの識別

データベース / コレクションエンジン (Database / Collection Engines)

データベースエンジン

データベース検索戦略のカスタマイズ

収集エンジン

データベースエンジンとの違い

インデックス作成 (Indexing)

バッチインポート

インポートクエリの変更

レコードの追加

クエリによるレコードの追加

記録の更新

インポート前のレコードの変更

レコードの削除

インデックス作成の一時停止

条件付きで検索可能なモデルインスタンス

検索中 (Searching)

カスタムインデックス

Where句

ページネーション

ソフト削除

エンジン検索のカスタマイズ

Eloquent 結果クエリのカスタマイズ

カスタムエンジン (Custom Engines)

エンジンを書く

エンジンの登録