typesense-docs

公式ドキュメントから見るTypesense

概要

このスキルは、Typesenseのドキュメントに記載されている、見落としがちなポイントをまとめたものです。例えば、RAMを消費するもの、HTTP 200の背後に失敗を隠すインポート結果、フィルタの優先順位、結果を緩くするデフォルト設定、スコープ付き検索キーのリーク、ハイブリッド検索の重み、v30での同義語セットとキュレーションセットへの移行などが含まれます。一般的な検索やデータベースのアドバイスは除外されています。すべての主張には、その出典となるドキュメントのURLが付記されています。

対象バージョン

Typesense Server 30.2、コードサンプルはJavaScriptクライアントを使用。サーバーフラグはセルフホストサーバーに適用されます。Typesense Cloud がこれらを管理します。古いサーバー向けに書かれたコードをレビューする前に、下の「古いパターン」を参照してください。

ナビゲーション方法

1. 以下のクイックスタートを読んでください。ほとんどのタスクで重要なルールを網羅しています。
2. 最後の表から、タスクの領域に合致するリファレンスファイルを1つ開いてください。各ファイルは独立しています。
3. すべての主張は、そのソース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.html
• object[] 内の同じオブジェクト条件: ingredients.{name:=cheese && concentration:<50}。 https://typesense.org/docs/guide/tips-for-filtering.html
• drop_tokens_threshold と typo_tokens_threshold のデフォルトは1なので、ヒット数が少ないクエリは警告なく単語をドロップしたり、タイプミスを追加したりします。すべての単語を必須にするには drop_tokens_threshold: 0 を設定します。タイプミスを無効にするには num_typos: 0 および typo_tokens_threshold: 0 の両方を設定します。 https://typesense.org/docs/guide/ranking-and-relevance.html
• max_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
• 1ページあたり最大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 はベクトルの重みです。query_by_weights には埋め込みフィールド用のプレースホルダ 0 が必要です。 https://typesense.org/docs/30.2/api/vector-search.html
• RAG: conversation=true と exclude_fields: 'embedding' を指定するか、生の浮動小数点数でLLMコンテキストを埋めます。 https://typesense.org/docs/30.2/api/conversational-search-rag.html

キーとマルチテナンシー

• アプリでブートストラップキーを決して使用しないでください。管理キーやスコープ付き検索キーの親キーを公開しないでください。 https://typesense.org/docs/guide/data-access-control.html
• スコープ付き検索キー: documents:search のみの権限を持つ親キーから、ユーザーごとにバックエンドで生成し、filter_by と filter_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 を持つ1つのカウンタールール	イベントタイプごとに1つのルールと 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 に記載されています。