typesense

typesense — インストール可能な、タイポ許容検索環境

Typesense は、高速でタイポを許容する オープンソースの検索エンジンです。Algolia の代替となり、ElasticSearch よりも 使いやすい選択肢です。実行時依存関係のない単一の C++ バイナリで、 低レイテンシー（<50ms）の即時検索を実現するよう設計されています。このスキルは ルーティング優先のラッパーです。サーバーの実行方法を選び、クライアントを接続し、 データをモデル化して、検索、UI、本番環境向けの堅牢化を進めます。

このスキルを使う場面

• ユーザーが、サイト、アプリ、カタログ、ドキュメント、製品閲覧体験向けに 検索バックエンドを立ち上げたい
• ユーザーが Typesense のインストールや実行（バイナリ、Docker、Typesense Cloud）を求めている
• ユーザーが タイポ許容、ファセット／フィルタリング、ジオ検索、並べ替え、 グループ化、同義語、キュレーション、スコープ付き API キー、連合マルチ検索 を求めている
• ユーザーが、セルフホストまたはマネージドのオープンソースエンジンに Algolia または Elasticsearch から移行したい
• ユーザーが Typesense の前面または周辺に InstantSearch.js の UI または Raft HA クラスターを導入したい

このスキルを使わない場面

• ユーザーが LLM のトレース／評価の可観測性（ハルシネーション、プロンプト スコアリング）を求めている → opik / langsmith を使用
• ユーザーがリポジトリ内でエージェント向けの トークン効率の高いコード検索を 求めている → semble を使用
• ユーザーが 汎用サービスダッシュボード／稼働時間アラート（検索以外の テレメトリー）を求めている → monitoring-observability を使用
• ユーザーが埋め込み専用に特化した ベクトルデータベースを求めている — Typesense はベクトル検索とハイブリッド検索に対応しますが、純粋な ANN を 極めて大規模に扱う場合は、専用ストアのほうが適している可能性があります。 まずワークロードを確認してください

前提条件

要件	備考
Docker（推奨）	公式イメージを使う、ローカルと本番環境で最も簡単な方法です
またはバイナリを実行するホスト	typesense.org/downloads から Linux（x86-64）／macOS 用バイナリパッケージを入手できます
または Typesense Cloud	運用不要のマネージドクラスター（固定の時間料金＋帯域料金で、レコード単位の料金ではありません）
API クライアント	Python／JS／PHP／Ruby は公式、Go／Dart／C# はコミュニティ提供です
API キー	サーバー起動時に設定します（--api-key）。テナントごとにスコープ付きキーを生成してください

手順

ステップ 1 — サーバーモードを選ぶ

モード	用途	エントリーポイント
Docker（推奨）	ローカル開発から本番環境まで、コマンド 1 つで実行	docker run typesense/typesense …
バイナリ	ベアメタル／Docker なし	https://typesense.org/downloads からダウンロード
Typesense Cloud	運用不要のマネージド環境、HA	https://cloud.typesense.org

ローカル Docker サーバー（実際のバージョンタグを指定し、強力なキーを設定します）：

docker run -p 8108:8108 -v /tmp/typesense-data:/data \
  typesense/typesense:27.1 --data-dir /data --api-key=CHANGE_ME_STRONG_KEY

このスキルには、ローカル Docker サーバーを起動し、Python クライアントを一度に インストールする scripts/install.sh が含まれています。

ステップ 2 — API クライアントをインストールする

pip install typesense        # Python (official)
npm install typesense        # JS/TS (official)
# PHP: composer require typesense/typesense-php   Ruby: gem install typesense

生の CURL よりも公式クライアントを推奨します。HA 構成向けのスマートな再試行戦略が 組み込まれています。クライアントと統合の全マトリックスについては、 references/commands.md を参照してください。

ステップ 3 — コレクションのスキーマを設計する

コレクションは、型付きスキーマを持つインデックスです。絞り込み／ドリルダウン用に フィールドへ facet: true を指定し、ランキング用に default_sorting_field を 設定します。

import typesense
client = typesense.Client({
    "api_key": "CHANGE_ME_STRONG_KEY",
    "nodes": [{"host": "localhost", "port": "8108", "protocol": "http"}],
    "connection_timeout_seconds": 2,
})
client.collections.create({
    "name": "companies",
    "fields": [
        {"name": "company_name", "type": "string"},
        {"name": "num_employees", "type": "int32"},
        {"name": "country", "type": "string", "facet": True},
    ],
    "default_sorting_field": "num_employees",
})

