> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 검색

> Laravel의 검색 기능의 전체상. 전문 검색·벡터 검색·리랭킹·Laravel Scout를 용도에 맞춰 구분 사용하는 방법을 설명합니다.

## 시작하기

애플리케이션에 검색 기능을 추가하는 방법은 용도에 따라 여러 가지가 있습니다. Laravel은 키워드 일치부터 AI를 사용한 시맨틱 검색까지, 외부 서비스 불필요로 대응할 수 있는 조립된 도구를 제공하고 있습니다.

```mermaid theme={null}
flowchart TD
    Q["검색 요건"]
    Q --> A{"키워드 일치로 충분?"}
    A -->|Yes| B["전문 검색<br>whereFullText"]
    A -->|No - 의미로 일치시키고 싶다| C["벡터 검색<br>whereVectorSimilarTo"]
    Q --> D{"모델 자동 동기가 필요?"}
    D -->|Yes| E["Laravel Scout<br>Searchable 트레이트"]
    Q --> F{"결과의 관련도를 AI로 재순위 부여?"}
    F -->|Yes| G["리랭킹<br>AI SDK Reranking"]
```

### 기능 비교

| 기능                     | 외부 서비스                      | 특징                                      |
| ---------------------- | --------------------------- | --------------------------------------- |
| `whereFullText`        | 불필요                         | MariaDB / MySQL / PostgreSQL 조립된 전문 인덱스 |
| `whereVectorSimilarTo` | 불필요 (PostgreSQL + pgvector) | 의미적인 유사도로 검색. AI SDK가 필요                |
| `Reranking`            | AI 프로바이더                    | 임의의 결과 세트를 AI로 관련도 순으로 재정렬              |
| Laravel Scout          | 불필요 (database 엔진) / 임의      | Eloquent 모델의 자동 인덱스 동기                  |

***

## 전문 검색

`LIKE` 쿼리는 심플한 부분 일치에는 편리하지만, 언어를 이해하지 않습니다. 전문 검색은 전용 인덱스를 사용해 단어의 경계·어형 변화·관련도 스코어를 고려한 검색을 수행합니다.

MariaDB·MySQL·PostgreSQL은 전문 검색을 조립되어 지원하고 있어, 외부 서비스는 불필요합니다.

<Warning>
  전문 검색은 MariaDB·MySQL·PostgreSQL에서 지원됩니다.
</Warning>

### 전문 인덱스의 추가

전문 검색을 사용하려면, 우선 대상 컬럼에 전문 인덱스를 추가합니다.

```php theme={null}
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();

    $table->fullText(['title', 'body']); // 복합 인덱스
});
```

PostgreSQL에서는 인덱스에 언어 설정을 지정할 수 있습니다. 영어 이외의 언어에서는 어형 변화의 처리가 바뀝니다.

```php theme={null}
$table->fullText('body')->language('english');
```

인덱스의 상세는 [마이그레이션](/ko/migrations)을 참조해 주세요.

<Info>
  **한국어 전문 검색의 주의 사항**
  MySQL에서의 한국어 전문 검색은 약간 사용하기 어려운 면이 있습니다. AWS RDS에서는 N-gram 파서만 이용 가능하며, 형태소 분석 플러그인을 추가할 수 없기 때문에 제한됩니다. Laravel Cloud의 MySQL도 마찬가지라고 생각됩니다. PostgreSQL에서도 한국어의 어형 변화 대응은 한정적입니다. 한국어 검색의 정확도가 중요한 경우는 Meilisearch나 Typesense 등의 전용 엔진의 이용을 검토해 주세요.
</Info>

### 전문 쿼리의 실행

인덱스를 추가하면 `whereFullText` 메서드로 검색합니다. Laravel은 사용하고 있는 데이터베이스 드라이버에 맞춰 적절한 SQL을 생성합니다 (MariaDB / MySQL에서는 `MATCH(...) AGAINST(...)`, PostgreSQL에서는 `to_tsvector(...) @@ plainto_tsquery(...)`).

```php theme={null}
$articles = Article::whereFullText('body', 'web developer')->get();
```

복합 인덱스를 작성한 경우는, 같은 컬럼 배열을 전달합니다.

```php theme={null}
$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();
```

