[G1-Sync] Manual knowledge update

2026-05-09 21:08:02 +09:00
parent f0befc887a
commit 93ec7e9056
363 changed files with 68333 additions and 64 deletions
@@ -0,0 +1,189 @@
+---
+id: db-full-text-search
+title: Full-text Search — Postgres / Elasticsearch / Meilisearch
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [database, search, postgres, elasticsearch, vibe-coding]
+tech_stack: { language: "SQL / TS", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [full-text search, FTS, tsvector, GIN, Meilisearch, Typesense, OpenSearch]
+---
+
+# Full-text Search
+
+> "맥북" 검색 = "macbook" 도 매치. **언어별 stemming + ranking**. Postgres FTS = 가벼운 시작, Meilisearch/Typesense = 빠른 typo, Elasticsearch/OpenSearch = 큰 규모.
+
+## 📖 핵심 개념
+- Tokenize: "맥북 m1" → ["맥북", "m1"].
+- Stemming: "running" → "run".
+- Ranking: BM25 / TF-IDF.
+- Faceting: 카테고리 / 가격대 필터 + 검색.
+
+## 💻 코드 패턴
+
+### Postgres FTS — 시작
+```sql
+ALTER TABLE products ADD COLUMN tsv tsvector
+  GENERATED ALWAYS AS (
+    setweight(to_tsvector('simple', coalesce(name, '')), 'A') ||
+    setweight(to_tsvector('simple', coalesce(description, '')), 'B')
+  ) STORED;
+
+CREATE INDEX products_tsv ON products USING GIN(tsv);
+```
+
+```sql
+-- 검색
+SELECT id, name,
+       ts_rank(tsv, query) AS rank
+FROM products, plainto_tsquery('simple', 'macbook m1') query
+WHERE tsv @@ query
+ORDER BY rank DESC
+LIMIT 20;
+```
+
+### 한국어 (pg_search 확장 필요)
+```sql
+-- 또는 trigram (n-gram 비슷)
+CREATE EXTENSION pg_trgm;
+CREATE INDEX products_name_trgm ON products USING GIN (name gin_trgm_ops);
+
+SELECT * FROM products WHERE name % '맥북' ORDER BY similarity(name, '맥북') DESC;
+```
+
+### Meilisearch (typo + ranking 자동)
+```ts
+import { MeiliSearch } from 'meilisearch';
+
+const ms = new MeiliSearch({ host: 'http://meilisearch:7700', apiKey: '...' });
+const idx = ms.index('products');
+
+// 인덱싱
+await idx.addDocuments([{ id: '1', name: 'MacBook M1', price: 1000, category: 'laptop' }]);
+await idx.updateSettings({
+  searchableAttributes: ['name', 'description'],
+  filterableAttributes: ['category', 'price'],
+  rankingRules: ['words', 'typo', 'proximity', 'attribute', 'sort', 'exactness'],
+});
+
+// 검색
+const r = await idx.search('macboo', { // typo OK
+  filter: 'category = "laptop" AND price < 2000',
+  limit: 20,
+  attributesToHighlight: ['name'],
+});
+```
+
+### Elasticsearch
+```ts
+import { Client } from '@elastic/elasticsearch';
+
+const es = new Client({ node: 'http://elasticsearch:9200' });
+
+// 매핑
+await es.indices.create({
+  index: 'products',
+  body: {
+    mappings: {
+      properties: {
+        name:        { type: 'text', analyzer: 'standard' },
+        description: { type: 'text' },
+        price:       { type: 'float' },
+        category:    { type: 'keyword' },
+      },
+    },
+  },
+});
+
+// 검색
+const r = await es.search({
+  index: 'products',
+  query: {
+    bool: {
+      must: [{ multi_match: { query: 'macbook', fields: ['name^3', 'description'] } }],
+      filter: [{ term: { category: 'laptop' } }, { range: { price: { lt: 2000 } } }],
+    },
+  },
+  highlight: { fields: { name: {} } },
+  size: 20,
+});
+```
+
+### Hybrid (vector + keyword)
+```sql
+-- pgvector + FTS 결합
+WITH v_hits AS (
+  SELECT id, 1 - (embedding <=> $1::vector) AS v_score
+  FROM products ORDER BY embedding <=> $1::vector LIMIT 100
+),
+t_hits AS (
+  SELECT id, ts_rank(tsv, plainto_tsquery($2)) AS t_score
+  FROM products WHERE tsv @@ plainto_tsquery($2) LIMIT 100
+)
+SELECT id, COALESCE(v_score, 0) * 0.6 + COALESCE(t_score, 0) * 0.4 AS score
+FROM v_hits FULL OUTER JOIN t_hits USING (id)
+ORDER BY score DESC LIMIT 20;
+```
+
+### Faceting
+```ts
+// Meilisearch
+const r = await idx.search('macbook', {
+  facets: ['category', 'price_range'],
+});
+// r.facetDistribution: { category: { laptop: 50, desktop: 5 } }
+```
+
+### Suggest / autocomplete
+```ts
+// Meilisearch: prefix 자동
+await idx.search('mac', { limit: 5 });
+
+// Elasticsearch: completion suggester 또는 edge ngram
+```
+
+### Sync (DB → 검색 엔진)
+```ts
+// CDC 또는 outbox 로 변경 → 검색 인덱스 업데이트
+on('product.changed', async (p) => {
+  await idx.addDocuments([p]); // upsert
+});
+on('product.deleted', async (id) => {
+  await idx.deleteDocument(id);
+});
+```
+
+## 🤔 의사결정 기준
+| 규모 | 추천 |
+|---|---|
+| <1M docs, simple | Postgres FTS |
+| Typo 강함 | Meilisearch / Typesense |
+| 대규모 + 분석 + 복잡 | Elasticsearch / OpenSearch |
+| Hybrid (semantic + keyword) | pgvector + FTS / Vespa |
+| Code search | Sourcegraph / Algolia |
+| 사용자별 권한 + 검색 | per-user filter |
+
+## ❌ 안티패턴
+- **`LIKE '%query%'`**: 인덱스 안 탐. 느림.
+- **GIN 인덱스 없이 tsvector**: 같은 결과지만 느림.
+- **Regex 검색 prod**: pre-compute 가 답.
+- **모든 컬럼 인덱싱**: 인덱스 크기. searchable 필드 명시.
+- **Stemming 없는 영어**: "runs" 검색이 "running" 못 찾음.
+- **단순 prefix only**: typo 무시.
+- **App-level dedup**: 검색 엔진의 ranking 가 나음.
+- **Sync 비동기 lag 무시**: search 결과가 stale.
+
+## 🤖 LLM 활용 힌트
+- 작은 = pg FTS / pg_trgm.
+- typo 강 = Meilisearch.
+- 큰 = Elasticsearch.
+- Hybrid = pgvector + FTS rerank.
+
+## 🔗 관련 문서
+- [[AI_RAG_Pattern_Basics]]
+- [[DB_JSONB_Postgres_Patterns]]
+- [[DB_Change_Data_Capture]]