Meilisearch 완벽 가이드 — 오픈소스 검색 엔진·인덱싱·랭킹·Next.js 통합

이 글의 핵심

Meilisearch는 Rust로 구현된 오픈소스 검색 엔진으로, 전자상거래·콘텐츠·SaaS 대시보드 등에서 흔히 요구되는 빠른 자동완성형 검색을 단일 프로세스(또는 소규모 클러스터)로 제공합니다. 데이터베이스의 LIKE나 단순 전문 검색(full-text search) 만으로는 부족한 랭킹·오타 허용(typo tolerance)·필터 조합을 API 수준에서 선언적으로 다룰 수 있다는 점이 실무에서의 매력입니다.

이 글에서는 핵심 개념(인덱스·문서·태스크) 을 정리한 뒤, 인덱싱 파이프라인과 필터링, 검색 파라미터와 랭킹 규칙, 오타 허용·동의어, 다국어, Next.js·React 통합 패턴, 마지막으로 Algolia와의 비교까지 연결합니다. 독자는 REST·JSON 경험과 기본적인 검색 용어(토큰·역인덱스)에 익숙하다고 가정합니다.

---

1. Meilisearch가 해결하는 문제

웹 서비스의 검색은 “문자열 매칭”이 아니라 사용자 의도에 가까운 결과를 빠르게 제시하는 UX 문제에 가깝습니다. 다음 요구가 동시에 걸리는 경우가 많습니다.

• 응답 지연: 입력할 때마다 수십~수백 ms 안에 결과를 갱신해야 함
• 오타·형태 변화: 철자 실수, 띄어쓰기 차이에도 유연해야 함
• 비즈니스 규칙: 재고·가격·카테고리·권한 같은 필터와 함께 동작
• 운영 단순성: 검색 전용 클러스터를 Elasticsearch 수준으로 키우기 어려운 팀도 있음

Meilisearch는 이런 제품 검색(product search) 성격의 워크로드에 맞춰, 기본 랭킹·오타·동의어를 포함한 단순한 멘탈 모델을 제공합니다. 반대로 말하면, 대규모 로그 분석·복잡한 집계·매우 무거운 텍스트 분석 파이프라인을 한 엔진에 모두 실을 목적의 솔루션은 아닙니다. 용도를 분명히 할수록 도입 성공률이 높아집니다.

---

2. 아키텍처 개요

전형적인 구성은 다음과 같습니다.

1. 애플리케이션 DB가 진실의 원천(source of truth)
2. 변경 이벤트(배치·CDC·주기 동기화)로 문서를 Meilisearch에 적재
3. 사용자 검색은 Meilisearch API로만 처리하거나, 백엔드 프록시를 경유

Meilisearch는 문서 지향 JSON 저장소로서 검색에 최적화된 역인덱스를 유지합니다. 인덱스 갱신은 내부적으로 태스크(task) 로 비동기 처리되는 부분이 많으므로, “쓰기 직후 즉시 읽기”를 DB처럼 가정하면 안 됩니다. 최종 일관성(eventual consistency) 을 전제로 설계합니다.

---

3. 핵심 개념

3.1 인덱스(index)

인덱스는 문서들의 논리적 컨테이너입니다. 예를 들어 products, articles, users처럼 도메인 단위로 나누는 경우가 많습니다. 인덱스마다 설정(settings) 이 독립적으로 존재하며, 검색 가능 필드·필터 가능 필드·랭킹 규칙 등을 이 단위로 선언합니다.

3.2 문서(document)와 기본 키(primary key)

각 문서는 JSON 객체입니다. 인덱스에 문서를 넣을 때는 고유 식별자가 필요합니다. 보통 id 필드를 기본 키로 지정하거나, Meilisearch가 문서에서 키를 추론하도록 합니다. 운영에서는 애플리케이션의 PK와 1:1로 매핑하는 편이 동기화·삭제에 유리합니다.

3.3 설정(settings)과 재색인

