본문 바로가기

Laravel Scout

업데이트됨

번역일: 2026년 11월 14일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정
2026년 11월 16일
번역 갱신
2026년 11월 14일

Laravel Scout

소개

Laravel Scout는 Eloquent 모델에 전문(full-text) 검색 기능을 간단하게 추가할 수 있도록 해 주는 드라이버 기반 솔루션입니다. Scout는 모델 옵저버를 사용해 검색 인덱스를 Eloquent 레코드와 자동으로 동기화합니다.

Scout에는 MySQL / PostgreSQL의 전문 인덱스와 LIKE 절을 이용해 기존 데이터베이스를 그대로 검색하는 database 엔진이 기본으로 포함되어 있어, 별도의 외부 서비스 없이도 사용할 수 있습니다. 대부분의 애플리케이션에서는 이것만으로 충분합니다. Laravel에서 사용할 수 있는 검색 방식 전반에 대한 개요는 검색 문서를 참고하세요.

오타 보정, 패싯(faceted) 필터링, 벡터 검색, 대규모 지리 정보(geo) 검색 같은 기능이 필요하다면 Algolia, Meilisearch, Typesense, Turbopuffer 드라이버도 사용할 수 있습니다. 로컬 개발용 "collection" 드라이버도 제공되며, 필요하다면 커스텀 엔진을 직접 작성할 수도 있습니다.

설치

먼저 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; }

큐 사용

database 또는 collection 엔진이 아닌 다른 엔진을 사용한다면, 라이브러리를 사용하기 전에 큐 드라이버를 설정하는 것을 강력히 권장합니다. 큐 워커를 실행하면 모델 정보를 검색 인덱스에 동기화하는 모든 작업을 Scout가 큐에 넣어 처리하므로, 웹 인터페이스의 응답 속도가 크게 좋아집니다.

큐 드라이버를 설정했다면 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

고유 작업(Unique Jobs)

쓰기 작업이 많은 애플리케이션에서는 같은 모델 레코드에 대한 중복 작업이 큐에 쌓이지 않도록 하고 싶을 수 있습니다. 서비스 프로바이더의 boot 메서드 등에서 MakeSearchableUniquely와 RemoveFromSearchUniquely 작업 클래스를 등록하면 고유 인덱싱 작업을 사용할 수 있습니다.

use Laravel\Scout\Jobs\MakeSearchableUniquely; use Laravel\Scout\Jobs\RemoveFromSearchUniquely; use Laravel\Scout\Scout; Scout::makeSearchableUsing(MakeSearchableUniquely::class); Scout::removeFromSearchUsing(RemoveFromSearchUniquely::class);

이 작업들은 Laravel의 고유 작업 락을 사용하므로, 동일한 검색 대상 모델 레코드에 대한 작업이 이미 큐에 있는 동안에는 같은 인덱싱 작업이 중복으로 디스패치되지 않습니다.

드라이버 사전 준비

Algolia

Algolia 드라이버를 사용할 때는 config/scout.php 설정 파일에 Algolia의 id와 secret 자격 증명을 설정해야 합니다. 자격 증명을 설정한 뒤에는 Composer 패키지 관리자로 Algolia PHP SDK도 설치해야 합니다.

composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch는 전문 검색, 시맨틱 검색, 하이브리드 검색을 지원하는 빠른 오픈 소스 검색 엔진입니다. 로컬 환경에 Meilisearch를 어떻게 설치해야 할지 모르겠다면, Laravel이 공식 지원하는 Docker 개발 환경인 Laravel Sail을 사용할 수 있습니다. 운영 환경에서는 Meilisearch를 직접 호스팅하거나 Meilisearch Cloud를 사용할 수 있습니다.

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 문서를 참고하세요.

Typesense

Typesense는 매우 빠른 오픈 소스 검색 엔진으로, 키워드 검색, 시맨틱 검색, 지리 정보(geo) 검색, 벡터 검색을 지원합니다.

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

Laravel Sail을 사용 중이라면 TYPESENSE_HOST 환경 변수를 Docker 컨테이너 이름에 맞게 조정해야 할 수 있습니다. 설치한 Typesense의 포트, 경로, 프로토콜도 선택적으로 지정할 수 있습니다.

TYPESENSE_PORT=8108 TYPESENSE_PATH= TYPESENSE_PROTOCOL=http

