Meilisearch 실전 튜토리얼 — Docker 설치부터 Node.js SDK·필터·랭킹·Next.js 연동까지

docker run — 메이리서치 즉시 실행
# 데이터 디렉터리 준비 후 컨테이너 실행
mkdir -p ./meili_data

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -v "$(pwd)/meili_data:/meili_data" \
  -e MEILI_ENV=development \
  -e MEILI_MASTER_KEY='dev-master-key-change-me-32chars!!' \
  getmeili/meilisearch:v1.11

# 헬스 체크
curl -s http://127.0.0.1:7700/health
# 기대 응답: {"status":"available"}

docker-compose.yml — 로컬 개발 환경
services:
  meilisearch:
    image: getmeili/meilisearch:v1.11
    ports:
      - "7700:7700"
    environment:
      MEILI_ENV: development
      MEILI_MASTER_KEY: dev-master-key-change-me-32chars!!
      MEILI_NO_ANALYTICS: "true"
    volumes:
      - ./meili_data:/meili_data
    restart: unless-stopped

curl — 인덱스 생성과 문서 업로드
export MEILI_HOST=http://127.0.0.1:7700
export MEILI_KEY='dev-master-key-change-me-32chars!!'

# 1) 인덱스 생성 (primaryKey: id)
curl -s -X POST "$MEILI_HOST/indexes" \
  -H "Authorization: Bearer $MEILI_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{"uid":"products","primaryKey":"id"}'

# 2) 문서 업로드 (비동기 task)
curl -s -X POST "$MEILI_HOST/indexes/products/documents" \
  -H "Authorization: Bearer $MEILI_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '[
    {"id":1,"name":"울트라북 14","brand":"Acme","price":1290000,"category":"laptop","stock":12},
    {"id":2,"name":"기계식 키보드","brand":"KeyLab","price":189000,"category":"peripheral","stock":40},
    {"id":3,"name":"27인치 모니터","brand":"ViewMax","price":420000,"category":"display","stock":8}
  ]'

# 3) 간단한 검색
curl -s -X POST "$MEILI_HOST/indexes/products/search" \
  -H "Authorization: Bearer $MEILI_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{"q":"노트북"}'

npm 설치 및 클라이언트 초기화
npm install meilisearch

# lib/meili.js
import { MeiliSearch } from 'meilisearch'

const host = process.env.MEILI_HOST || 'http://127.0.0.1:7700'
const apiKey = process.env.MEILI_MASTER_KEY

if (!apiKey) {
  throw new Error('MEILI_MASTER_KEY is required')
}

export const meili = new MeiliSearch({ host, apiKey })
export const productsIndex = meili.index('products')

문서 동기화 헬퍼 — DB 변경 후 인덱스 반영
// lib/sync-product.js
import { productsIndex } from './meili.js'

/**
 * 상품 생성·수정 후 호출. 삭제 시 deleteDocument(id).
 * 실패해도 주문 플로우는 막지 말고, 재시도 큐에 넣는 편이 안전하다.
 */
export async function upsertProductDocument(product) {
  const doc = {
    id: product.id,
    name: product.name,
    brand: product.brand,
    price: product.price,
    category: product.category,
    stock: product.stock,
    description: product.description || '',
    updatedAt: product.updatedAt || Date.now(),
  }

  const task = await productsIndex.addDocuments([doc])
  return task // { taskUid, status, ... }
}

export async function removeProductDocument(id) {
  return productsIndex.deleteDocument(id)
}

인덱스 설정 + 필터 검색 예시
import { productsIndex } from './meili.js'

// 1) 한 번만 설정 (배포 스크립트 또는 마이그레이션)
await productsIndex.updateSettings({
  searchableAttributes: ['name', 'brand', 'description'],
  filterableAttributes: ['category', 'brand', 'price', 'stock'],
  sortableAttributes: ['price', 'stock', 'updatedAt'],
  displayedAttributes: ['id', 'name', 'brand', 'price', 'category', 'stock'],
})