검색 가능 필드 순서, 필터 가능 필드, 정렬 가능 필드, 랭킹 규칙, 오타 설정, 동의어 등은 인덱스 설정으로 관리합니다. 설정을 바꾸면 내부적으로 재색인(re-indexing) 이 필요할 수 있으며, 이는 태스크로 관찰합니다. 배포 파이프라인에서 “설정 변경 → 태스크 완료 대기 → 트래픽 전환” 같은 절차를 두는 팀도 있습니다.

3.4 태스크(task)

문서 추가·삭제·설정 업데이트는 비동기 태스크로 처리되는 경우가 많습니다. 운영 시에는 태스크 ID로 상태를 조회하고, 실패 시 원인을 로그와 함께 추적합니다. 대량 적재 시에는 배치 크기와 동시 요청 수를 조절해 서버와 애플리케이션 모두에서 백프레셔(backpressure)를 걸어야 합니다.

3.5 API 키와 보안 모델

Meilisearch는 마스터 키를 기반으로 검색 전용 키, 문서 쓰기 키, 관리 키 등을 파생합니다. 기본 원칙은 단순합니다.

• 브라우저에 노출: 검색만 가능한 권한(필요 시 인덱스 제한)
• 서버에서만: 문서 적재·설정 변경

공개 사이트에서 마스터 키를 프론트엔드 번들에 넣는 것은 즉시 취약점입니다. Next.js라면 Route Handler나 서버 액션 뒤에 숨기거나, API Gateway에서 JWT·세션 검증 후 Meilisearch로 프록시하는 패턴이 일반적입니다.

---

4. 인덱싱과 필터링

4.1 검색 가능 필드(searchable attributes)

모든 필드를 검색에 넣으면 노이즈가 늘고 속도가 떨어질 수 있습니다. 실무에서는 다음처럼 의도를 분리합니다.

• 제목·이름·SKU: 높은 가중치(앞쪽에 둠)
• 본문·설명: 보조
• 내부 메모·원본 JSON: 검색 제외

Meilisearch는 필드 순서가 랭킹에 영향을 주도록 설계되어 있어, “무엇을 먼저 맞추면 좋은가”를 설정으로 표현합니다.

4.2 필터 가능 필드(filterable attributes)

필터는 정확 일치·범위에 가깝게 동작하도록 별도 인덱싱이 필요합니다. 카테고리, 브랜드, 재고 여부, 가격대, 공개 범위 같은 facet 후보를 미리 filterable로 지정해야 합니다. 이를 누락하면 “검색은 되는데 필터가 안 먹는” 상황이 생깁니다.

4.3 정렬 가능 필드(sortable attributes)

“관련도순”이 아니라 최신순·가격순·인기순으로 바꾸려면 정렬에 쓸 필드를 sortable로 선언합니다. 정렬 키는 스키마 설계와 연결됩니다. 예를 들어 인기도를 실시간으로 반영하려면 주기적으로 문서를 갱신하거나, 별도 점수 필드를 두고 배치로 업데이트합니다.

4.4 문서 적재 패턴

대표적인 방법은 다음과 같습니다.

• 배치 임포트: 초기 마이그레이션·전체 재구축
• 증분 동기화: 변경된 레코드만 addDocuments/updateDocuments
• 삭제: DB에서 삭제된 PK는 Meilisearch에서도 deleteDocument로 맞춤

동기화 실패를 허용하지 않는 도메인이라면 아웃박스 패턴(outbox) 으로 이벤트를 먼저 기록하고, 워커가 Meilisearch에 재시도하는 방식이 안전합니다.

4.5 로컬 실행과 최소 예시

Docker로 프로세스를 띄운 뒤, HTTP API로 문서를 넣을 수 있습니다. 아래는 개념 확인용 최소 예시이며, 실제 프로덕션에서는 TLS·인증·네트워크 격리를 반드시 적용합니다.

# 개발용: 마스터 키는 예시이며 실제로는 강한 랜덤 값을 사용합니다.
docker run -d --name meili -p 7700:7700 \
  -e MEILI_MASTER_KEY=dev_master_key \
  getmeili/meilisearch:latest

curl -X POST 'http://localhost:7700/indexes/products/documents' \
  -H 'Authorization: Bearer dev_master_key' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    { "id": 1, "title": "무선 키보드", "category": "peripherals", "price": 89000 },
    { "id": 2, "title": "유선 마우스", "category": "peripherals", "price": 35000 }
  ]'