Typesense 컬렉션에 대한 추가 설정과 스키마 정의는 애플리케이션의 config/scout.php 설정 파일에서 확인할 수 있습니다. Typesense에 대한 자세한 내용은 Typesense 문서를 참고하세요.

Turbopuffer

Turbopuffer는 전문 검색, 시맨틱 검색, 하이브리드 검색을 지원하는 검색 엔진입니다. Turbopuffer 드라이버를 사용하려면 SCOUT_DRIVER 환경 변수를 설정하고 Turbopuffer API 키를 지정합니다.

SCOUT_DRIVER=turbopuffer TURBOPUFFER_API_KEY=tpuf_... TURBOPUFFER_REGION=gcp-us-central1

TURBOPUFFER_REGION 환경 변수는 선택 사항이며, 기본값은 gcp-us-central1입니다.

설정

검색 대상 데이터 설정

기본적으로 모델의 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(); // 데이터 배열을 원하는 대로 수정합니다... return $array; } }

모델별 엔진 설정

검색할 때 Scout는 일반적으로 애플리케이션의 scout 설정 파일에 지정된 기본 검색 엔진을 사용합니다. 하지만 모델에서 searchableUsing 메서드를 오버라이드하면 특정 모델에서 사용할 검색 엔진을 따로 지정할 수 있습니다.

<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; use Laravel\Scout\Engines\Engine; use Laravel\Scout\Scout; use Laravel\Scout\Searchable; class User extends Model { use Searchable; /** * Get the engine used to index the model. */ public function searchableUsing(): Engine { return Scout::engine('meilisearch'); } }

데이터베이스 / 컬렉션 엔진

데이터베이스 엔진

WARNING

데이터베이스 엔진은 현재 MySQL과 PostgreSQL을 지원하며, 두 데이터베이스 모두 빠른 전문(full-text) 컬럼 인덱싱을 제공합니다.

database 엔진은 MySQL / PostgreSQL의 전문 인덱스와 LIKE 절을 사용해 기존 데이터베이스를 직접 검색합니다. 많은 애플리케이션에서 이 방식이 검색 기능을 추가하는 가장 간단하고 현실적인 방법입니다. 외부 서비스나 추가 인프라가 필요하지 않기 때문입니다.

데이터베이스 엔진을 사용하려면 SCOUT_DRIVER 환경 변수를 database로 설정합니다.

SCOUT_DRIVER=database

설정을 마쳤다면 검색 대상 데이터를 정의하고 모델에 대해 검색 쿼리를 실행할 수 있습니다. 서드파티 엔진과 달리 데이터베이스 엔진은 별도의 인덱싱 단계가 필요 없으며, 데이터베이스 테이블을 직접 검색합니다.

데이터베이스 엔진은 PostgreSQL에서 pgvector 확장을 사용할 때 시맨틱 검색과 하이브리드 검색을 지원합니다. 시작하려면 모델 테이블에 null 허용(nullable) 벡터 컬럼과 전문 인덱스를 추가합니다. Scout는 모델이 저장된 이후에 임베딩을 저장하므로 벡터 컬럼은 반드시 nullable이어야 합니다.

Schema::ensureVectorExtensionExists(); Schema::table('articles', function (Blueprint $table) { // ... $table->vector('embedding', dimensions: 1536)->nullable(); $table->vectorIndex('embedding'); $table->fullText(['title', 'body']); });

다음으로 모델에 toSearchableEmbedding 메서드를 정의합니다. 이 메서드는 Scout가 임베딩할 원본 텍스트를 반환하거나, 미리 계산해 둔 임베딩 배열을 반환할 수 있습니다. Scout는 기본적으로 embedding 컬럼에 임베딩을 저장하며, 다른 컬럼을 사용하려면 모델에 searchableEmbeddingColumn 메서드를 정의하면 됩니다.

데이터베이스 검색 전략 커스터마이징

기본적으로 데이터베이스 엔진은 검색 가능하도록 설정한 모든 모델 속성에 대해 LIKE 쿼리를 실행합니다. 하지만 특정 컬럼에는 더 효율적인 검색 전략을 지정할 수 있습니다. SearchUsingFullText 속성(attribute)은 해당 컬럼에 대해 데이터베이스의 전문 인덱스를 사용하고, SearchUsingPrefix는 문자열 전체에서 검색(%example%)하는 대신 문자열의 시작 부분만 일치시킵니다(example%).

이 동작을 정의하려면 모델의 toSearchableArray 메서드에 PHP 어트리뷰트를 지정합니다. 어트리뷰트가 없는 컬럼은 계속해서 기본 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, ]; }

