공식 문서에서 본 Typesense
개요
이 스킬은 Typesense 문서에서 자주 실수하기 쉬운 내용을 담고 있습니다: RAM을 소모하는 요소, HTTP 200 뒤에 실패를 숨기는 가져오기 결과, 필터 우선순위, 결과를 느슨하게 만드는 기본값, 스코프 검색 키 누수, 하이브리드 검색 가중치, v30에서 동의어 집합과 큐레이션 집합으로의 전환 등입니다. 일반적인 검색 및 데이터베이스 조언은 제외했습니다. 모든 주장에는 출처 문서 URL이 포함되어 있습니다.
지원 버전
Typesense Server 30.2이며, 코드 샘플은 JavaScript 클라이언트를 사용합니다. 서버 플래그는 자체 호스팅 서버에 적용됩니다. Typesense Cloud는 이를 관리합니다. 이전 서버용으로 작성된 코드를 검토하기 전에 아래 "이전 패턴"을 읽으십시오.
탐색 방법
- 아래 빠른 시작을 읽으십시오. 대부분의 작업에서 중요한 규칙을 다룹니다.
- 작업 주제와 일치하는 하나의 참조 파일을 마지막 표에서 열어 읽으십시오. 각 파일은 독립적으로 구성되어 있습니다.
- 각 주장은 출처 URL로 끝납니다. 세부 사항이 결과를 좌우할 때는 해당 URL을 다시 열어 확인하십시오.
빠른 시작
스키마 및 메모리
- 스키마의 모든 필드는 RAM에 인덱싱됩니다. 표시 전용 필드는 스키마에 포함하지 않거나(여전히 저장 및 반환됨)
index: false로 설정하십시오..*자동 감지보다는 미리 정의된 스키마를 선호하십시오. https://typesense.org/docs/30.2/api/collections.html 및 https://typesense.org/docs/guide/running-in-production.html - 날짜 타입 없음: Unix 타임스탬프는
int64로 저장하십시오.geopoint는[lat, lng]이며 GeoJSON 순서를 사용하지 마십시오. https://typesense.org/docs/30.2/api/collections.html 및 https://typesense.org/docs/30.2/api/geosearch.html facet: true는facet_by및group_by에 필요합니다. 문자열 정렬에는sort: true가 필요합니다. https://typesense.org/docs/30.2/api/search.html- alter는 해당 컬렉션에 대한 모든 쓰기를 차단합니다. 스키마 변경 기본 방법: 새 버전의 컬렉션을 만들고, 재인덱싱한 후, 앱이 항상 사용하는 별칭을 다시 가리키십시오. https://typesense.org/docs/30.2/api/collections.html
- 특수 문자는 제거되고 일치는 접두사 전용입니다: SKU, 이메일 및 URL에는
token_separators가 필요합니다. https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html
데이터 쓰기
- 기본값:
action: 'upsert'를 사용한 가져오기(JSONL).upsert는 전체 문서를 대체하고,emplace또는update는 부분 문서를 처리합니다. https://typesense.org/docs/30.2/api/documents.html - 가져오기는 항상 HTTP 200으로 응답합니다. 모든 결과 줄에서
success: false를 확인하고,return_id=true를 사용하십시오. https://typesense.org/docs/30.2/api/documents.html 및 https://typesense.org/docs/guide/faqs.html - 고유한 문자열
id를 설정하십시오. 가져오기에 최소 5분(동기화 가이드에 따르면 대규모 배치의 경우 최대 60분)의 클라이언트 타임아웃을 설정하고, 아직 실행 중인 쓰기를 재시도하지 마십시오. https://typesense.org/docs/30.2/api/documents.html 및 https://typesense.org/docs/guide/syncing-data-into-typesense.html 503 Not Ready or Lagging은 쓰기 역압력입니다: 배치 쓰기, CPU 추가, 지터를 사용한 재시도. https://typesense.org/docs/guide/syncing-data-into-typesense.html
검색
filter_by에는 콜론이 필요합니다:price:>=100.:는 단어를 일치시키고,:=는 전체 값을 일치시킵니다.&&와||는 우선순위가 동일하므로 괄호를 추가하십시오. 백틱은 쉼표나 괄호가 있는 값을 이스케이프합니다. https://typesense.org/docs/guide/tips-for-filtering.htmlobject[]내의 동일 객체 조건:ingredients.{name:=cheese && concentration:<50}. https://typesense.org/docs/guide/tips-for-filtering.htmldrop_tokens_threshold와typo_tokens_threshold의 기본값은 1이므로, 적중 수가 적은 쿼리는 자동으로 단어를 삭제하거나 오타를 추가합니다. 모든 단어를 강제하려면drop_tokens_threshold: 0을 사용하십시오. 오타를 비활성화하려면num_typos: 0ANDtypo_tokens_threshold: 0을 사용하십시오. https://typesense.org/docs/guide/ranking-and-relevance.htmlmax_candidates의 기본값은 4입니다. 짧은 쿼리는 이 값을 높이거나 인기default_sorting_field를 설정하지 않으면 레코드를 놓칠 수 있습니다. https://typesense.org/docs/30.2/api/search.html- 관련성과 인기도 혼합:
_text_match(buckets: 10):desc,popularity:desc. 필터링 없이 부스팅:_eval(in_stock:true):desc. https://typesense.org/docs/guide/ranking-and-relevance.html - 페이지당 최대 250개 적중.
group_by는grouped_hits와 근사치found를 반환합니다. https://typesense.org/docs/30.2/api/search.html union: true멀티 검색은 검색별 페이지네이션을 무시하고 동일한 정렬 필드 타입이 필요합니다. https://typesense.org/docs/30.2/api/federated-multi-search.html
벡터 및 AI 검색
- 벡터 쿼리는
multi_search를 통해 이루어지며, 항상 벡터 필드에exclude_fields를 사용하십시오.k또는distance_threshold로 결과를 제한하십시오. https://typesense.org/docs/30.2/api/vector-search.html - 하이브리드:
query_by: 'title,embedding'. 퓨전은 키워드 0.7과 벡터 0.3이며,vector_query의alpha는 VECTOR 가중치입니다.query_by_weights에는 임베딩 필드에 대한 자리 표시자0이 필요합니다. https://typesense.org/docs/30.2/api/vector-search.html - RAG:
exclude_fields: 'embedding'와 함께conversation=true, 또는 원시 부동 소수점이 LLM 컨텍스트를 채웁니다. https://typesense.org/docs/30.2/api/conversational-search-rag.html
키 및 멀티 테넌시
- 앱에서 부트스트랩 키를 절대 사용하지 마십시오. 관리자 키나 스코프 검색 키의 부모 키를 절대 노출하지 마십시오. https://typesense.org/docs/guide/data-access-control.html
- 스코프 검색 키: 부모는
documents:search만 있어야 하며, 백엔드에서 사용자별로 생성하고,filter_byANDfilter_curated_hits: true를 포함시켜야 합니다. 그렇지 않으면 고정 및 큐레이션된 적중이 테넌트 간에 누출됩니다. https://typesense.org/docs/30.2/api/api-keys.html 및 https://typesense.org/docs/30.2/api/curation.html - 키의
collections는 전역 엔드포인트(keys,synonym_sets,stopwords)를 제한하지 않습니다. 참조 필드는 조인을 통해 참조된 컬렉션을 노출합니다. https://typesense.org/docs/30.2/api/api-keys.html
운영
- 프로덕션: 3~5노드 HA, 모든 노드(로드 밸런서 뒤에
nearestNode포함)가 구성된 클라이언트, RAM 85% 미만. https://typesense.org/docs/guide/high-availability.html 및 https://typesense.org/docs/guide/running-in-production.html /operations/snapshot으로 백업하고, 라이브 데이터 디렉토리를 복사하지 마십시오. 팔로워를 먼저 업그레이드하고, 리더를 마지막에 업그레이드하십시오. https://typesense.org/docs/guide/backups.html 및 https://typesense.org/docs/guide/updating-typesense.html
이전 패턴
| 이전 | 현재 | 출처 |
|---|---|---|
/collections/{c}/synonyms, synonyms:* 키 액션 | /synonym_sets, synonym_sets:* 및 synonym_sets/items:*, 컬렉션 synonym_sets로 연결 | https://typesense.org/docs/30.2/api/synonyms.html |
/collections/{c}/overrides, overrides:* | /curation_sets, curation_sets:* 및 curation_sets/items:* | https://typesense.org/docs/30.2/api/curation.html |
override_tags | curation_tags | https://typesense.org/docs/30.2/api/curation.html |
params.source 및 params.destination이 있는 분석 규칙 | 최상위 collection, event_type, 평면 params | https://typesense.org/docs/30.2/api/analytics-query-suggestions.html |
가중치 source.events가 있는 하나의 카운터 규칙 | params.weight가 있는 이벤트 유형당 하나의 규칙 | https://typesense.org/docs/30.2/api/analytics-query-suggestions.html |
group_by로 정확한 found | 근사치, 정확도를 위한 group_max_candidates | https://typesense.org/docs/30.2/api/search.html |
| 필터 생성을 위한 앱 내 LLM 호출 | nl_search_models + nl_query=true | https://typesense.org/docs/guide/natural-language-search.html |
| 평면화된 중첩 객체 | enable_nested_fields | https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html |
혼합 리스트를 위한 document_type이 있는 하나의 컬렉션 | union: true가 포함된 multi_search | https://typesense.org/docs/guide/faqs.html |
이전 highlights 배열 | highlight 객체, enable_highlight_v1=false | https://typesense.org/docs/30.2/api/search.html |
키는 업데이트할 수 없습니다. 새 키를 만들어 이전 키를 교체하십시오. 자체 호스팅 서버는 업그레이드 전에 스냅샷을 생성하여 동의어와 재정의가 마이그레이션되도록 합니다. https://typesense.org/docs/30.2/api/synonyms.html
참조 파일
| 파일 | 읽을 내용 |
|---|---|
| references/schema-and-collections.md | 필드 매개변수 및 기본값, 타입, RAM 비용, 자동 스키마, 중첩 객체, alter, 별칭, 복제, 컬렉션 레이아웃 |
| references/tokenization-locale-stemming.md | token_separators, symbols_to_index, infix, SKU, 이메일 및 URL 레시피, 로케일 및 분음 부호, 형태소 분석 사전 |
| references/documents-and-import.md | ID, 가져오기 액션, 가져오기 결과 읽기, 타임아웃, dirty_values, 업데이트, 삭제 및 쿼리별 내보내기 |
| references/syncing-and-reindexing.md | 데이터베이스 동기화 전략, 대량 쓰기, 503 및 리소스 오류, 별칭 재인덱스 |
| references/search-parameters.md | q, query_by, 오타 허용 오차, 토큰 삭제, 접두사, max_candidates, 하이라이팅, 페이지네이션, 캐시, 프리셋 |
| references/filtering-and-geo.md | filter_by 구문, 우선순위, 이스케이프, 배열, 중첩 객체, 빈 값, 지리 필터 및 정렬 |
| references/ranking-and-sorting.md | 기본 랭킹, sort_by, text_match_type, 버킷, _eval, 감쇠, 누락 값, 고정 |
| references/faceting-grouping-multi-search.md | 패싯 및 전략, group_by, 연합 및 유니온 멀티 검색, 부울 태그 검색 |
| references/synonyms-curation-stopwords.md | 동의어 집합, 큐레이션 집합, 태그, 동적 규칙, 스코프 검색 키를 사용한 큐레이션, 중지어 |
| references/vector-and-hybrid-search.md | 벡터 필드, 자동 임베딩 모델, vector_query, 하이브리드 퓨전 및 alpha, HNSW, 메모리 |
| references/conversational-nl-image-voice.md | RAG 대화 모델, 자연어 검색, 이미지 및 음성 쿼리, 추천 |
| references/api-keys-and-access-control.md | 키 타입, 액션, 스코프 함정, 스코프 검색 키, 멀티 테넌트 패턴, 로테이션 |
| references/clients-and-errors.md | 클라이언트 라이브러리, 노드 및 로드 밸런서 구성, JS 튜닝, 캐시, 오류 코드, 느린 검색 |
| references/server-configuration.md | 서버 플래그 및 기본값, CORS, TLS, 로깅, 리소스 제한, 분석 플래그, 설치 노트 |
| references/cluster-ha-backups-upgrades.md | HA 클러스터, 노드 파일, 복구, 운영 API, 모니터링, 백업, 업그레이드, 크기 조정, CI |
| references/analytics-and-query-suggestions.md | 분석 규칙 및 이벤트, 인기 및 무적중 쿼리, 카운터, 로그 규칙, 제안 |
| references/joins-and-personalization.md | 참조 필드, 조인 포함, 필터 및 정렬, 왼쪽 및 안티 조인, 비동기 참조, 개인화 |
| references/ui-and-algolia-migration.md | InstantSearch 어댑터, Algolia 차이점, 개념 매핑, 마이그레이션 단계 |
출처 및 가져오기 세부 정보는 SOURCES.md에 나열되어 있습니다.