Algolia とは異なり、ほとんどの設定（検索対象フィールド、ファセット、ランキング）は クエリ時に指定するため、1 つのコレクションで複数の並べ替え順に対応できます。 メモリ使用量を抑えながら、柔軟性を高められます。

ステップ 4 — ドキュメントをインデックスに登録する

client.collections["companies"].documents.create({
    "id": "124", "company_name": "Stark Industries",
    "num_employees": 5215, "country": "USA",
})
# Bulk import (JSONL) for large datasets:
# client.collections["companies"].documents.import_(jsonl_lines, {"action": "upsert"})

ステップ 5 — 検索する（タイポ許容＋ファセット＋フィルター＋ジオ検索）

client.collections["companies"].documents.search({
    "q": "stork",                       # typo of "stark" — handled out of the box
    "query_by": "company_name",
    "filter_by": "num_employees:>100",
    "sort_by": "num_employees:desc",
    "facet_by": "country",
})

活用できる機能：ファセット／フィルタリング、ジオ検索（距離順の並べ替え）、 グループ化と distinct、同義語、キュレーション／マーチャンダイジング（レコードの ピン留め）、1 回のリクエストでコレクションをまたいで実行する連合 マルチ検索、ベクトル検索／ハイブリッド検索。詳細は references/commands.md を参照してください。

ステップ 6 — 検索 UI と本番環境

• UI：InstantSearch.js adapter を使うと、フィルタリング、並べ替え、ページネーション、入力中の UI をすばやく実装できます。
• マルチテナント：特定のレコードへのアクセスを制限するスコープ付き API キーを生成します。管理者キーをクライアントに渡してはいけません。
• HA：高可用性を実現するため、Raft ベースのクラスター（通常は 3 ノード）を実行します。アップグレードはバイナリの差し替えと再起動で行います。

ステップ 7 — jeo-skills と併用するプラグイン形式のインストール

このスキルフォルダーは、標準の jeo-skills フローを通じてプラグインとしてインストールできます。これにより、ラッパー、リファレンス、インストーラーがディスクに配置され、サポートされている任意のエージェントランタイムで使用できます。

# Project install (writes into .agents/skills/typesense/)
npx skills add https://github.com/akillness/jeo-skills --skill typesense

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill typesense -a claude-code -a codex -y

出力形式

ユーザーが typesense にヘルプを求めた場合は、簡潔な概要を返します。

# typesense Routing Brief

## Scope
- Server mode: docker | binary | cloud | undecided
- Client: python | js | php | ruby | community
- Stage: install-server | install-client | schema-design | index | search | ui | production-ha

## Recommended next move
- start-docker-server | install-client | create-collection | import-docs | run-search | wire-instantsearch | scoped-keys | cluster

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `opik` / `langsmith` for LLM trace/eval observability
- `semble` for agent-facing code search over a repo
- `monitoring-observability` for non-search service telemetry

ベストプラクティス

1. latest ではなくバージョンタグを固定する — typesense/typesense:27.1 を指定し、再起動してもインデックスが失われないよう、データディレクトリには実際のボリュームを使用します。
2. クエリ時に設定する — 検索対象フィールド、ファセット、ソート、ランキングはクエリごとに設定します。ソート順ごとに複数のコレクションが必要になることはほとんどありません。
3. スキーマでファセットを指定する — フィールドのフィルタリングやドリルダウンには facet: true が必要です。
4. クライアントにはスコープ付き API キーを使用する — 管理者キーはサーバー側に保持し、スコープ付きキーでテナントごとのレコードアクセスを制御します。
5. upsert を使って JSONL で一括インポートする — 大規模なデータセットでは、ドキュメントを個別に作成するよりはるかに高速です。インデックスはメモリ常駐型のため、RAM はインデックスのサイズに合わせます。
6. ライセンスに注意する — サーバーは GPL、クライアントライブラリは Apache-2.0 です。サーバーは別のデーモンとして実行してください（想定されている使い方です）。

参考資料

• アップストリームリポジトリ：https://github.com/typesense/typesense
• API ドキュメント：https://typesense.org/api
• ガイド／チュートリアル：https://typesense.org/guide
• ダウンロード（バイナリ）：https://typesense.org/downloads
• Docker イメージ：https://hub.docker.com/r/typesense/typesense
• Typesense Cloud：https://cloud.typesense.org
• InstantSearch アダプター：https://github.com/typesense/typesense-instantsearch-adapter
• インストールスクリプト：scripts/install.sh
• クライアントと統合の一覧：references/commands.md
• 関連スキル：../opik/SKILL.md、../semble/SKILL.md、 ../monitoring-observability/SKILL.md
• ライセンス：GPL-3.0（サーバー）；Apache-2.0（API クライアント）