WARNING

컬럼에 전문 쿼리 조건을 사용하도록 지정하기 전에, 해당 컬럼에 전문 인덱스가 설정되어 있는지 확인하세요.

PostgreSQL을 사용하면 Scout는 저장된 tsvector 컬럼을 검색하여 인덱스를 활용한 가중치 기반 전문 검색을 수행할 수 있습니다. 시작하려면 마이그레이션에서 searchable 메서드를 사용해 생성 컬럼(generated column)인 search_vector와 해당 GIN 인덱스를 추가합니다.

use Illuminate\Database\Schema\Blueprint; use Illuminate\Support\Facades\Schema; Schema::table('posts', function (Blueprint $table) { $table->searchable(['title' => 'A', 'body' => 'D']); });

컬럼 가중치는 A(가장 높음)부터 D(가장 낮음)까지입니다. 가중치 없이 ['title', 'body']처럼 컬럼 이름 목록만 전달하면 각 컬럼에 기본 가중치인 D가 적용됩니다. 원본 컬럼이 변경되면 PostgreSQL이 생성 컬럼을 자동으로 갱신합니다.

다음으로 모델의 toSearchableArray 메서드에 SearchUsingFullText 어트리뷰트를 적용하고 vector 옵션을 true로 설정합니다.

use Laravel\Scout\Attributes\SearchUsingFullText; /** * Get the indexable data array for the model. * * @return array<string, mixed> */ #[SearchUsingFullText(['search_vector'], ['vector' => true])] public function toSearchableArray(): array { return ['search_vector' => null]; }

필요한 것은 컬럼 이름뿐이며, Scout는 저장된 값을 그대로 검색합니다. 다른 속성에 대한 LIKE 절이 추가되면 PostgreSQL이 GIN 인덱스를 사용하지 못할 수 있으므로, 벡터 컬럼만 반환하세요.

searchable 메서드는 텍스트 검색 설정, 트라이그램(trigram) 인덱스용 컬럼, 사용자 지정 벡터 컬럼 이름도 받을 수 있습니다.

$table->searchable( columns: ['title' => 'A', 'body' => 'D'], language: 'english', trigram: ['title'], tsvector: 'search_vector', );

마이그레이션을 롤백할 때 생성 컬럼과 관련 인덱스를 제거하려면 dropSearchable 메서드를 사용하고, 동일한 트라이그램 컬럼과 벡터 컬럼 이름을 전달합니다.

Schema::table('posts', function (Blueprint $table) { $table->dropSearchable(trigram: ['title'], tsvector: 'search_vector'); });

PostgreSQL 검색 옵션

SearchUsingFullText 어트리뷰트의 두 번째 인수를 사용해 PostgreSQL 전문 검색을 커스터마이징할 수 있습니다.

옵션설명기본값
vector전문 검색 컬럼이 저장된 tsvector 컬럼인지 여부입니다.false
languageenglish나 public.english_unaccent 같은 텍스트 검색 설정입니다.english
mode쿼리 구문입니다: plain, phrase, websearch, rawplain
rank순위 함수입니다: ts_rank 또는 ts_rank_cdts_rank
trigram오타를 허용하는 매칭에 사용할 컬럼 이름 또는 컬럼 배열입니다.없음
trigram_mode트라이그램 매칭을 fallback으로 사용할지, blend로 전문 검색 결과와 혼합할지 지정합니다.fallback

plain 모드는 쿼리의 모든 검색어를 찾고, phrase 모드는 검색어가 순서대로 나타나는 경우를 찾습니다. websearch 모드는 따옴표로 묶은 구문이나 제외할 검색어 같은 웹 검색 구문을 지원하며, raw 모드는 PostgreSQL tsquery 구문을 그대로 받습니다. 저장된 벡터 컬럼을 검색할 때는 language가 해당 컬럼을 생성할 때 사용한 텍스트 검색 설정과 일치해야 합니다.

오타 허용 기능을 사용하려면 마이그레이션과 어트리뷰트 옵션 양쪽에 트라이그램 컬럼을 지정합니다.

#[SearchUsingFullText(['search_vector'], ['vector' => true, 'trigram' => ['title']])] public function toSearchableArray(): array { return ['search_vector' => null]; }

