*/
public function toSearchableArray(): array
{
return array_merge($this->toArray(),[
'id' => (string) $this->id,
'created_at' => $this->created_at->timestamp,
]);
}
```
Вам також слід описати схеми колекцій Typesense у файлі `config/scout.php` вашого застосунку. Схема колекції описує типи даних кожного поля, доступного для пошуку через Typesense. Докладніше про всі доступні опції схеми читайте в [документації Typesense](https://typesense.org/docs/latest/api/collections.html#schema-parameters).
Якщо вам треба змінити схему колекції Typesense після того, як її описано, ви можете або виконати `scout:flush` і `scout:import`, що видалить усі проіндексовані дані й перестворить схему, або скористатися API Typesense, щоб змінити схему колекції, не видаляючи проіндексованих даних.
Якщо ваша придатна до пошуку модель підтримує м'яке видалення, опишіть поле `__soft_deleted` у відповідній схемі Typesense у конфігураційному файлі `config/scout.php` вашого застосунку:
```php
User::class => [
'collection-schema' => [
'fields' => [
// ...
[
'name' => '__soft_deleted',
'type' => 'int32',
'optional' => true,
],
],
],
],
```
#### Динамічні параметри пошуку
Typesense дозволяє змінювати ваші [параметри пошуку](https://typesense.org/docs/latest/api/search.html#search-parameters) динамічно під час виконання пошуку - через метод `options`:
```php
use App\Models\Todo;
Todo::search('Groceries')->options([
'query_by' => 'title, description'
])->get();
```
### Turbopuffer
Turbopuffer потребує схеми та атрибутів для пошуку для кожної моделі. Опишіть їх у масиві `model-settings` вашої конфігурації `turbopuffer` у конфігураційному файлі `scout`:
```php
use App\Models\Article;
'turbopuffer' => [
// ...
'model-settings' => [
Article::class => [
'searchable-attributes' => [
'title' => 3,
'body' => 1,
],
'schema' => [
'title' => ['type' => 'string', 'full_text_search' => true],
'body' => ['type' => 'string', 'full_text_search' => true],
'status' => ['type' => 'string'],
],
],
],
],
```
Числові значення, призначені `searchable-attributes`, - це відносні ваги BM25. У прикладі вище збіги в заголовку статті додають до оцінки втричі більше, ніж збіги в тілі.
Щоб увімкнути семантичний і гібридний пошук, додайте до конфігурації моделі параметр `embedding` і схему вектора:
```php
'turbopuffer' => [
// ...
'model-settings' => [
Article::class => [
'searchable-attributes' => [
'title' => 3,
'body' => 1,
],
'embedding' => [
'attribute' => 'embedding',
'dimensions' => 1536,
],
'schema' => [
'title' => ['type' => 'string', 'full_text_search' => true],
'body' => ['type' => 'string', 'full_text_search' => true],
'embedding' => ['type' => '[1536]f32', 'ann' => true],
],
],
],
],
```
Метод вашої моделі `toSearchableEmbedding` має повертати вихідний текст, який Scout перетворить на ембединг, або вже готовий масив ембединга. Ембединги з вихідного тексту Scout генерує за допомогою [Laravel AI SDK](/docs/{{version}}/ai-sdk).
Як альтернативу ви можете скористатися нативними ембедингами Turbopuffer, не встановлюючи Laravel AI SDK і не описуючи метод `toSearchableEmbedding`. Установіть драйвер ембедингів у значення `turbopuffer` і налаштуйте схему `embed` на вихідному атрибуті:
```php
'embedding' => [
'driver' => 'turbopuffer',
'attribute' => 'embedding_text',
],
'schema' => [
// ...
'embedding_text' => [
'type' => 'string',
'embed' => [
'model' => 'voyage/voyage-4',
'dimensions' => 1024,
'attribute' => 'embedding',
],
],
],
```
Вихідний атрибут має бути серед того, що повертає метод моделі `toSearchableArray`.
## Індексування у сторонніх рушіях
> [!NOTE]
> Описані в цьому розділі можливості індексування стосуються передусім сторонніх рушіїв (Algolia, Meilisearch, Typesense чи Turbopuffer). Рушій database шукає безпосередньо у ваших таблицях, тож не потребує ручного керування індексами.
### Пакетний імпорт
Якщо ви встановлюєте Scout у наявний проєкт, у вас, можливо, вже є записи в базі даних, які треба імпортувати до індексів. Scout надає артизан-команду `scout:import`, якою можна імпортувати всі наявні записи до ваших пошукових індексів:
```shell
php artisan scout:import "App\Models\Post"
```
Команда `scout:queue-import` дозволяє імпортувати всі ваші наявні записи через [завдання в черзі](/docs/{{version}}/queues):
```shell
php artisan scout:queue-import "App\Models\Post" --chunk=500
```
Команда `flush` дозволяє прибрати всі записи моделі з ваших пошукових індексів:
```shell
php artisan scout:flush "App\Models\Post"
```
#### Зміна запиту для імпорту
Якщо ви хочете змінити запит, яким дістаються всі ваші моделі для пакетного імпорту, визначте на моделі метод `makeAllSearchableUsing`. Це чудове місце, щоб додати будь-яке жадібне завантаження зв'язків, потрібне перед імпортом ваших моделей:
```php
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');
}
```
> [!WARNING]
> Метод `makeAllSearchableUsing` може бути незастосовним, коли пакетний імпорт моделей іде через чергу. Зв'язки [не відновлюються](/docs/{{version}}/queues#handling-relationships), коли колекції моделей обробляються завданнями.
### Додавання записів
Коли ви додали трейт `Laravel\Scout\Searchable` до моделі, вам залишається лише зберегти (`save`) чи створити (`create`) екземпляр моделі - і його буде автоматично додано до вашого пошукового індексу. Якщо ви налаштували Scout [на використання черг](#queueing), цю операцію виконає у фоні ваш воркер черги:
```php
use App\Models\Order;
$order = new Order;
// ...
$order->save();
```
#### Додавання записів через запит
Якщо ви хочете додати до пошукового індексу колекцію моделей через запит Eloquent, додайте до нього ланцюжком метод `searchable`. Метод `searchable` [розіб'є результати](/docs/{{version}}/eloquent#chunking-results) запиту на порції й додасть записи до вашого пошукового індексу. І знову ж: якщо ви налаштували Scout на використання черг, усі порції буде імпортовано у фоні вашими воркерами:
```php
use App\Models\Order;
Order::where('price', '>', 100)->searchable();
```
Ви також можете викликати метод `searchable` на екземплярі зв'язку Eloquent:
```php
$user->orders()->searchable();
```
Або ж, якщо у вас уже є колекція моделей Eloquent у пам'яті, викличте метод `searchable` на екземплярі колекції, щоб додати екземпляри моделей до відповідного індексу:
```php
$orders->searchable();
```
> [!NOTE]
> Метод `searchable` можна вважати операцією «upsert». Іншими словами, якщо запис моделі вже є у вашому індексі, його буде оновлено. Якщо його в індексі немає, його буде додано.
### Оновлення записів
Щоб оновити придатну до пошуку модель, вам треба лише змінити властивості її екземпляра й зберегти (`save`) модель до бази даних. Scout автоматично збереже зміни до вашого пошукового індексу:
```php
use App\Models\Order;
$order = Order::find(1);
// Update the order...
$order->save();
```
Ви також можете викликати метод `searchable` на екземплярі запиту Eloquent, щоб оновити колекцію моделей. Якщо моделей у вашому пошуковому індексі немає, їх буде створено:
```php
Order::where('price', '>', 100)->searchable();
```
Якщо ви хочете оновити записи пошукового індексу для всіх моделей у зв'язку, викличте `searchable` на екземплярі зв'язку:
```php
$user->orders()->searchable();
```
Або ж, якщо у вас уже є колекція моделей Eloquent у пам'яті, викличте метод `searchable` на екземплярі колекції, щоб оновити екземпляри моделей у відповідному індексі:
```php
$orders->searchable();
```
#### Зміна записів перед імпортом
Іноді вам може знадобитися підготувати колекцію моделей, перш ніж робити їх придатними до пошуку. Наприклад, ви можете захотіти жадібно завантажити зв'язок, щоб його дані ефективно потрапили до пошукового індексу. Для цього визначте у відповідній моделі метод `makeSearchableUsing`:
```php
use Illuminate\Database\Eloquent\Collection;
/**
* Modify the collection of models being made searchable.
*/
public function makeSearchableUsing(Collection $models): Collection
{
return $models->load('author');
}
```
#### Умовне оновлення пошукового індексу
За замовчуванням Scout переіндексує оновлену модель незалежно від того, які атрибути було змінено. Якщо ви хочете змінити цю поведінку, визначте на моделі метод `searchIndexShouldBeUpdated`:
```php
/**
* Determine if the search index should be updated.
*/
public function searchIndexShouldBeUpdated(): bool
{
return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
}
```
### Видалення записів
Щоб прибрати запис із вашого індексу, просто видаліть (`delete`) модель із бази даних. Це працює навіть із моделями, що використовують [м'яке видалення](/docs/{{version}}/eloquent#soft-deleting):
```php
use App\Models\Order;
$order = Order::find(1);
$order->delete();
```
Якщо ви не хочете діставати модель перед видаленням запису, скористайтеся методом `unsearchable` на екземплярі запиту Eloquent:
```php
Order::where('price', '>', 100)->unsearchable();
```
Якщо ви хочете прибрати записи пошукового індексу для всіх моделей у зв'язку, викличте `unsearchable` на екземплярі зв'язку:
```php
$user->orders()->unsearchable();
```
Або ж, якщо у вас уже є колекція моделей Eloquent у пам'яті, викличте метод `unsearchable` на екземплярі колекції, щоб прибрати екземпляри моделей із відповідного індексу:
```php
$orders->unsearchable();
```
Щоб прибрати з відповідного індексу всі записи моделі, викличте метод `removeAllFromSearch`:
```php
Order::removeAllFromSearch();
```
### Призупинення індексування
Іноді вам може знадобитися виконати пакет операцій Eloquent над моделлю, не синхронізуючи її дані з пошуковим індексом. Зробити це можна методом `withoutSyncingToSearch`. Цей метод приймає єдине замикання, яке буде виконано одразу. Жодна операція з моделлю всередині замикання не потрапить до індексу моделі:
```php
use App\Models\Order;
Order::withoutSyncingToSearch(function () {
// Perform model actions...
});
```
### Умовна індексованість екземплярів моделей
Іноді вам може знадобитися робити модель придатною до пошуку лише за певних умов. Уявіть, наприклад, що у вас є модель `App\Models\Post`, яка може бути в одному з двох станів: «draft» і «published». Ви можете захотіти, щоб до пошуку потрапляли лише «published»-дописи. Для цього визначте на моделі метод `shouldBeSearchable`:
```php
/**
* Determine if the model should be searchable.
*/
public function shouldBeSearchable(): bool
{
return $this->isPublished();
}
```
Метод `shouldBeSearchable` застосовується лише тоді, коли ви працюєте з моделями через методи `save` і `create`, запити чи зв'язки. Пряме додавання моделей чи колекцій до пошуку методом `searchable` перевизначить результат методу `shouldBeSearchable`.
> [!WARNING]
> Метод `shouldBeSearchable` незастосовний із рушієм Scout «database», адже всі дані для пошуку завжди зберігаються в базі. Щоб досягти схожої поведінки з рушієм database, скористайтеся натомість [умовами where](#where-clauses).
## Пошук
Почати пошук по моделі можна методом `search`. Метод search приймає єдиний рядок, за яким шукатимуться ваші моделі. Далі додайте до пошукового запиту ланцюжком метод `get`, щоб отримати моделі Eloquent, які відповідають заданому запиту:
```php
use App\Models\Order;
$orders = Order::search('Star Trek')->get();
```
Оскільки пошук у Scout повертає колекцію моделей Eloquent, ви можете навіть повертати результати просто з маршруту чи контролера - їх буде автоматично перетворено на JSON:
```php
use App\Models\Order;
use Illuminate\Http\Request;
Route::get('/search', function (Request $request) {
return Order::search($request->search)->get();
});
```
Якщо ви хочете отримати сирі результати пошуку до їх перетворення на моделі Eloquent, скористайтеся методом `raw`:
```php
$orders = Order::search('Star Trek')->raw();
```
### Семантичний пошук
Рушії database, Meilisearch і Turbopuffer підтримують семантичний пошук, який добирає записи за змістом запиту. Коли ембединги генерує Scout, семантичний і гібридний пошук потребують [Laravel AI SDK](/docs/{{version}}/ai-sdk). [Нативні ембединги](#turbopuffer-configuration) Turbopuffer і заздалегідь обчислені вектори запиту Laravel AI SDK не потребують.
Налаштувавши ембединги для обраного рушія, викличте на пошуковому запиті метод `semantic`:
```php
$articles = Article::search('staying cool in the summer')
->semantic()
->get();
```
Ви можете задати мінімальний поріг схожості, якщо обраний рушій це підтримує:
```php
$articles = Article::search('renewable energy storage')
->semantic(minSimilarity: 0.6)
->get();
```
Щоб поєднати повнотекстовий і семантичний пошук, скористайтеся методом `hybrid`. Два його перші аргументи керують відносними вагами текстових і семантичних результатів:
```php
$articles = Article::search('renewable energy storage')
->hybrid(textWeight: 1, semanticWeight: 2)
->get();
```
#### Власні індекси
Шукаючи через сторонні рушії, пошукові запити зазвичай виконуються в індексі, вказаному методом моделі [searchableAs](#configuring-model-indexes). Проте ви можете скористатися методом `within`, щоб указати інший індекс для пошуку:
```php
$orders = Order::search('Star Trek')
->within('tv_shows_popularity_desc')
->get();
```
### Умови where
Scout дозволяє додавати до пошукових запитів умови «where». Наприклад, базові перевірки на рівність стають у пригоді, щоб обмежити пошук за ID власника:
```php
use App\Models\Order;
$orders = Order::search('Star Trek')->where('user_id', 1)->get();
```
Ви також можете скористатися операторами порівняння `=`, `!=`, `<`, `>`, `>=`, `<=`, щоб будувати складніші запити:
```php
Order::search('Star Trek')
->where('status', '=', 'completed')
->where('is_refunded', '!=', true)
->where('total_price', '>', 100)
->where('shipping_cost', '<', 20)
->where('discount_percent', '>=', 10)
->where('item_count', '<=', 5)
->get();
```
Крім того, метод `whereIn` дозволяє перевірити, що значення заданого стовпця міститься в заданому масиві:
```php
$orders = Order::search('Star Trek')->whereIn(
'status', ['open', 'paid']
)->get();
```
Метод `whereNotIn` перевіряє, що значення заданого стовпця не міститься в заданому масиві:
```php
$orders = Order::search('Star Trek')->whereNotIn(
'status', ['closed']
)->get();
```
> [!WARNING]
> Якщо ваш застосунок використовує Meilisearch, вам треба налаштувати [атрибути для фільтрації](#meilisearch-index-settings), перш ніж користуватися умовами «where» у Scout.
#### Налаштування запиту результатів Eloquent
Коли Scout отримає від пошукового рушія вашого застосунку список відповідних моделей Eloquent, Eloquent дістає всі ці моделі за їхніми первинними ключами. Ви можете налаштувати цей запит методом `query`. Метод `query` приймає замикання, яке отримає аргументом екземпляр конструктора запитів Eloquent:
```php
use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;
$orders = Order::search('Star Trek')
->query(fn (Builder $query) => $query->with('invoices'))
->get();
```
Зі стороннім рушієм цей колбек викликається вже після того, як потрібні моделі отримано з пошукового рушія, тож його не варто використовувати для «фільтрації» результатів - скористайтеся натомість [умовами where у Scout](#where-clauses). Проте з рушієм database обмеження методу `query` застосовуються безпосередньо до запиту в базу, тож ви можете використовувати його й для фільтрації.
### Пагінація
Окрім отримання колекції моделей, ви можете розбити результати пошуку на сторінки методом `paginate`. Цей метод поверне екземпляр `Illuminate\Pagination\LengthAwarePaginator` - так само, як і при [пагінації звичайного запиту Eloquent](/docs/{{version}}/pagination):
```php
use App\Models\Order;
$orders = Order::search('Star Trek')->paginate();
```
Ви можете вказати, скільки моделей отримувати на сторінку, передавши кількість першим аргументом до методу `paginate`:
```php
$orders = Order::search('Star Trek')->paginate(15);
```
З рушієм database ви можете також скористатися методом `simplePaginate`. На відміну від `paginate`, який дістає загальну кількість відповідних записів, щоб показати номери сторінок, `simplePaginate` лише визначає, чи є результати за межами поточної сторінки, - що ефективніше для великих наборів даних, де вам потрібні лише посилання «попередня» й «наступна»:
```php
$orders = Order::search('Star Trek')->simplePaginate(15);
```
Отримавши результати, ви можете показати їх і відрендерити посилання на сторінки через [Blade](/docs/{{version}}/blade) - так само, як при пагінації звичайного запиту Eloquent:
```html
@foreach ($orders as $order)
{{ $order->price }}
@endforeach
{{ $orders->links() }}
```
Звісно, якщо ви хочете отримати результати пагінації як JSON, поверніть екземпляр пагінатора просто з маршруту чи контролера:
```php
use App\Models\Order;
use Illuminate\Http\Request;
Route::get('/orders', function (Request $request) {
return Order::search($request->input('query'))->paginate(15);
});
```
> [!WARNING]
> Оскільки пошукові рушії не знають про визначення глобальних скопів вашої моделі Eloquent, вам не слід використовувати глобальні скопи в застосунках, що покладаються на пагінацію Scout. Або ж вам треба відтворити обмеження глобального скопа під час пошуку через Scout.
### М'яке видалення
Якщо ваші проіндексовані моделі використовують [м'яке видалення](/docs/{{version}}/eloquent#soft-deleting) і вам треба шукати серед м'яко видалених моделей, встановіть опцію `soft_delete` у конфігураційному файлі `config/scout.php` у значення `true`:
```php
'soft_delete' => true,
```
Коли ця опція має значення `true`, Scout не прибиратиме м'яко видалені моделі з пошукового індексу. Натомість він встановить прихований атрибут `__soft_deleted` на проіндексованому записі. Далі ви можете скористатися методами `withTrashed` чи `onlyTrashed`, щоб діставати м'яко видалені записи під час пошуку:
```php
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();
```
> [!NOTE]
> Коли м'яко видалену модель остаточно видаляють через `forceDelete`, Scout автоматично прибирає її з пошукового індексу.
### Налаштування пошуку в рушіях
Якщо вам потрібне складне налаштування пошукової поведінки рушія, ви можете передати замикання другим аргументом до методу `search`. Наприклад, цим колбеком можна додати геодані до ваших опцій пошуку, перш ніж запит буде передано до Algolia:
```php
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();
```
## Власні рушії
#### Написання рушія
Якщо жоден із вбудованих пошукових рушіїв Scout вам не пасує, ви можете написати власний і зареєструвати його в Scout. Ваш рушій має успадковувати абстрактний клас `Laravel\Scout\Engines\Engine`. Цей абстрактний клас містить вісім методів, які має реалізувати ваш рушій:
```php
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. Викликати метод `extend` слід у методі `boot` вашого класу `App\Providers\AppServiceProvider` чи будь-якого іншого сервіс-провайдера вашого застосунку:
```php
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;
});
}
```
Коли ваш рушій зареєстровано, ви можете вказати його як стандартний `driver` Scout у конфігураційному файлі `config/scout.php` вашого застосунку:
```php
'driver' => 'mysql',
```