문서를 넣은 뒤에는 태스크 상태를 조회해 색인이 끝났는지 확인하고, 검색 요청에서 filter(예: category = peripherals)와 sort(정렬 가능 필드가 선언된 경우)를 조합합니다.

---

5. 검색 파라미터와 랭킹

5.1 기본 검색 동작

검색 요청은 보통 쿼리 문자열과 함께 필터·정렬·오프셋/페이지를 붙입니다. 인스턴트 검색 UI에서는 limit을 작게 잡고, 스크롤·페이지네이션에서는 offset/page 전략을 택합니다.

5.2 랭킹 규칙(ranking rules)

Meilisearch는 버킷 정렬(bucket sort) 에 가까운 방식으로, 앞선 규칙이 동점을 깨고 다음 규칙이 다시 순서를 가늠합니다. 그래서 규칙 배열의 순서 자체가 제품 UX를 바꾸는 중요한 설정입니다. 공식 문서에 정리된 내장 랭킹 규칙의 기본 순서는 다음과 같습니다(설정에서 재배열 가능).

["words", "typo", "proximity", "attributeRank", "sort", "wordPosition", "exactness"]

식별자	역할
words	매칭된 쿼리 용어 수가 많을수록 우선합니다. 쿼리 문자열의 단어 순서도 결과에 영향을 줍니다.
typo	오타가 적은 매칭을 우선합니다.
proximity	쿼리 용어가 가깝게·쿼리와 같은 순서로 나타나는 문서를 우선합니다.
attributeRank	searchableAttributes에서 앞에 둔 필드에 매칭이 있으면 우대합니다(필드 내부 단어 위치는 이 규칙만으로는 다루지 않음).
sort	검색 요청에 sort 파라미터가 있을 때만 동작하며, 배치 순서에 따라 관련도 우선인지 정렬 엄격인지 성격이 달라집니다.
wordPosition	속성 안에서 매칭된 용어가 앞쪽에 있을수록 우선합니다.
exactness	쿼리와 더 동일한 형태의 단어 매칭을 우선합니다.

과거 호환용으로 attribute 규칙( attributeRank와 wordPosition을 합친 개념)이 문서화되어 있으나, 신규 설정에서는 attributeRank와 wordPosition을 분리해 사이에 다른 규칙을 끼우는 편이 유연합니다. 커스텀 랭킹(예: popularity:desc)은 보통 맨 뒤에 두어 텍스트 관련도를 먼저 정한 뒤 비즈니스 로직으로 동점을 깹니다. 배포 중인 버전의 공식 문서를 기준으로 확인하는 것이 안전합니다.

5.3 하이라이트와 크롭

검색 결과 UI에서는 attributesToRetrieve로 필요한 필드만 줄이고, 스니펫을 위해 크롭·하이라이트 옵션을 사용합니다. 이는 트래픽과 페이로드 크기를 동시에 줄이는 데 도움이 됩니다.

5.4 멱등성과 캐싱

검색 API는 읽기 위주이므로 CDN·엣지 캐시를 고려할 수 있습니다. 다만 필터 조합이 매우 많은 B2C에서는 캐시 키 폭발을 경계해야 합니다. 반대로 내부 관리자 검색처럼 변동이 적다면 서버 측 캐시가 효과적입니다.

---

6. Typo Tolerance와 Synonyms

6.1 오타 허용(typo tolerance)

사용자 입력은 항상 완벽하지 않습니다. Meilisearch는 기본적으로 짧은 단어는 엄격·긴 단어는 관대 같은 휴리스틱을 적용해 오타를 허용합니다. 설정에서는 한 단어·두 단어에서 허용할 오타 수, 금지 단어 목록 등을 조정할 수 있습니다.

실무 팁은 다음과 같습니다.

• 제품 코드·SKU처럼 오타 허용이 오히려 독이 되는 필드는 별도 인덱스로 쪼개거나, 검색 경로를 분리합니다.
• 브랜드명은 동의어로 보강하는 편이 안전한 경우가 많습니다.