기본적으로 Scout는 최초 검색 결과가 없을 때에만 트라이그램 매칭으로 검색을 다시 시도합니다. trigram_mode를 blend로 설정하면 트라이그램 매칭 결과를 전문 검색 결과와 함께 포함하고, 트라이그램 유사도를 관련도 순위에도 반영합니다.

WARNING

트라이그램 매칭을 사용하려면 pg_trgm 확장이 커넥션의 검색 경로(search path)에서 사용 가능해야 합니다. 트라이그램 컬럼을 지정하면 searchable 마이그레이션 메서드가 이 확장을 생성하므로, 마이그레이션을 실행하는 데이터베이스 사용자에게 확장을 생성할 권한이 있어야 합니다.

options 메서드를 사용하면 개별 검색에 대해 mode, language, rank, trigram, trigram_mode 옵션을 덮어쓸 수 있습니다.

$posts = Post::search('"laravel scout"')->options(['mode' => 'websearch'])->get();

컬렉션 엔진

"collection" 엔진은 빠른 프로토타입, 매우 작은 데이터셋(수백 건 정도), 또는 테스트 실행을 위한 엔진입니다. 데이터베이스에서 가능한 모든 레코드를 가져온 뒤 Laravel의 Str::is 헬퍼로 PHP에서 필터링하므로, 인덱싱이나 데이터베이스별 기능이 필요하지 않습니다. 단순한 용도를 넘어선다면 데이터베이스 엔진을 사용하는 것이 좋습니다.

컬렉션 엔진을 사용하려면 SCOUT_DRIVER 환경 변수 값을 collection으로 설정하거나, 애플리케이션의 scout 설정 파일에서 collection 드라이버를 직접 지정하면 됩니다.

SCOUT_DRIVER=collection

collection 드라이버를 기본 드라이버로 지정했다면 모델에 대해 검색 쿼리를 실행할 수 있습니다. 컬렉션 엔진을 사용할 때는 Algolia, Meilisearch, Typesense 인덱스를 채우는 데 필요한 것과 같은 검색 엔진 인덱싱이 필요하지 않습니다.

데이터베이스 엔진과의 차이점

데이터베이스 엔진은 전문 인덱스와 LIKE 절을 사용해 일치하는 레코드를 효율적으로 찾지만, 컬렉션 엔진은 모든 레코드를 가져와 PHP에서 필터링합니다. 컬렉션 엔진은 SQLite와 SQL Server를 포함해 Laravel이 지원하는 모든 관계형 데이터베이스에서 동작하므로 이식성이 가장 높은 옵션입니다. 다만 데이터베이스 엔진보다 효율이 크게 떨어지므로 대용량 데이터셋에는 사용하지 않아야 합니다.

서드파티 엔진 설정

아래 설정 옵션은 Algolia, Meilisearch, Typesense 같은 서드파티 검색 엔진을 사용할 때만 해당됩니다. 데이터베이스 엔진을 사용 중이라면 이 섹션은 건너뛰어도 됩니다.

모델 인덱스 설정

서드파티 엔진을 사용하면 각 Eloquent 모델은 해당 모델의 검색 대상 레코드를 모두 담고 있는 검색 "인덱스"와 동기화됩니다. 기본적으로 각 모델은 모델의 일반적인 "테이블" 이름과 일치하는 인덱스에 저장됩니다. 보통 모델 이름의 복수형이지만, 모델에서 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'; } }

NOTE

데이터베이스 엔진은 항상 모델의 데이터베이스 테이블을 직접 검색하므로, searchableAs 메서드는 데이터베이스 엔진에서는 아무런 효과가 없습니다.

모델 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'; } }

NOTE

데이터베이스 엔진은 항상 모델의 기본 키를 사용하므로, getScoutKey와 getScoutKeyName 메서드는 데이터베이스 엔진에서는 아무런 효과가 없습니다.

Algolia

인덱스 설정

Algolia 인덱스에 추가 설정을 적용하고 싶을 때가 있습니다. 이런 설정은 Algolia UI에서 관리할 수도 있지만, 애플리케이션의 config/scout.php 설정 파일에서 인덱스 설정의 원하는 상태를 직접 관리하는 편이 더 효율적인 경우가 많습니다.

이 방식을 사용하면 애플리케이션의 자동화된 배포 파이프라인으로 설정을 함께 배포할 수 있어, 수동 설정을 피하고 여러 환경 간의 일관성을 보장할 수 있습니다. 필터링 가능한 속성, 랭킹, 패싯(faceting) 등 지원되는 모든 설정을 구성할 수 있습니다.

