2025년 9월 21일·8분
앱에서 인스턴트 서버 사이드 검색을 위한 Meilisearch
빠르고 오타를 허용하는 서버 사이드 검색을 위해 Meilisearch를 백엔드에 추가하는 방법: 설치, 인덱싱, 랭킹 조정, 필터/정렬/패싯, 보안 및 확장 기본을 안내합니다.
빠르고 오타를 허용하는 서버 사이드 검색을 위해 Meilisearch를 백엔드에 추가하는 방법: 설치, 인덱싱, 랭킹 조정, 필터/정렬/패싯, 보안 및 확장 기본을 안내합니다.
서버 사이드 검색은 쿼리가 브라우저 내부가 아니라 서버(또는 전용 검색 서비스)에서 처리된다는 뜻입니다. 애플리케이션이 검색 요청을 보내면 서버가 인덱스에서 쿼리를 실행하고 순위가 매겨진 결과를 반환합니다.
데이터셋을 클라이언트로 전송할 수 없을 때, 플랫폼 간 일관된 관련성이 필요할 때, 또는 접근 제어가 필수일 때(예: 내부 도구에서 사용자가 허용된 것만 보아야 하는 경우) 서버 사이드 검색이 중요합니다. 또한 분석, 로깅, 예측 가능한 성능을 원할 때 기본 선택이 됩니다.
사람들은 검색 엔진 자체를 생각하지 않으며, 경험을 평가합니다. 좋은 “인스턴트” 검색 흐름은 보통 다음을 의미합니다:
이 요소들 중 하나라도 빠지면 사용자는 다른 쿼리를 시도하거나 스크롤을 더 하거나 검색을 포기합니다.
이 문서는 Meilisearch로 위와 같은 경험을 구축하기 위한 실용적 워크스루입니다. 안전한 설치 방법, 인덱싱 및 데이터 동기화 방식, 관련성 및 랭킹 규칙 튜닝, 필터/정렬/패싯 추가 방법, 그리고 검색이 앱 성장에 따라 빠르게 유지되도록 보안과 확장성에 대해 생각하는 방법을 다룹니다.
Meilisearch는 다음에 적합합니다:
목표는: 즉시성 있고 정확하며 신뢰할 수 있는 결과를 제공하되, 검색 자체가 큰 엔지니어링 프로젝트가 되지 않도록 하는 것입니다.
Meilisearch는 애플리케이션 옆에서 실행되는 검색 엔진입니다. 제품, 기사, 사용자, 지원 티켓 같은 문서를 전송하면 Meilisearch가 빠른 검색에 최적화된 인덱스를 만듭니다. 백엔드(또는 프론트엔드)는 간단한 HTTP API로 Meilisearch에 쿼리하고 밀리초 단위로 순위가 매겨진 결과를 받습니다.
Meilisearch는 현대 검색에서 기대되는 기능에 집중합니다:
짧거나 약간 잘못된, 애매한 쿼리일지라도 반응성이 좋고 관대하게 동작하도록 설계되었습니다.
Meilisearch는 주 데이터베이스의 대체물이 아닙니다. 쓰기, 트랜잭션, 제약은 데이터베이스가 유지하며, Meilisearch는 검색/조회에 필요한 선택된 필드의 복사본을 저장합니다.
좋은 사고 모델은: 데이터베이스는 저장 및 갱신, Meilisearch는 빠른 검색입니다.
Meilisearch는 매우 빠를 수 있지만 결과는 몇 가지 실무적인 요인에 따라 달라집니다:
작은~중간 규모 데이터셋에서는 단일 머신으로도 충분한 경우가 많습니다. 인덱스가 커질수록 무엇을 인덱싱할지, 어떻게 갱신할지에 대해 더 신중해야 합니다 — 이 점은 뒤섹션에서 다룹니다.
무엇을 실제로 검색할지 설치 전에 결정하세요. 인덱스와 문서가 사용자가 앱을 탐색하는 방식과 맞아야 Meilisearch가 “인스턴트”처럼 느껴집니다.
검색 가능한 엔터티를 나열하세요 — 보통 제품, 기사, 사용자, 도움말 문서, 위치 등입니다. 많은 앱에서는 엔터티 타입별 인덱스 하나(예: products, articles)가 가장 깔끔합니다. 이렇게 하면 랭킹 규칙과 필터가 예측 가능해집니다.
만약 UX가 여러 타입을 한 검색창에서 뒤지는 경우(“모두 검색”), 별도 인덱스를 유지하고 백엔드에서 결과를 합치거나 나중에 전용 “글로벌” 인덱스를 만들 수 있습니다. 모든 것을 하나의 인덱스에 억지로 넣지 마세요 — 필드와 필터가 진짜로 정렬되어 있지 않다면요.
각 문서에는 안정적인 식별자(기본 키)가 필요합니다. 다음을 충족하는 것을 고르세요:
id, sku, slug)문서 형태는 가능한 한 플랫 필드를 선호하세요. 플랫 구조가 필터와 정렬에 더 쉽습니다. author 객체처럼 묶음이 단단하고 거의 변하지 않는 경우 중첩 필드도 괜찮지만, 관계형 스키마를 그대로 반영하는 깊은 중첩은 피하세요 — 검색 문서는 읽기 최적화되어야 하고 데이터베이스 모양을 그대로 따를 필요는 없습니다.
실용적인 문서 설계 방법은 각 필드를 역할로 태그하는 것입니다:
이렇게 하면 흔한 실수를 피할 수 있습니다: “혹시 몰라서” 어떤 필드를 인덱싱했다가 결과가 시끄러워지거나 필터가 느려지는 것을 나중에 후회하는 일입니다.
데이터 내에서 “언어”는 몇 가지 의미가 있습니다:
lang: "en"와 같은 필드)초기에 언어별로 별도 인덱스를 사용할지(단순하고 예측 가능) 또는 언어 필드를 가진 단일 인덱스를 사용할지(인덱스 수는 적지만 더 많은 로직 필요) 결정하세요. 사용자가 한 번에 하나의 언어로 검색하는지, 번역을 어떻게 저장하는지에 따라 정답이 달라집니다.
Meilisearch 실행은 간단하지만 "기본값으로 안전"하게 운영하려면 몇 가지 선택이 필요합니다: 어디에 배포할지, 데이터를 어떻게 영속화할지, 마스터 키를 어떻게 다룰지 등을 결정하세요.
스토리지: Meilisearch는 인덱스를 디스크에 씁니다. 데이터 디렉터리는 신뢰성 있는 영속 스토리지에 두세요(에페메랄 컨테이너 스토리지 아님). 대용량 텍스트 필드와 많은 속성으로 인덱스가 빠르게 커질 수 있으니 용량 계획을 하세요.
메모리: 부하 시 검색 반응성을 유지할 수 있도록 충분한 RAM을 할당하세요. 스와핑이 발생하면 성능이 저하됩니다.
백업: Meilisearch 데이터 디렉터리를 백업하거나(또는 스토리지 계층에서 스냅샷을 사용) 복구를 최소 한 번은 테스트하세요. 복구할 수 없는 백업 파일은 의미가 없습니다.
모니터링: CPU, RAM, 디스크 사용량과 디스크 I/O를 추적하세요. 프로세스 상태와 로그 오류도 모니터링하세요. 최소한 서비스 중단이나 디스크 용량 부족 시에 경고가 가도록 하세요.
개발 환경을 넘어서면 항상 마스터 키로 Meilisearch를 실행하세요. 마스터 키는 시크릿 매니저나 암호화된 환경 변수 저장소에 보관하고(깃에 저장하지 않음), 평문 .env 파일에 커밋하지 마세요.
예제(Docker):
docker run -d --name meilisearch \\
-p 7700:7700 \\
-v meili_data:/meili_data \\
-e MEILI_MASTER_KEY="$(openssl rand -hex 32)" \\
getmeili/meilisearch:latest
또한 네트워크 규칙을 고려하세요: 프라이빗 인터페이스에 바인딩하거나 인바운드 접근을 제한해서 백엔드 서버만 Meilisearch에 접근하도록 하세요.
curl -s http://localhost:7700/version
Meilisearch 인덱싱은 비동기적입니다: 문서를 전송하면 Meilisearch가 작업을 큐에 넣고, 그 작업이 성공한 후에야 문서가 검색 가능해집니다. 인덱싱을 단일 요청으로 취급하지 말고 작업(job) 시스템으로 다루세요.
id).curl -X POST 'http://localhost:7700/indexes/products/documents?primaryKey=id' \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY' \\
--data-binary @products.json
taskUid가 포함됩니다. 그것이 succeeded(또는 failed)가 될 때까지 폴링하세요.curl -X GET 'http://localhost:7700/tasks/123' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY'
curl -X GET 'http://localhost:7700/indexes/products/stats' \\
-H 'Authorization: Bearer YOUR_WRITE_KEY'
카운트가 일치하지 않으면 추측하지 말고 먼저 작업 에러 세부사항을 확인하세요.
배칭은 작업을 예측 가능하고 복구 가능하게 유지하는 것입니다.
addDocuments는 **업서트(upsert)**로 동작합니다: 같은 기본 키가 있으면 업데이트하고, 없으면 삽입합니다. 정상 업데이트에는 이것을 사용하세요.
다음 경우 전체 재인덱스를 고려하세요:
삭제는 명시적으로 deleteDocument(s)를 호출하세요; 그렇지 않으면 오래된 레코드가 남아 있을 수 있습니다.
인덱싱은 재시도 가능해야 합니다. 핵심은 안정적인 문서 id입니다.
taskUid를 배치/작업 id와 함께 저장하고, 작업 상태에 따라 재시도하세요.프로덕션 데이터 이전에 실제 필드 구조와 일치하는 작은 데이터셋(200–500개)을 인덱싱하세요. 예: id, name, description, category, brand, price, inStock, createdAt이 포함된 products 세트. 이는 대량 임포트 없이 작업 흐름, 카운트, 업데이트/삭제 동작을 검증하는 데 충분합니다.
검색 “관련성”은 단순히: 무엇이 먼저 보이고 왜 그런가 하는 문제입니다. Meilisearch는 자체 스코어링 시스템을 만들 필요 없이 이를 조정할 수 있게 해줍니다.
두 가지 설정이 콘텐츠를 어떻게 취급할지 결정합니다:
searchableAttributes: 사용자가 입력한 쿼리를 Meilisearch가 어느 필드에서 찾을지(예: title, summary, tags). 순서가 중요합니다: 앞에 있는 필드일수록 더 중요하게 취급됩니다.displayedAttributes: 응답에 반환할 필드. 이는 개인정보 보호와 페이로드 크기에 영향을 줍니다 — 표시되지 않는 필드는 반환되지 않습니다.실용적 기본값은 몇 개의 신호가 강한 필드(제목, 핵심 텍스트)를 검색 대상으로 하고, UI가 필요로 하는 최소한의 표시 필드만 반환하는 것입니다.
Meilisearch는 랭킹 규칙(ranking rules)이라는 파이프라인으로 문서를 정렬합니다 — 일종의 우선순위 결정 체계입니다. 개념적으로는 다음을 선호합니다:
내부 작동 방식을 모두 외울 필요는 없습니다. 주로 어떤 필드가 중요한가와 언제 커스텀 정렬을 적용할지를 선택하면 됩니다.
목표: “제목 매치가 우선되어야 한다” → title을 맨 앞에 둡니다:
{
"searchableAttributes": ["title", "subtitle", "description", "tags"]
}
목표: “새 콘텐츠를 앞에 배치” → 정렬 규칙을 추가하고 쿼리 시 정렬하세요(또는 커스텀 랭킹 설정):
{
"sortableAttributes": ["publishedAt"],
"rankingRules": ["sort", "typo", "words", "proximity", "attribute", "exactness"]
}
그런 다음 요청 시:
{ "q": "release notes", "sort": ["publishedAt:desc"] }
목표: “인기 항목을 홍보” → popularity를 sortable로 만들고 필요할 때 정렬하세요.
사용자가 실제로 입력하는 쿼리 5–10개를 골라 변경 전 상위 결과를 저장한 뒤, 변경 후와 비교하세요.
예시:
"apple" → Apple Watch band, Pineapple slicer, Apple iPhone case"apple" → Apple iPhone case, Apple Watch band, Pineapple slicer“변경 후” 결과가 사용자 의도에 더 잘 맞으면 설정을 유지하세요. 예외 케이스에 해가 된다면 한 번에 한 가지씩(속성 순서, 그다음 정렬 규칙) 변경해 어떤 설정이 개선을 야기했는지 알 수 있게 하세요.
좋은 검색 창은 단순히 “단어 입력 → 결과”가 아닙니다. 사람들은 결과를 좁히고(“재고 있는 항목만”) 정렬(“가장 저렴한 것부터”)하고 싶어합니다. Meilisearch에서는 필터, 정렬, 패싯으로 이를 구현합니다.
필터는 결과 집합에 적용하는 규칙입니다. 패싯은 사용자가 그 규칙을 만들도록 돕는 UI 요소(보통 체크박스나 개수)입니다.
비기술적 예시:
예: 사용자는 "running"을 검색한 뒤 category = Shoes 및 status = in_stock으로 필터링할 수 있습니다. 패싯은 "Shoes (128)", "Jackets (42)"처럼 카운트를 보여 사용자가 어떤 선택지를 기대할 수 있는지 알게 해줍니다.
Meilisearch는 필터링과 정렬에 사용할 필드를 명시적으로 허용해야 합니다.
category, status, brand, price, created_at, tenant_id 등을 추가하세요(필터로 쓸 경우).price, rating, created_at, popularity 등을 추가하세요(정렬에 쓸 경우).항목을 좁게 유지하세요. 모든 필드를 filterable/sortable로 만들면 인덱스 크기가 늘어나고 업데이트가 느려질 수 있습니다.
50,000개의 매치가 있더라도 사용자는 첫 페이지만 봅니다. 작은 페이지(보통 20–50 결과)를 사용하고 limit을 합리적으로 설정하며 offset으로 페이지네이션하세요(또는 더 최신 페이지네이션 기능 사용). 또한 앱에서 최대 페이지 깊이를 제한해 비용이 큰 "400페이지" 요청을 방지하세요.
서버 사이드 검색을 깔끔하게 추가하는 방법은 Meilisearch를 백엔드 뒤의 전문화된 데이터 서비스로 취급하는 것입니다. 앱이 검색 요청을 받고 백엔드가 Meilisearch를 호출한 뒤 클라이언트에 가공된 응답을 반환합니다.
많은 팀이 다음 흐름을 사용합니다:
GET /api/search?q=wireless+headphones&limit=20).이 패턴은 Meilisearch를 교체 가능하게 만들고 프론트엔드 코드가 인덱스 내부에 의존하지 않도록 합니다.
새 앱을 만들거나 내부 도구를 재구축하는 중이고 이 패턴을 빠르게 구현하려면, React UI, Go 백엔드, PostgreSQL을 스캐폴딩하고 Meilisearch를 /api/search 뒤에 통합하는 플랫폼(예: Koder.ai)이 단축키가 될 수 있습니다.
Meilisearch는 클라이언트 사이드 쿼리를 지원하지만 백엔드 쿼리가 보통 더 안전합니다:
퍼블릭 데이터에는 제한된 키로 클라이언트 쿼리를 허용할 수 있지만, 사용자별 가시성 규칙이 있다면 반드시 서버를 통해 검색을 라우팅하세요.
검색 트래픽에는 반복이 많습니다("iphone case", "return policy" 등). API 레이어에 캐시를 추가하세요:
검색을 공개 엔드포인트로 취급하세요:
limit과 최대 쿼리 길이 설정Meilisearch는 종종 앱 뒤에 배치되며 민감한 비즈니스 데이터를 빠르게 반환할 수 있습니다. 데이터베이스처럼 잠그고 각 호출자가 볼 수 있는 것만 노출하세요.
Meilisearch에는 모든 작업을 할 수 있는 마스터 키가 있습니다: 인덱스 생성/삭제, 설정 업데이트, 문서 읽기/쓰기 등. 마스터 키는 서버 전용으로 유지하세요.
애플리케이션에는 작업과 인덱스를 제한한 API 키를 생성하세요. 일반 패턴:
최소 권한을 적용하면 키가 유출되더라도 데이터 삭제나 관련 없는 인덱스 접근이 불가능합니다.
여러 고객(테넌트)을 서비스하면 두 가지 주요 옵션이 있습니다:
1) 테넌트별 인덱스.
교차 테넌트 접근 위험이 낮고 이해하기 쉽지만 관리할 인덱스가 많아지고 설정 업데이트를 일관되게 적용해야 하는 단점이 있습니다.
2) 공유 인덱스 + tenantId 필터.
모든 문서에 tenantId 필드를 저장하고 모든 검색에 tenantId = "t_123" 필터를 요구하세요. 이 방식은 잘 확장될 수 있지만, 모든 요청에 필터가 항상 적용되도록 해야 합니다(이탈을 방지하려면 범위 제한 키를 사용하는 것이 이상적).
검색이 정확하더라도 의도치 않은 필드(이메일, 내부 메모, 원가 등)가 노출될 수 있습니다. 반환 가능한 속성을 안전한 허용 목록으로 구성하세요:
“최악의 경우” 테스트를 해보세요: 일반 용어로 검색해 민감 필드가 노출되지 않는지 확인하세요.
클라이언트 측에 키를 두어도 되는지 확신이 없으면 기본적으로 “아니오”로 가정하고 검색을 서버 사이드로 유지하세요.
Meilisearch는 **인덱싱(쓰기)**과 **쿼리(읽기)**라는 두 가지 워크로드를 염두에 두고 빠릅니다. 대부분의 성능 문제는 이 둘 중 하나가 CPU, RAM, 디스크를 경쟁할 때 발생합니다.
인덱싱 부하는 대량 배치 임포트, 잦은 업데이트, 많은 검색 필드 추가 시 급증합니다. 인덱싱은 백그라운드 작업이지만 CPU와 디스크 대역폭을 소비합니다. 작업 큐가 쌓이면 쿼리량이 변하지 않아도 검색이 느려질 수 있습니다.
쿼리 부하는 트래픽 증가뿐 아니라 기능(필터 수, 패싯, 큰 결과 집합, 높은 오타 허용)으로 인해 요청당 작업량이 늘어나면서 증가합니다.
디스크 I/O가 조용한 범인입니다. 느린 디스크(또는 공유 볼륨의 noisy neighbor)는 "인스턴트"를 "결국"으로 만들 수 있습니다. 프로덕션에서는 NVMe/SSD를 기본으로 권장합니다.
간단한 사이징에서 시작하세요: 인덱스를 메모리에 유지할 수 있는 충분한 RAM과 피크 QPS를 처리할 CPU를 주세요. 그런 다음 관심사를 분리하세요:
작은 신호 집합을 추적하세요:
백업은 일상적이어야 합니다. Meilisearch의 스냅샷 기능을 일정에 따라 사용하고, 스냅샷을 외부에 저장하며 주기적으로 복구 테스트를 하세요. 업그레이드는 릴리스 노트를 읽고 비프로덕션 환경에서 스테이징 후 진행하세요. 버전 변경이 인덱싱 동작에 영향을 주면 재인덱싱 시간 계획을 포함하세요.
이미 플랫폼 스냅샷/롤백 워크플로(예: Koder.ai의 스냅샷/롤백)를 사용 중이라면 검색 롤아웃을 동일한 규율에 맞추세요: 변경 전 스냅샷 찍기, 헬스체크 검증, 빠른 복귀 경로 확보.
깔끔한 통합을 했더라도 검색 문제는 반복되는 몇 가지 범주로 귀결됩니다. 좋은 소식은 Meilisearch가 작업, 로그, 결정적인 설정을 제공해 체계적으로 디버그할 수 있게 한다는 점입니다.
filterableAttributes에 추가되지 않았거나 문서가 예상과 다른 형태(문자열 vs 배열 vs 중첩 객체)로 저장됨sortableAttributes/rankingRules 설정 문제먼저 Meilisearch가 마지막 변경을 성공적으로 적용했는지 확인하세요.
filter, 그다음 sort, 그다음 facets설명을 못 하겠는 결과가 있다면 구성(동의어, 랭킹 규칙)을 임시로 줄이고 작은 데이터셋(예: 50개 문서)에서 테스트하세요. 복잡한 관련성 문제는 5백만 건 대신 50건에서 훨씬 더 쉽게 진단됩니다.
your_index_v2를 병렬로 만들고 설정을 적용한 뒤 생산 쿼리 샘플을 재생성filterableAttributes와 sortableAttributes가 UI 요구와 일치하는지 확인Related guides: /blog (search reliability, indexing patterns, and production rollout tips).
서버 사이드 검색은 쿼리가 브라우저가 아닌 백엔드(또는 전용 검색 서비스)에서 실행된다는 의미입니다. 다음과 같은 경우 서버 사이드 검색을 선택하세요:
사용자가 즉시 알아채는 네 가지 포인트가 있습니다:
이 중 하나라도 빠지면 사용자는 쿼리를 다시 입력하거나 스크롤을 더 하거나 검색을 포기합니다.
Meilisearch는 검색 인덱스로 보아야 하며, 진짜 원본 데이터베이스를 대체하지 않습니다. 데이터베이스는 쓰기, 트랜잭션, 제약을 담당하고, Meilisearch는 검색을 빠르게 하기 위해 선택한 필드의 복사본을 저장합니다.
유용한 사고 모델:
기본 권장은 엔터티 타입별로 하나의 인덱스입니다(예: products, articles). 이렇게 하면:
만약 “모두 검색”이 필요하면 여러 인덱스를 조회해서 백엔드에서 결과를 병합하거나, 나중에 전용 글로벌 인덱스를 추가하세요.
다음 조건을 만족하는 기본 키를 고르세요:
id, sku, slug)안정적인 ID는 인덱싱을 멱등하게 만들어 재시도 시 중복 생성이 일어나지 않게 합니다.
각 필드를 목적에 따라 분류하세요:
이렇게 명확히 하면 과도한 인덱싱을 피할 수 있고, 노이즈가 줄며 인덱스가 비대해지는 것을 막습니다.
인덱싱은 비동기적입니다: 문서를 업로드하면 작업(task)이 생성되고, 그 작업이 성공해야만 문서가 검색 가능해집니다.
안전한 흐름은:
succeeded 또는 failed가 될 때까지 폴링결과가 오래된 것처럼 보이면 먼저 작업 상태를 확인하세요.
하나의 거대한 업로드보다 여러 개의 작은 배치가 안전합니다. 권장 시작점:
작은 배치는 재시도하기 쉽고, 문제 레코드를 찾기 쉬우며 타임아웃 가능성이 낮습니다.
관련성을 개선하는 데 효과적인 두 가지 레버는 다음과 같습니다:
searchableAttributes: 어떤 필드를 검색할지, 그리고 우선순위publishedAt, price, popularity 같은 필드로 정렬할지 여부실무적으로는 실제 사용자 쿼리 5–10개를 골라 현재 결과를 저장한 뒤, 한 가지 설정을 바꾸고 비교해 보세요.
대부분의 필터/정렬 문제는 설정 누락에서 옵니다:
filterableAttributes**에 포함되어야 합니다sortableAttributes**에 포함되어야 합니다또한 문서 내 필드 형태(문자열 vs 배열 vs 중첩 객체)를 확인하세요. 필터가 실패하면 마지막 설정 작업/태스크 상태를 확인하고 문서가 기대한 값을 실제로 가지고 있는지 검증하세요.