<Info>
  MariaDB·MySQL에서는 결과가 자동적으로 관련도 스코어 순으로 늘어섭니다. PostgreSQL에서는 `whereFullText`는 매치하는 레코드를 필터링할 뿐이며 관련도 순이 되지 않습니다. PostgreSQL에서 자동적인 관련도 순이 필요한 경우는 [Scout의 데이터베이스 엔진](#laravel-scout)이 유효합니다.
</Info>

`orWhereFullText` 메서드로 OR 조건으로서 전문 검색을 추가할 수도 있습니다. 상세는 [쿼리 빌더 문서](/ko/query-builder)를 참조해 주세요.

***

## 시맨틱 / 벡터 검색

전문 검색은 키워드의 일치에 의존하고 있습니다. 벡터 검색은 근본적으로 다른 접근 방법으로, AI가 생성한 벡터 임베딩을 사용해 텍스트의 *의미*를 수치 배열로서 표현하고, 의미적으로 가까운 결과를 검색합니다.

예를 들어 "best wineries in Napa Valley"라는 검색으로 "Top Vineyards to Visit"라는 타이틀의 기사가 히트합니다. 단어가 일치하지 않아도 의미가 가깝기 때문입니다.

<Note>
  벡터 검색에는 [Laravel AI SDK](/ko/ai-sdk)가 필요하며, PostgreSQL(`pgvector` 확장이 필요)과 MongoDB(Laravel MongoDB 패키지가 필요)를 지원합니다. [Laravel Cloud](https://laravel.com/cloud)의 모든 Postgres 데이터베이스에는 `pgvector`가 사전 설치되어 있습니다.
</Note>

### 임베딩의 생성

임베딩은 텍스트의 의미를 나타내는 고차원의 수치 배열(통상 수백\~수천 차원)입니다. Laravel의 `Stringable` 클래스의 `toEmbeddings` 메서드로 생성할 수 있습니다.

```php theme={null}
use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
```

여러 텍스트를 한 번에 처리하는 경우는 `Embeddings` 클래스를 사용하면 효율적입니다(API 호출이 1회로 끝납니다).

```php theme={null}
use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    'Napa Valley has great wine.',
    'Laravel is a PHP framework.',
])->generate();

$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]
```

임베딩 프로바이더의 설정이나 차원 수의 커스터마이즈에 대해서는 [AI SDK 문서](/ko/ai-sdk)를 참조해 주세요.

### 벡터의 보존과 인덱스 작성

벡터 임베딩을 보존하려면, 마이그레이션으로 `vector` 컬럼을 정의합니다. 임베딩 프로바이더의 출력 차원 수에 맞춰 `dimensions`를 지정해 주세요(예: OpenAI의 `text-embedding-3-small`은 1536 차원). `index()`를 호출해 HNSW 인덱스를 작성하면, 대규모 데이터셋에서의 유사 검색이 대폭 고속화됩니다.

```php theme={null}
Schema::ensureVectorExtensionExists(); // pgvector 확장을 활성화

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});
```

Eloquent 모델에서는 `embedding` 컬럼을 `array`로 캐스트해, PHP 배열과 데이터베이스의 벡터 형식의 변환을 자동화합니다.

```php theme={null}
protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}
```

벡터 컬럼과 인덱스의 상세는 [마이그레이션](/ko/migrations)을 참조해 주세요.

### 유사도에 의한 검색

임베딩을 보존하면, `whereVectorSimilarTo` 메서드로 유사 레코드를 검색할 수 있습니다. 코사인 유사도로 벡터를 비교하고, `minSimilarity` 임계값 이하의 결과를 필터링해, 관련성이 높은 순으로 자동 정렬합니다. 임계값은 `0.0`\~`1.0`의 값으로, `1.0`은 완전 일치를 의미합니다.

```php theme={null}
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();
```

임베딩 배열 대신에 문자열을 전달하면, Laravel이 자동적으로 임베딩을 생성해 줍니다. 사용자의 검색 쿼리를 그대로 전달할 수 있으므로 매우 편리합니다.

```php theme={null}
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();
```

보다 세밀한 제어가 필요한 경우는 `whereVectorDistanceLessThan`·`selectVectorDistance`·`orderByVectorDistance`도 이용할 수 있습니다. 상세는 [쿼리 빌더 문서](/ko/query-builder)와 [AI SDK 문서](/ko/ai-sdk)를 참조해 주세요.

***

## 리랭킹

리랭킹은, AI 모델이 결과 세트를 쿼리와의 관련도 순으로 재정렬하는 수법입니다. 벡터 검색과 달리, 사전에 임베딩을 계산·보존할 필요는 없고, 임의의 텍스트 컬렉션에 적용할 수 있습니다.

전문 검색으로 대량의 레코드를 빠르게 좁힌 후에 리랭킹을 적용하는 "**검색→리랭크**" 패턴이 특히 효과적입니다. 데이터베이스의 속도와 AI의 정확도를 양립할 수 있습니다.

```php theme={null}
use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
```

Laravel 컬렉션에는 `rerank` 매크로가 있어, 필드명(또는 클로저)과 쿼리를 전달하는 것만으로 Eloquent의 결과를 리랭크할 수 있습니다.

```php theme={null}
$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');
```

리랭킹 프로바이더의 설정과 이용 가능한 옵션에 대해서는 [AI SDK 문서](/ko/ai-sdk)를 참조해 주세요.

***

## Laravel Scout

여기까지 설명한 검색 수법은 모두 쿼리 빌더의 메서드를 직접 호출하는 것이었습니다. [Laravel Scout](/ko/scout)는 다른 접근 방법을 취합니다. Eloquent 모델에 `Searchable` 트레이트를 추가하면, Scout가 레코드의 작성·업데이트·삭제에 맞춰 검색 인덱스를 자동 동기합니다.

### 데이터베이스 엔진

Scout 조립된 데이터베이스 엔진은 기존의 데이터베이스에 대해 전문 검색과 `LIKE` 검색을 수행합니다. 외부 서비스도 인프라도 추가 불필요합니다.

`toSearchableArray` 메서드로 검색 대상의 컬럼을 정의합니다. PHP 애트리뷰트로 컬럼별로 검색 전략을 지정할 수 있습니다.

```php theme={null}
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
use Laravel\Scout\Searchable;

class Article extends Model
{
    use Searchable;

    #[SearchUsingPrefix(['id'])]
    #[SearchUsingFullText(['title', 'body'])]
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}
```

| 애트리뷰트                 | 검색 전략                                          |
| --------------------- | ---------------------------------------------- |
| `SearchUsingFullText` | 전문 인덱스를 사용 (`MATCH...AGAINST` / `to_tsvector`) |
| `SearchUsingPrefix`   | 전방 일치 (`example%`)                             |
| 없음                    | 전후 와일드카드 (`%example%`)                         |

<Warning>
  `SearchUsingFullText`를 지정하는 컬럼에는 사전에 [전문 인덱스](/ko/migrations)가 필요합니다.
</Warning>

트레이트를 추가하면, `search` 메서드로 모델을 검색할 수 있습니다. Scout의 데이터베이스 엔진은 PostgreSQL에서도 자동적으로 관련도 순으로 결과를 반환합니다.

```php theme={null}
$articles = Article::search('Laravel')->get();
```

### 서드파티 엔진

Scout는 [Algolia](https://www.algolia.com/)·[Meilisearch](https://www.meilisearch.com)·[Typesense](https://typesense.org) 등의 서드파티 검색 엔진도 지원합니다. 이들은 오타 허용·패싯 검색·지오 서치·커스텀 랭킹 등 고도의 기능을 제공합니다.

Scout는 통일 API를 제공하기 때문에, 나중에 데이터베이스 엔진에서 서드파티 엔진으로 이행할 때의 코드 변경은 최소한으로 끝납니다.

<Note>
  대부분의 애플리케이션은 외부 검색 엔진을 필요로 하지 않습니다. 이 페이지에서 설명한 조립된 수법이 대다수의 유스 케이스를 커버합니다.
</Note>

Scout의 상세는 [Laravel Scout 가이드](/ko/scout)를 참조해 주세요.

***

## 기술의 조합

여기까지 소개한 검색 수법은 상호 배타적이지 않습니다. 조합함으로써 최량의 결과를 얻을 수 있습니다.

### 전문 검색 + 리랭킹

전문 검색으로 후보를 빠르게 좁혀, 리랭킹으로 시맨틱한 관련도 순으로 재정렬합니다. 데이터베이스 속도와 AI 정확도를 양립하는 패턴입니다.

```php theme={null}
$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);
```

### 벡터 검색 + 통상의 필터

벡터 유사 검색과 통상의 `where` 절을 조합하여, 특정한 서브셋으로 좁힌 시맨틱 검색을 실현합니다. 팀이나 카테고리로 좁히면서 의미적인 검색을 하고 싶은 경우에 편리합니다.

```php theme={null}
$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();
```

***

## 관련 페이지

<Card title="Laravel Scout" icon="magnifying-glass" href="/ko/scout">
  Searchable 트레이트로 모델을 자동 인덱스 동기하는 완전 가이드.
</Card>

<Card title="Laravel AI SDK" icon="sparkles" href="/ko/ai-sdk">
  벡터 임베딩과 리랭킹에 필요한 AI SDK의 설정 방법.
</Card>

<Card title="쿼리 빌더" icon="database" href="/ko/query-builder">
  whereFullText·whereVectorSimilarTo 등의 쿼리 빌더 메서드의 상세.
</Card>

<Card title="마이그레이션" icon="table" href="/ko/migrations">
  전문 인덱스와 벡터 컬럼의 작성 방법.
</Card>


## Related topics

- [Basic client - Laravel Bluesky](/ko/packages/laravel-bluesky/basic-client.md)
- [Laravel AI SDK](/ko/ai-sdk.md)
- [2026년 3월 Laravel 업데이트](/ko/blog/changelog/202603.md)
- [MongoDB](/ko/mongodb.md)
- [Laravel과 AI 개발](/ko/ai.md)