시작하려면 애플리케이션의 config/scout.php 설정 파일에 각 인덱스별 설정을 추가합니다.

use App\Models\User; use App\Models\Flight; 'algolia' => [ 'id' => env('ALGOLIA_APP_ID', ''), 'secret' => env('ALGOLIA_SECRET', ''), 'index-settings' => [ User::class => [ 'searchableAttributes' => ['id', 'name', 'email'], 'attributesForFaceting'=> ['filterOnly(email)'], // 그 외 설정 필드... ], Flight::class => [ 'searchableAttributes'=> ['id', 'destination'], ], ], ],

특정 인덱스의 기반이 되는 모델이 소프트 삭제를 사용하고 index-settings 배열에 포함되어 있다면, Scout는 해당 인덱스에서 소프트 삭제된 모델에 대한 패싯 지원을 자동으로 포함합니다. 소프트 삭제 모델 인덱스에 정의할 다른 패싯 속성이 없다면, 해당 모델에 대해 빈 항목을 index-settings 배열에 추가하면 됩니다.

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

애플리케이션의 인덱스 설정을 마친 후에는 scout:sync-index-settings Artisan 명령어를 실행해야 합니다. 이 명령어는 현재 설정된 인덱스 설정을 Algolia에 알려 줍니다. 편의를 위해 이 명령어를 배포 과정에 포함시켜 두는 것이 좋습니다.

php artisan scout:sync-index-settings

사용자 식별

Scout는 Algolia를 사용할 때 사용자를 자동으로 식별하는 기능을 제공합니다. 인증된 사용자를 검색 작업과 연결해 두면 Algolia 대시보드에서 검색 분석을 확인할 때 도움이 될 수 있습니다. 애플리케이션의 .env 파일에 SCOUT_IDENTIFY 환경 변수를 true로 정의하면 사용자 식별을 활성화할 수 있습니다.

SCOUT_IDENTIFY=true

이 기능을 활성화하면 요청의 IP 주소와 인증된 사용자의 기본 식별자도 Algolia에 전달되어, 해당 사용자가 수행하는 모든 검색 요청에 이 데이터가 연결됩니다.

Meilisearch

인덱스 설정

Meilisearch에서는 필터링 가능한 속성, 정렬 가능한 속성, 그 외 지원되는 설정 필드 같은 인덱스 검색 설정을 미리 정의해 두어야 합니다.

필터링 가능한 속성(filterable attributes)은 Scout의 where 메서드를 호출할 때 필터 기준으로 사용할 속성이고, 정렬 가능한 속성(sortable attributes)은 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'], // 그 외 설정 필드... ], 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

Meilisearch에서 시맨틱 검색이나 하이브리드 검색을 사용하려면, 검색 가능한 각 모델에 대해 인덱스 설정에 임베더(embedder)를 구성하고 임베딩 설정도 함께 지정합니다.

'meilisearch' => [ // ... 'index-settings' => [ Article::class => [ 'embedders' => [ 'default' => [ 'source' => 'userProvided', 'dimensions' => 1536, ], ], ], ], 'model-settings' => [ Article::class => [ 'embedding' => [ 'embedder' => 'default', 'dimensions' => 1536, ], ], ], ],

모델의 toSearchableEmbedding 메서드는 원본 텍스트를 반환할 수 있으며, 이 경우 Scout가 Laravel AI SDK를 사용해 임베딩합니다. 미리 계산해 둔 임베딩 배열을 반환할 수도 있습니다. 설정을 변경한 후에는 scout:sync-index-settings 명령어를 실행하세요.

또는 임베딩 driver를 meilisearch로 지정해 Meilisearch의 네이티브 임베딩을 사용할 수도 있습니다. 이 모드에서는 Meilisearch가 설정된 임베더로 문서와 쿼리의 임베딩을 생성하므로, dimensions 옵션과 toSearchableEmbedding 메서드가 필요하지 않습니다.

'meilisearch' => [ 'index-settings' => [ Article::class => [ 'embedders' => [ 'default' => [ 'source' => 'openAi', 'apiKey' => env('OPENAI_API_KEY'), 'model' => 'text-embedding-3-small', 'documentTemplate' => 'An article titled {{ doc.title }}: {{ doc.body }}', ], ], ], ], 'model-settings' => [ Article::class => [ 'embedding' => [ 'embedder' => 'default', 'driver' => 'meilisearch', ], ], ], ],

네이티브 임베딩을 사용하면 Scout는 인덱싱되는 문서에 벡터를 생성하거나 추가하지 않습니다. 이 경우에도 vector 검색 옵션을 사용해 미리 계산한 쿼리 벡터를 직접 제공할 수 있습니다. 다른 인덱스 설정과 마찬가지로, 임베더 설정을 변경한 후에는 scout:sync-index-settings 명령어를 실행하세요.

사용 가능한 임베더 소스와 옵션에 대한 자세한 내용은 Meilisearch 하이브리드 검색 문서를 참고하세요.

검색 대상 데이터 타입

Meilisearch는 올바른 타입의 데이터에 대해서만 필터 연산(>, < 등)을 수행합니다. 검색 대상 데이터를 커스터마이징할 때는 숫자 값이 올바른 타입으로 캐스팅되었는지 확인해야 합니다.

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

Typesense

검색 대상 데이터 준비

Typesense를 사용할 때는 검색 가능한 모델에 toSearchableArray 메서드를 정의하여 모델의 기본 키를 문자열로, 생성일을 UNIX 타임스탬프로 캐스팅해야 합니다.

/** * Get the indexable data array for the model. * * @return array<string, mixed> */ public function toSearchableArray(): array { 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 설정에 embedding 설정과 벡터 필드를 정의합니다. 기본적으로 Scout는 Laravel AI SDK를 사용해 임베딩을 생성합니다.

use App\Models\Article; 'model-settings' => [ Article::class => [ 'collection-schema' => [ 'fields' => [ ['name' => 'title', 'type' => 'string'], ['name' => 'embedding', 'type' => 'float[]', 'num_dim' => 1536], ], ], 'search-parameters' => ['query_by' => 'title'], 'embedding' => [ 'attribute' => 'embedding', 'dimensions' => 1536, ], ], ],

모델의 toSearchableEmbedding 메서드는 Scout가 임베딩할 원본 텍스트 또는 미리 계산해 둔 임베딩 배열을 반환해야 합니다.

public function toSearchableEmbedding(): string|array { return $this->title.' '.$this->body; }

동적 검색 파라미터

Typesense에서는 검색을 수행할 때 options 메서드를 통해 검색 파라미터를 동적으로 변경할 수 있습니다.

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

Turbopuffer

Turbopuffer는 모델마다 스키마와 검색 가능한 속성을 지정해야 합니다. scout 설정 파일의 turbopuffer 설정 안에 있는 model-settings 배열에 이를 정의합니다.

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의 상대적 가중치입니다. 위 예제에서는 기사 제목(title)에서 일치한 항목이 본문(body)에서 일치한 항목보다 3배 높은 점수를 얻습니다.

시맨틱 검색과 하이브리드 검색을 사용하려면 모델 설정에 embedding 설정과 벡터 스키마를 추가합니다.

'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를 사용해 원본 텍스트의 임베딩을 생성합니다.

또는 Laravel AI SDK를 설치하거나 toSearchableEmbedding 메서드를 정의하지 않고도 Turbopuffer의 네이티브 임베딩을 사용할 수 있습니다. 임베딩 드라이버를 turbopuffer로 설정하고, 검색 가능한 원본 속성에 embed 스키마를 구성합니다.

'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)을 사용할 때 해당됩니다. 데이터베이스 엔진은 데이터베이스 테이블을 직접 검색하므로 인덱스를 수동으로 관리할 필요가 없습니다.

일괄 가져오기

기존 프로젝트에 Scout를 설치하는 경우, 인덱스로 가져와야 할 데이터베이스 레코드가 이미 있을 수 있습니다. Scout는 기존 레코드를 모두 검색 인덱스로 가져올 수 있는 scout:import Artisan 명령어를 제공합니다.

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

scout:queue-import 명령어를 사용하면 큐 작업으로 기존 레코드를 모두 가져올 수 있습니다.

php artisan scout:queue-import "App\Models\Post" --chunk=500

flush 명령어는 검색 인덱스에서 모델의 모든 레코드를 제거할 때 사용합니다.

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

가져오기 쿼리 수정

일괄 가져오기를 위해 모든 모델을 조회하는 쿼리를 수정하고 싶다면 모델에 makeAllSearchableUsing 메서드를 정의하면 됩니다. 모델을 가져오기 전에 필요한 연관 관계를 즉시 로딩(eager loading)하도록 추가하기에 알맞은 위치입니다.

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 메서드를 적용할 수 없을 수 있습니다. 모델 컬렉션이 Job으로 처리될 때 연관 관계는 복원되지 않기 때문입니다.

레코드 추가

모델에 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();

NOTE

searchable 메서드는 "upsert" 연산으로 볼 수 있습니다. 즉, 모델 레코드가 이미 인덱스에 있다면 수정되고, 검색 인덱스에 없다면 인덱스에 추가됩니다.

레코드 수정

검색 가능한 모델을 수정하려면 모델 인스턴스의 속성을 변경한 뒤 모델을 데이터베이스에 save하기만 하면 됩니다. Scout가 변경 사항을 검색 인덱스에 자동으로 반영합니다.

use App\Models\Order; $order = Order::find(1); // 주문을 수정합니다... $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'); }

조건부로 검색 인덱스 갱신

기본적으로 Scout는 모델이 수정되면 어떤 속성이 변경되었는지와 관계없이 다시 인덱싱합니다. 이 동작을 바꾸고 싶다면 모델에 searchIndexShouldBeUpdated 메서드를 정의하면 됩니다.

/** * Determine if the search index should be updated. */ public function searchIndexShouldBeUpdated(): bool { return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']); }

레코드 삭제

인덱스에서 레코드를 제거하려면 데이터베이스에서 모델을 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 () { // 모델 작업을 수행합니다... });

조건부로 검색 가능한 모델 인스턴스

특정 조건에서만 모델을 검색 가능하게 만들어야 할 때가 있습니다. 예를 들어 App\Models\Post 모델이 "draft"(임시 저장)와 "published"(발행) 두 가지 상태 중 하나라고 가정해 보겠습니다. 이때 "published" 상태의 게시글만 검색 가능하게 하고 싶을 수 있습니다. 이를 위해 모델에 shouldBeSearchable 메서드를 정의합니다.

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

shouldBeSearchable 메서드는 save와 create 메서드, 쿼리, 연관 관계를 통해 모델을 다룰 때만 적용됩니다. searchable 메서드로 모델이나 컬렉션을 직접 검색 가능하게 만들면 shouldBeSearchable 메서드의 결과가 무시됩니다.

WARNING

Scout의 "database" 엔진을 사용할 때는 모든 검색 대상 데이터가 항상 데이터베이스에 저장되어 있으므로 shouldBeSearchable 메서드를 적용할 수 없습니다. 데이터베이스 엔진에서 비슷한 동작을 구현하려면 대신 where 절을 사용하세요.

검색

search 메서드를 사용해 모델 검색을 시작할 수 있습니다. 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();

데이터베이스, Meilisearch, Typesense, Turbopuffer 엔진은 쿼리의 의미를 기준으로 레코드를 찾는 시맨틱 검색을 지원합니다. Scout가 임베딩을 생성하는 경우, 시맨틱 검색과 하이브리드 검색에는 Laravel AI SDK가 필요합니다. Typesense의 네이티브 임베딩, Turbopuffer의 네이티브 임베딩, 그리고 미리 계산한 쿼리 벡터는 Laravel AI SDK가 필요하지 않습니다.

선택한 엔진에 임베딩을 설정한 후, 검색 쿼리에서 semantic 메서드를 호출합니다.

$articles = Article::search('staying cool in the summer') ->semantic() ->get();

선택한 엔진이 지원하는 경우 최소 유사도 임계값을 지정할 수 있습니다.

$articles = Article::search('renewable energy storage') ->semantic(minSimilarity: 0.6) ->get();

전문 검색과 시맨틱 검색을 함께 사용하려면 hybrid 메서드를 사용합니다. 처음 두 인수는 텍스트 검색 결과와 시맨틱 검색 결과의 상대적 가중치를 지정합니다.

$articles = Article::search('renewable energy storage') ->hybrid(textWeight: 1, semanticWeight: 2) ->get();

커스텀 인덱스

서드파티 엔진을 사용하면 검색 쿼리는 보통 모델의 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();

=, !=, <, >, >=, <= 비교 연산자를 사용해 더 복잡한 쿼리를 만들 수도 있습니다.

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 메서드를 사용하면 지정한 컬럼의 값이 주어진 배열에 포함되어 있는지 확인할 수 있습니다.

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

whereNotIn 메서드는 지정한 컬럼의 값이 주어진 배열에 포함되어 있지 않은지 확인합니다.

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

WARNING

애플리케이션에서 Meilisearch를 사용한다면, Scout의 "where" 절을 사용하기 전에 애플리케이션의 필터링 가능한 속성을 설정해야 합니다.

Eloquent 결과 쿼리 커스터마이징

Scout가 애플리케이션의 검색 엔진에서 일치하는 모델 목록을 가져오고 나면, 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();

서드파티 엔진을 사용하면 이 콜백은 관련 모델을 검색 엔진에서 이미 가져온 뒤에 호출되므로, 결과를 "필터링"하는 용도로 사용해서는 안 됩니다. 필터링에는 Scout where 절을 사용하세요. 반면 데이터베이스 엔진을 사용하면 query 메서드의 조건이 데이터베이스 쿼리에 직접 적용되므로 필터링 용도로도 사용할 수 있습니다.

페이지네이션

모델 컬렉션을 조회하는 것 외에도 paginate 메서드로 검색 결과를 페이지네이션할 수 있습니다. 이 메서드는 일반적인 Eloquent 쿼리를 페이지네이션할 때와 마찬가지로 Illuminate\Pagination\LengthAwarePaginator 인스턴스를 반환합니다.

use App\Models\Order; $orders = Order::search('Star Trek')->paginate();

paginate 메서드의 첫 번째 인수로 개수를 전달하면 페이지당 조회할 모델 수를 지정할 수 있습니다.

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

데이터베이스 엔진을 사용할 때는 simplePaginate 메서드도 사용할 수 있습니다. paginate는 페이지 번호를 표시하기 위해 일치하는 전체 레코드 수를 조회하지만, simplePaginate는 현재 페이지 이후에 결과가 더 있는지만 확인합니다. 그래서 "이전" / "다음" 링크만 필요한 대용량 데이터셋에서 더 효율적입니다.

$orders = Order::search('Star Trek')->simplePaginate(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); });

WARNING

검색 엔진은 Eloquent 모델의 글로벌 스코프 정의를 알지 못하므로, Scout 페이지네이션을 사용하는 애플리케이션에서는 글로벌 스코프를 사용하지 않아야 합니다. 또는 Scout로 검색할 때 글로벌 스코프의 조건을 직접 다시 구현해야 합니다.

소프트 삭제

인덱싱된 모델이 소프트 삭제를 사용하고 소프트 삭제된 모델도 검색해야 한다면, config/scout.php 설정 파일의 soft_delete 옵션을 true로 설정합니다.

'soft_delete' => true,

이 설정 옵션이 true이면 Scout는 소프트 삭제된 모델을 검색 인덱스에서 제거하지 않습니다. 대신 인덱싱된 레코드에 숨김 속성인 __soft_deleted를 설정합니다. 그러면 검색할 때 withTrashed 또는 onlyTrashed 메서드를 사용해 소프트 삭제된 레코드를 조회할 수 있습니다.

use App\Models\Order; // 결과를 조회할 때 삭제된 레코드를 포함합니다... $orders = Order::search('Star Trek')->withTrashed()->get(); // 결과를 조회할 때 삭제된 레코드만 포함합니다... $orders = Order::search('Star Trek')->onlyTrashed()->get();

NOTE

소프트 삭제된 모델을 forceDelete로 영구 삭제하면 Scout가 검색 인덱스에서도 자동으로 제거합니다.

엔진 검색 커스터마이징

엔진의 검색 동작을 세밀하게 커스터마이징해야 한다면 search 메서드의 두 번째 인수로 클로저를 전달할 수 있습니다. 예를 들어 이 콜백을 사용하면 검색 쿼리가 Algolia로 전달되기 전에 검색 옵션에 지리 정보(geo-location) 데이터를 추가할 수 있습니다.

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 추상 클래스를 상속해야 합니다. 이 추상 클래스에는 커스텀 엔진이 반드시 구현해야 하는 여덟 개의 메서드가 있습니다.

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 서비스 컨테이너에서 resolve할 수 있습니다. extend 메서드는 App\Providers\AppServiceProvider 클래스 또는 애플리케이션에서 사용하는 다른 서비스 프로바이더의 boot 메서드에서 호출해야 합니다.

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',

이 문서는 Laravel 공식 문서(MIT)를 한국 개발자를 위해 번역·재구성한 것입니다.

번역일: 2026년 11월 14일