6.2 동의어(synonyms)

동의어는 검색어 확장과 정규화에 쓰입니다. 예를 들어 “노트북·랩탑·laptop”, “스마트폰·휴대폰”처럼 동일 의미 군을 묶습니다. 운영에서는 초기에 과도한 동의어를 넣기보다, 검색 로그에서 실패 쿼리를 모아 점진적으로 채우는 방식이 유지보수에 유리합니다.

6.3 불용어(stop words)

“그·이·을” 같은 조사나 영어의 “the, a”는 검색 노이즈가 될 수 있습니다. 다만 제품명에 불용어가 포함되는 도메인에서는 오히려 결과를 망칠 수 있으므로, 언어별 기본 불용어를 무비판적으로 넣지 말고 샘플 쿼리로 검증합니다.

---

7. 다국어 지원

7.1 언어 설정의 의미

Meilisearch는 언어별 토큰화·정규화를 통해 검색 품질을 끌어올립니다. 한국어·일본어·중국어처럼 형태소·분절 이슈가 큰 언어는 설정의 영향이 큽니다. 반면 영문 위주 카탈로그라면 기본 설정으로도 충분한 경우가 많습니다.

7.2 실무 전략

• 단일 인덱스·다국어 필드: title_ko, title_en처럼 필드를 나누고 searchable 순서를 조정
• 인덱스 분리: 로케일별로 아예 인덱스를 나누어 랭킹·동의어·불용어를 분리
• 동기화 파이프라인: 번역 콘텐츠가 비동기로 들어오면 태스크 지연을 UX에 반영

한국어 서비스에서는 사용자 입력 정규화(유니코드 NFC/NFD, 자모 분리 이슈)도 함께 점검합니다. 검색 엔진만으로 모든 문제를 해결하지 못하는 지점입니다.

---

8. Next.js·React 통합

8.1 공식 JavaScript SDK

서버와 브라우저 모두에서 meilisearch 패키지로 클라이언트를 생성합니다. 호스트 URL과 API 키는 환경 변수로 분리합니다.

// lib/meilisearch.ts — 서버 전용 설정 예시
import { MeiliSearch } from 'meilisearch';

export function getServerMeiliClient() {
  const host = process.env.MEILI_HOST;
  const apiKey = process.env.MEILI_API_KEY;
  if (!host || !apiKey) {
    throw new Error('Meilisearch 환경 변수가 설정되지 않았습니다.');
  }
  return new MeiliSearch({ host, apiKey });
}

프론트엔드에 직접 붙일 때는 검색 전용 키만 사용하고, 인덱스 UID를 제한한 키를 발급합니다.

8.2 Route Handler로 프록시(권장 패턴)

Next.js App Router에서는 클라이언트 → Next API → Meilisearch 형태로 숨겨 키 유출을 방지합니다.

// app/api/search/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { getServerMeiliClient } from '@/lib/meilisearch';

export async function GET(req: NextRequest) {
  const q = req.nextUrl.searchParams.get('q') ?? '';
  const indexUid = req.nextUrl.searchParams.get('index') ?? 'products';

  if (!q.trim()) {
    return NextResponse.json({ hits: [] });
  }

  const client = getServerMeiliClient();
  const index = client.index(indexUid);

  const result = await index.search(q, {
    limit: 20,
    attributesToRetrieve: ['id', 'title', 'price', 'category'],
    filter: undefined,
  });

  return NextResponse.json(result);
}

이 방식이면 레이트 리밋·인증·감사 로그를 같은 계층에 추가하기 쉽습니다.

8.3 InstantSearch와의 연동

Algolia의 InstantSearch에 익숙하다면, Meilisearch용 클라이언트와 어댑터를 사용해 위젯·상태 모델을 재사용할 수 있습니다. 일반적인 조합은 meilisearch SDK와 @meilisearch/instant-meilisearch 입니다. 호스트와 검색 전용 키를 넣어 instantMeiliSearch 인스턴스를 만들고, InstantSearch의 InstantSearch·SearchBox·Hits 등에 넘깁니다.