// 2) 검색 API
export async function searchProducts({ q, category, maxPrice, page = 1 }) {
  const limit = 20
  const offset = (page - 1) * limit
  const filters = []
  if (category) filters.push(`category = "${category}"`)
  if (typeof maxPrice === 'number') filters.push(`price <= ${maxPrice}`)

  const result = await productsIndex.search(q || '', {
    filter: filters.length ? filters.join(' AND ') : undefined,
    sort: ['price:asc'],
    limit,
    offset,
    attributesToHighlight: ['name', 'description'],
  })

  return {
    hits: result.hits,
    estimatedTotalHits: result.estimatedTotalHits,
    processingTimeMs: result.processingTimeMs,
  }
}

동의어·랭킹 규칙 업데이트
import { productsIndex } from './meili.js'

await productsIndex.updateSettings({
  synonyms: {
    노트북: ['울트라북', '랩탑', 'laptop', 'notebook'],
    키보드: ['keyboard', '기계식'],
  },
  // 왼쪽일수록 우선순위 높음. 기본 규칙을 복사한 뒤 커스텀 필드를 끼운다.
  rankingRules: [
    'words',
    'typo',
    'proximity',
    'attribute',
    'sort',
    'exactness',
    'stock:desc', // 재고 많은 상품 우선 (예시)
  ],
  typoTolerance: {
    enabled: true,
    minWordSizeForTypos: {
      oneTypo: 4,
      twoTypos: 8,
    },
  },
  stopWords: ['및', '의', '를', '을', 'the', 'a'],
})

app/api/search/route.js — 서버 프록시 검색
import { NextResponse } from 'next/server'
import { productsIndex } from '@/lib/meili'

export async function GET(request) {
  const { searchParams } = new URL(request.url)
  const q = (searchParams.get('q') || '').slice(0, 80)
  const category = searchParams.get('category')
  const page = Math.max(1, Number(searchParams.get('page') || 1))

  const filters = []
  if (category) {
    // 단순 화이트리스트 검증 예시
    const allowed = new Set(['laptop', 'peripheral', 'display'])
    if (!allowed.has(category)) {
      return NextResponse.json({ error: 'invalid category' }, { status: 400 })
    }
    filters.push(`category = "${category}"`)
  }

  const result = await productsIndex.search(q, {
    filter: filters.length ? filters.join(' AND ') : undefined,
    limit: 20,
    offset: (page - 1) * 20,
    attributesToHighlight: ['name'],
  })

  return NextResponse.json({
    hits: result.hits,
    estimatedTotalHits: result.estimatedTotalHits,
    processingTimeMs: result.processingTimeMs,
  })
}

클라이언트 — 디바운스 검색 호출
// components/ProductSearch.jsx (요약)
'use client'
import { useEffect, useState } from 'react'

export function ProductSearch() {
  const [q, setQ] = useState('')
  const [hits, setHits] = useState([])

  useEffect(() => {
    const t = setTimeout(async () => {
      const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`)
      const data = await res.json()
      setHits(data.hits || [])
    }, 200) // 200ms 디바운스
    return () => clearTimeout(t)
  }, [q])

  return (
    <div>
      <input
        value={q}
        onChange={(e) => setQ(e.target.value)}
        placeholder="상품 검색"
        aria-label="상품 검색"
      />
      <ul>
        {hits.map((h) => (
          <li key={h.id}>{h.name} — {h.price.toLocaleString()}원</li>
        ))}
      </ul>
    </div>
  )
}

검색 전용 API 키 생성
curl -s -X POST "http://127.0.0.1:7700/keys" \
  -H "Authorization: Bearer $MEILI_KEY" \
  -H "Content-Type: application/json" \
  --data-binary '{
    "name": "search-only",
    "description": "Next.js API route search proxy",
    "actions": ["search"],
    "indexes": ["products"],
    "expiresAt": null
  }'