パッケージ - Scout - 《Laravel 11.x ドキュメント》日本語

はじめに
インストール
- キュー処理
ドライバの前提条件
設定
データベース / コレクションエンジン
- データベースエンジン
  - データベース検索戦略のカスタマイズ
- コレクションエンジン
  - データベースエンジンとの違い
インデックス作成
検索
- カスタムインデックス
where 句
ページネーション
ソフトデリート
エンジン検索のカスタマイズ
- Eloquent 結果クエリのカスタマイズ
カスタムエンジン
- エンジンの作成
- エンジンの登録

はじめに

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

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

インストール

まず、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 インターフェースの応答時間が大幅に改善されます。

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

'queue' => true,

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

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

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

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

php artisan queue:work redis --queue=scout

ドライバの前提条件

Algolia

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

composer require algolia/algoliasearch-client-php

Meilisearch

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

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

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

次に、SCOUT_DRIVER 環境変数とアプリケーションの .env ファイル内に 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 は、超高速のオープンソース検索エンジンで、キーワード検索、セマンティック検索、地理検索、ベクトル検索をサポートしています。

Typesense をセルフホストするか、Typesense Cloud を使用できます。

Scout と一緒に Typesense を使用するには、Composer パッケージマネージャーを介して Typesense PHP SDK をインストールします:

composer require typesense/typesense-php

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

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

Laravel Sail を使用している場合は、Docker コンテナ名に合わせて TYPESENSE_HOST 環境変数を調整する必要があるかもしれません。また、インストールのポート、パス、プロトコルを指定することもできます:

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

設定

モデルインデックスの設定

各 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 に渡され、このデータはユーザーによって行われた検索リクエストに関連付けられます。

データベース / コレクションエンジン

データベースエンジン

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

アプリケーションが小規模から中規模のデータベースと対話する場合や軽い負荷がある場合、Scout の「データベース」エンジンを使用する方が便利かもしれません。データベースエンジンは、既存のデータベースからの結果をフィルタリングする際に「where like」句とフルテキストインデックスを使用して、クエリに適用可能な検索結果を決定します。

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

SCOUT_DRIVER=database

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

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

デフォルトでは、データベースエンジンは、検索可能として構成されたすべてのモデル属性に対して「where like」クエリを実行します。ただし、状況によっては、これがパフォーマンスの低下を引き起こす可能性があります。したがって、データベースエンジンの検索戦略を構成して、指定された列の一部がフルテキスト検索クエリを利用するか、文字列の接頭辞を検索するために「where like」制約のみを使用するように設定できます (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 によってサポートされているすべてのリレーショナルデータベースで動作するため、最もポータブルな検索エンジンですが、Scout のデータベースエンジンよりも効率が劣ります。

インデックス作成

バッチインポート

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

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

flush コマンドは、モデルのすべてのレコードを検索インデックスから削除するために使用できます:

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

インポートクエリの変更

バッチインポートのためにすべてのモデルを取得するために使用されるクエリを変更したい場合は、モデルに makeAllSearchableUsing メソッドを定義できます。これは、モデルをインポートする前に必要なイager リレーションシップの読み込みを追加するのに最適な場所です:

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 クエリを介してモデルのコレクションを検索インデックスに追加したい場合は、Eloquent クエリに searchable メソッドをチェーンできます。searchable メソッドは、クエリの結果をチャンクし、レコードを検索インデックスに追加します。再度、Scout をキューを使用するように設定した場合、すべてのチャンクはキューワーカーによってバックグラウンドでインポートされます:

use App\Models\Order;
Order::where('price', '>', 100)->searchable();

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

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

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

$orders->searchable();

searchable メソッドは「アップサート」操作と見なすことができます。言い換えれば、モデルレコードがすでにインデックスに存在する場合は更新され、検索インデックスに存在しない場合はインデックスに追加されます。

レコードの更新

検索可能なモデルを更新するには、モデルインスタンスのプロパティを更新し、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();

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

時には、検索可能にする前にモデルのコレクションを準備する必要があります。たとえば、リレーションシップをイager ロードして、リレーションシップデータを効率的に検索インデックスに追加したい場合があります。これを実現するには、対応するモデルに 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();

すべてのモデルレコードを対応するインデックスから削除するには、removeAllFromSearch メソッドを呼び出します:

Order::removeAllFromSearch();

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

時には、モデルに対して一連の Eloquent 操作を実行し、モデルデータを検索インデックスに同期させない必要があります。これを行うには、withoutSyncingToSearch メソッドを使用します。このメソッドは、単一のクロージャを受け入れ、即座に実行されます。クロージャ内で発生するモデル操作は、モデルのインデックスに同期されません:

use App\Models\Order;
Order::withoutSyncingToSearch(function () {
   // Perform model actions...
});

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

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

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

shouldBeSearchable メソッドは、save および create メソッド、クエリ、またはリレーションシップを介してモデルを操作する際にのみ適用されます。searchable メソッドを使用してモデルやコレクションを直接検索可能にすると、shouldBeSearchable メソッドの結果が上書きされます。

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

検索

モデルを検索するには、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);

結果を取得したら、結果を表示し、ページリンクを Blade を使用してレンダリングできます。従来の Eloquent クエリをページネートしたかのように:

<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 を介して検索する際にグローバルスコープの制約を再作成する必要があります。

ソフトデリート

インデックスされたモデルがソフトデリートされていて、ソフトデリートモデルを検索する必要がある場合は、soft_delete 設定ファイルの config/scout.php オプションを 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 メソッドは「フィルタリング」結果に使用すべきではありません。代わりに、Scout の where 句を使用する必要があります。

カスタムエンジン

エンジンの作成

組み込みの Scout 検索エンジンのいずれかがニーズに合わない場合は、独自のカスタムエンジンを作成し、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',