// 예시: InstantSearch + Meilisearch 어댑터(번들 환경에 맞게 import 경로 조정)
import { instantMeiliSearch } from '@meilisearch/instant-meilisearch';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';

const { searchClient } = instantMeiliSearch(
  process.env.NEXT_PUBLIC_MEILI_HOST!,
  process.env.NEXT_PUBLIC_MEILI_SEARCH_KEY! // 반드시 search-only 키
);

export function ProductSearch() {
  return (
    <InstantSearch searchClient={searchClient} indexName="products">
      <SearchBox />
      <Hits hitComponent={Hit} />
    </InstantSearch>
  );
}

NEXT_PUBLIC_*로 키가 노출되므로, 인덱스·작업 권한이 최소인 search 키만 발급하고, 민감한 필드는 attributesToRetrieve로 서버에서 제한하는 이중 방어를 고려합니다. UI는 검색창·필터·하이라이트를 조합하는 패턴이 Algolia와 유사하지만, Algolia 전용 확장 위젯에 깊게 결합되어 있다면 일부 교체 비용이 발생합니다.

8.4 React 상태 관리와 디바운스

인스턴트 검색은 요청 폭주를 막기 위해 디바운스·취소(AbortController) 가 필수입니다. 사용자가 빠르게 타이핑할 때 이전 요청을 버리지 않으면 레이스 컨디션으로 화면이 어긋납니다.

---

9. Algolia vs Meilisearch

완전한 “승자”는 없고, 조직의 제약으로 선택이 갈립니다.

관점	Algolia	Meilisearch
라이선스	상용 SaaS(티어 과금)	오픈소스(자체 호스팅)·클라우드 호스팅 선택지
운영	인프라 부담 낮음	직접 운영 시 백업·업그레이드·모니터링 필요
에코시스템	성숙한 UI·플러그인·교육 자료	성장 중, Algolia 대체 사례 증가
기능 깊이	대규모 상용 기능·지원 체계	심플한 API·빠른 기본 검색 UX
데이터 주권	클라우드에 상주	온프레미스·VPC 배치 용이

Algolia가 유리한 경우: 검색을 핵심 매출에 직결시키고, SLA·지원·글로벌 엣지가 중요한 경우.

Meilisearch가 유리한 경우: 비용·데이터 주권·온프레미스가 중요하고, 팀이 자체 운영을 감당할 수 있는 경우.

이미 Algolia를 쓰는 조직에서 Meilisearch로 이전할 때는 랭킹·동의어·필터 표현 차이를 PoC로 검증해야 합니다. “API가 비슷하다”와 “결과가 동일하다”는 다릅니다.

---

10. 운영 체크리스트

• 키 관리: 마스터 키는 절대 클라이언트에 없음
• 동기화: 삭제 누락이 검색 품질을 크게 망침 — 양방향 일치 검증
• 모니터링: p95 지연, 태스크 실패율, 인덱스 크기, GC·메모리
• 백업: 인덱스는 재구축 가능하더라도 스냅샷·설정 백업 절차를 문서화
• 버전 고정: 검색 엔진은 마이너 업그레이드도 설정 영향이 있으므로 릴리스 노트 확인

---

11. 요약

Meilisearch는 빠른 사용자-facing 검색을 위해 설계된 오픈소스 엔진으로, 인덱스·문서·설정·태스크라는 단순한 모델 위에 필터·정렬·랭킹·오타·동의어를 얹습니다. Next.js·React에서는 서버 프록시로 키를 보호하고, InstantSearch 계열 UI와 조합해 생산성을 확보할 수 있습니다. Algolia와의 선택은 기능 표가 아니라 운영 부담·비용·데이터 주권·조직의 검색 성숙도로 결정하는 것이 안전합니다.

---

참고 및 다음 단계

공식 문서에서 버전별 엔드포인트·설정 키 이름을 확인하고, 프로젝트에는 스테이징 인덱스를 두어 동의어·랭킹 실험을 안전하게 반복하는 것을 권장합니다. 배포 전에는 git push 후 npm run deploy를 사용하는 이 저장소 관례에 맞춰 변경을 반영하십시오.