{"title":"FTS5 전문 검색","slug":"fts5-search","category":"concepts","summary":"Synapse가 서브밀리초 전문 메모리 검색을 위해 SQLite FTS5를 사용하는 방법.","audience":["human","llm"],"tags":["concept","search","fts5","fulltext"],"difficulty":"advanced","updated":"2026-06-27","word_count":525,"read_minutes":3,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# FTS5 전문 검색\n\nSynapse는 빠르고 유연한 메모리 검색을 위해 FTS5 (Full-Text Search 5)를\n사용합니다. 이 페이지에서는 작동 방식과 효과적인 사용법을 설명합니다.\n\n## FTS5란?\n\nFTS5는 전문 검색 기능을 제공하는 SQLite 확장입니다 (확장을 통해\nPostgreSQL에서도 사용 가능). 다음을 제공합니다:\n\n- 빠른 키워드 검색을 위한 텍스트 콘텐츠 인덱싱\n- 불린 연산자 (AND, OR, NOT) 지원\n- 따옴표를 사용한 구문 매칭 지원\n- `*`를 사용한 접두사 매칭 지원\n- 관련성으로 결과 순위 지정\n\nSynapse는 FTS5를 사용하여 모든 메모리 콘텐츠를 인덱싱하여 수천 개의\n메모리에서 서브밀리초 검색을 가능하게 합니다.\n\n## Synapse의 FTS5 사용 방식\n\n`POST /memory` 시:\n\n1. 메모리 콘텐츠가 `memories` 테이블에 저장됩니다\n2. 콘텐츠가 FTS5 가상 테이블에도 삽입됩니다\n3. FTS5가 자동으로 토큰화하고 인덱싱합니다\n\n`GET /memory/search?q=...` 시:\n\n1. Synapse가 FTS5 구문을 사용하여 쿼리를 파싱합니다\n2. FTS5 인덱스에 대해 `MATCH`를 실행합니다\n3. `mind_id`로 필터링합니다 (테넌트 격리)\n4. 순위가 지정된 결과를 반환합니다\n\n## 쿼리 구문\n\n### 단순 키워드 검색\n\n```\n?q=docker\n```\n\n\"docker\"를 포함하는 메모리를 반환합니다.\n\n### 여러 키워드 (암시적 AND)\n\n```\n?q=docker+swarm\n?q=docker%20swarm\n```\n\n\"docker\"와 \"swarm\" 모두를 포함하는 메모리를 반환합니다.\n\n### 구문 매칭\n\n```\n?q=\"docker+swarm\"\n?q=%22docker%20swarm%22\n```\n\n정확한 구문 \"docker swarm\"을 포함하는 메모리를 반환합니다.\n\n### 접두사 매칭\n\n```\n?q=docker*\n```\n\n\"docker\"로 시작하는 단어 (예: \"dockers\", \"dockerfile\", \"dockerize\")를\n포함하는 메모리를 반환합니다.\n\n### 불린 OR\n\n```\n?q=docker+OR+kubernetes\n```\n\n\"docker\" 또는 \"kubernetes\"를 포함하는 메모리를 반환합니다.\n\n### 불린 NOT\n\n```\n?q=docker+-swarm\n?q=docker+NOT+swarm\n```\n\n\"docker\"를 포함하지만 \"swarm\"은 포함하지 않는 메모리를 반환합니다.\n\n### 그룹화\n\n```\n?q=(docker+OR+kubernetes)+-test\n```\n\n\"docker\" 또는 \"kubernetes\"를 포함하지만 \"test\"는 포함하지 않는 메모리를\n반환합니다.\n\n## 실용적인 예시\n\n### 프로젝트에 대한 메모리 찾기\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=synapse+deployment\"\n```\n\n### 정확한 구문 찾기\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22\"\n```\n\n### 테스트 메모리 제외\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=production+-test\"\n```\n\n### 기술로 찾기\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql\"\n```\n\n## 순위\n\nFTS5는 BM25 알고리즘을 사용하여 관련성으로 결과 순위를 지정합니다. 요인:\n\n- 용어 빈도 (용어가 얼마나 자주 등장하는가)\n- 역문서 빈도 (희귀한 용어가 더 높은 순위)\n- 문서 길이 (용어가 포함된 더 짧은 문서가 더 높은 순위)\n- 컬럼 가중치 (title > content)\n\n결과는 순위순으로 반환됩니다 (가장 관련성 높은 것이 먼저).\n\n## 성능\n\n| 작업 | 지연 시간 |\n|-----------|---------|\n| 100개 메모리 검색 | < 5ms |\n| 1,000개 메모리 검색 | < 10ms |\n| 10,000개 메모리 검색 | < 25ms |\n| 100,000개 메모리 검색 | < 100ms |\n\nFTS5는 읽기 중심의 워크로드에 고도로 최적화되어 있습니다.\n\n## 제한 사항\n\n### 어간 추출\n\nFTS5는 기본적으로 어간 추출을 하지 않습니다. \"running\"과 \"run\"은 다른\n용어입니다.\n\n**해결 방법:** 접두사 매칭 사용: `?q=run*`\n\n### 오타 허용\n\nFTS5는 퍼지 매칭을 지원하지 않습니다. 오타는 결과를 반환하지 않습니다.\n\n**해결 방법:** 개념 매칭을 위해 의미론적 검색\n(`/memory/semantic-search`)을 사용하십시오.\n\n### 불용어\n\n일반적인 단어 (the, a, an, is)는 인덱싱되지만 검색에 유용하지 않을 수\n있습니다. FTS5는 이를 자동으로 처리합니다.\n\n## FTS5와 의미론적 검색 비교\n\n| 측면 | FTS5 | 의미론적 검색 |\n|--------|------|-----------------|\n| 속도 | 서브밀리초 | 50-100ms |\n| 매칭 | 정확한 키워드 | 개념적 |\n| 오타 허용 | 없음 | 약간 |\n| 어간 추출 | 없음 | 암시적 |\n| 임베딩 필요 | 아니오 | 예 |\n| 적합한 용도 | 특정 용어 | 개념 |\n\n키워드를 알 때 FTS5를 사용하십시오. X가 다르게 설명된 \"X에 대한 메모리\"를\n원할 때 의미론적 검색을 사용하십시오.\n\n## 모범 사례\n\n> [!TIP]\n> - **구체적인 용어 사용** — \"container orchestration\"보다 \"docker swarm\"이 낫습니다\n> - **구문 인용** — `\"docker swarm\"`은 구문 매칭을 보장합니다\n> - **변형을 위해 접두사 사용** — `deploy*`는 \"deploy\", \"deployment\", \"deploying\"을 잡습니다\n> - **노이즈 제외** — `-test`는 테스트 메모리를 필터링합니다\n> - **태그와 결합** — `?q=docker&tag=production`이 결과를 좁힙니다\n\n## 다음 단계\n\n- [의미론적 검색](/docs/concepts/semantic-search)\n- [Memory API](/docs/api/memory)\n- [메모리 모범 사례](/docs/guides/memory-best-practices)\n","content_html":"

FTS5 전문 검색

\n

Synapse는 빠르고 유연한 메모리 검색을 위해 FTS5 (Full-Text Search 5)를\n사용합니다. 이 페이지에서는 작동 방식과 효과적인 사용법을 설명합니다.

\n

FTS5란?

\n

FTS5는 전문 검색 기능을 제공하는 SQLite 확장입니다 (확장을 통해\nPostgreSQL에서도 사용 가능). 다음을 제공합니다:

\n\n

Synapse는 FTS5를 사용하여 모든 메모리 콘텐츠를 인덱싱하여 수천 개의\n메모리에서 서브밀리초 검색을 가능하게 합니다.

\n

Synapse의 FTS5 사용 방식

\n

POST /memory 시:

\n
    \n
  1. 메모리 콘텐츠가 memories 테이블에 저장됩니다
    2. \n
  2. 콘텐츠가 FTS5 가상 테이블에도 삽입됩니다
    3. \n
  3. FTS5가 자동으로 토큰화하고 인덱싱합니다
    4. \n
\n

GET /memory/search?q=... 시:

\n
    \n
  1. Synapse가 FTS5 구문을 사용하여 쿼리를 파싱합니다
    2. \n
  2. FTS5 인덱스에 대해 MATCH를 실행합니다
    3. \n
  3. mind_id로 필터링합니다 (테넌트 격리)
    4. \n
  4. 순위가 지정된 결과를 반환합니다
    5. \n
\n

쿼리 구문

\n

단순 키워드 검색

\n
?q=docker

"docker"를 포함하는 메모리를 반환합니다.

\n

여러 키워드 (암시적 AND)

\n
?q=docker+swarm\n?q=docker%20swarm

"docker"와 "swarm" 모두를 포함하는 메모리를 반환합니다.

\n

구문 매칭

\n
?q="docker+swarm"\n?q=%22docker%20swarm%22

정확한 구문 "docker swarm"을 포함하는 메모리를 반환합니다.

\n

접두사 매칭

\n
?q=docker*

"docker"로 시작하는 단어 (예: "dockers", "dockerfile", "dockerize")를\n포함하는 메모리를 반환합니다.

\n

불린 OR

\n
?q=docker+OR+kubernetes

"docker" 또는 "kubernetes"를 포함하는 메모리를 반환합니다.

\n

불린 NOT

\n
?q=docker+-swarm\n?q=docker+NOT+swarm

"docker"를 포함하지만 "swarm"은 포함하지 않는 메모리를 반환합니다.

\n

그룹화

\n
?q=(docker+OR+kubernetes)+-test

"docker" 또는 "kubernetes"를 포함하지만 "test"는 포함하지 않는 메모리를\n반환합니다.

\n

실용적인 예시

\n

프로젝트에 대한 메모리 찾기

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"

정확한 구문 찾기

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"

테스트 메모리 제외

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=production+-test"

기술로 찾기

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"

순위

\n

FTS5는 BM25 알고리즘을 사용하여 관련성으로 결과 순위를 지정합니다. 요인:

\n\n

결과는 순위순으로 반환됩니다 (가장 관련성 높은 것이 먼저).

\n

성능

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
작업지연 시간
100개 메모리 검색< 5ms
1,000개 메모리 검색< 10ms
10,000개 메모리 검색< 25ms
100,000개 메모리 검색< 100ms
\n

FTS5는 읽기 중심의 워크로드에 고도로 최적화되어 있습니다.

\n

제한 사항

\n

어간 추출

\n

FTS5는 기본적으로 어간 추출을 하지 않습니다. "running"과 "run"은 다른\n용어입니다.

\n

해결 방법: 접두사 매칭 사용: ?q=run*

\n

오타 허용

\n

FTS5는 퍼지 매칭을 지원하지 않습니다. 오타는 결과를 반환하지 않습니다.

\n

해결 방법: 개념 매칭을 위해 의미론적 검색\n(/memory/semantic-search)을 사용하십시오.

\n

불용어

\n

일반적인 단어 (the, a, an, is)는 인덱싱되지만 검색에 유용하지 않을 수\n있습니다. FTS5는 이를 자동으로 처리합니다.

\n

FTS5와 의미론적 검색 비교

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
측면FTS5의미론적 검색
속도서브밀리초50-100ms
매칭정확한 키워드개념적
오타 허용없음약간
어간 추출없음암시적
임베딩 필요아니오예
적합한 용도특정 용어개념
\n

키워드를 알 때 FTS5를 사용하십시오. X가 다르게 설명된 "X에 대한 메모리"를\n원할 때 의미론적 검색을 사용하십시오.

\n

모범 사례

\n

다음 단계

\n\n","urls":{"html":"/docs/concepts/fts5-search","text":"/docs/concepts/fts5-search?format=text","json":"/docs/concepts/fts5-search?format=json","llm":"/docs/concepts/fts5-search?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}