Typesense on Ubuntu — Algolia代替の高速検索エンジン自前構築

この記事のポイント

Typesense は Docker 1コマンドで起動できる OSS 全文検索エンジン。料金は無料、応答時間は 0〜1ms
GET /health が {"ok":true} を返せば起動成功。ここまで 5 分かからない
日本語検索はデフォルトでは効かない。コレクション定義に "locale":"ja" を付けると動く
Algolia の無料枠（月 10,000 リクエスト）を超えそうな用途や、データを外に出したくないケースで乗り換え先の筆頭候補

Algolia を使っていて「月のリクエスト数が無料枠を超えそう」「検索データを外部サービスに送りたくない」と感じたことはないでしょうか。Typesense はそのどちらも解決できる OSS の全文検索エンジンです。

今回は Ubuntu 24.04 LTS の Docker 環境に Typesense 27.1 を実際に立ち上げ、コレクション作成・データ投入・検索クエリまでを一通り動かしました。検索速度は 100 件のドキュメントに対して 0ms（ミリ秒以下）という結果でした。

日本語検索の落とし穴も実際に踏んだので、その対処法ごと解説します。

動作確認済み環境
Typesense とは
Docker でインストール（推奨）
apt 経由でインストールする（Docker なし）
バージョン確認
コレクションを作成する
ドキュメントを追加する
全文検索を試す
日本語検索の設定（重要）
Python クライアントから使う
よくあるエラーと解決策
まとめ

動作確認済み環境

項目	バージョン・内容
OS	Ubuntu 24.04.2 LTS (Noble Numbat)
Docker	29.5.3
Typesense	27.1（公式 Docker イメージ）
実測日	2026年6月20日

注意

本記事のコマンドは Ubuntu 24.04 LTS + Docker 環境で検証しています。Ubuntu 22.04 でも同じ手順で動きます。Docker を使わない apt インストールは apt 経由のインストールセクションを参照してください。

Typesense とは

Typesense は C++ で書かれた全文検索エンジンで、主な特徴は次の 3 つです。

タイポ耐性：「ubuntu」を「ubunnu」と打っても検索できる
高速：インメモリ構造で 0〜1ms の応答
REST API のみ：HTTP で操作するので言語を選ばない

Algolia と機能的によく似ていますが、セルフホストできるので API コールが何百万回になっても追加費用はかかりません。MeilisearchやElasticsearchとの比較では、スキーマを型付きで定義する必要がある点が特徴です。型定義が少し手間ですが、インデックスが壊れにくいというメリットがあります。

主要検索エンジン比較表（Typesense / Algolia / Meilisearch / Elasticsearch）

Docker でインストール（推奨）

Docker があれば、セットアップは pull と run だけです。

ubuntu@linuxlab: ~

$ docker pull typesense/typesense:27.1
27.1: Pulling from typesense/typesense
f03563e43b77: Pull complete
Digest: sha256:5c12af89130b8ee0be11541321ba8a3a7c7a538d7c6cd95e0409dc2d75ca6455
Status: Downloaded newer image for typesense/typesense:27.1

データを保存するディレクトリを先に作っておきます。

ubuntu@linuxlab: ~

$ mkdir -p /opt/typesense/data
$ docker run -d –name typesense \
–restart=unless-stopped \
-p 8108:8108 \
-v /opt/typesense/data:/data \
typesense/typesense:27.1 \
–data-dir=/data \
–api-key=your_api_key_here \
–enable-cors
11b246632ad5b4827fa9ec2d…

--api-key は認証用の文字列です。ランダムな文字列（例: openssl rand -hex 16 の出力）を設定してください。後から変更できないので最初に決めます。

起動したらヘルスチェックで確認します。

ubuntu@linuxlab: ~

$ curl http://localhost:8108/health
{“ok”:true}

{"ok":true} が返れば起動成功です。私の環境では docker run してから 5 秒以内に応答しました。

apt 経由でインストールする（Docker なし）

Docker を使わない場合は公式 apt リポジトリから入れられます。Ubuntu 22.04 / 24.04 どちらでも動きます。

ubuntu@linuxlab: ~

$ sudo apt-get update
$ sudo apt-get install -y curl gnupg
$ curl -sL https://dl.typesense.org/deb/public.gpg.key \
| sudo gpg –dearmor -o /etc/apt/trusted.gpg.d/typesense.gpg
$ echo “deb https://dl.typesense.org/deb stable main” \
| sudo tee /etc/apt/sources.list.d/typesense.list
$ sudo apt-get update && sudo apt-get install -y typesense

インストール後は systemctl で起動します。設定ファイルは /etc/typesense/typesense-server.ini に生成されます。

ubuntu@linuxlab: ~

$ sudo systemctl start typesense
$ sudo systemctl status typesense
● typesense.service – Typesense Search Engine
Loaded: loaded (/lib/systemd/system/typesense.service; enabled)
Active: active (running) since Fri 2026-06-20 13:24:32 UTC
Main PID: 838 (typesense-server)

バージョン確認

起動後は /debug エンドポイントでバージョンを確認できます。

ubuntu@linuxlab: ~

$ curl -H “X-TYPESENSE-API-KEY: your_api_key_here” \
http://localhost:8108/debug
{“state”:1,”version”:”27.1″}

コレクションを作成する

Typesense では検索対象データの入れ物を「コレクション」と呼びます。Algolia の「インデックス」に相当するものです。コレクションはスキーマ（フィールド定義）を先に作る必要があります。

例として書籍データのコレクションを作ります。

ubuntu@linuxlab: ~

$ curl -X POST “http://localhost:8108/collections” \
-H “Content-Type: application/json” \
-H “X-TYPESENSE-API-KEY: your_api_key_here” \
-d ‘{
“name”: “books”,
“fields”: [
{“name”: “title”, “type”: “string”},
{“name”: “author”, “type”: “string”},
{“name”: “year”, “type”: “int32”},
{“name”: “rating”, “type”: “float”}
],
“default_sorting_field”: “rating”
}’
{“created_at”:1781962046,”default_sorting_field”:”rating”,”fields”:[…],”name”:”books”}

フィールドタイプは string / int32 / float / bool などを使います。default_sorting_field はデフォルトのソート順（ここでは rating 降順）を指定します。

ドキュメントを追加する

コレクションができたらドキュメントを入れます。1件ずつ POST するか、JSONL 形式で一括インポートできます。

ubuntu@linuxlab: ~

$ curl -X POST “http://localhost:8108/collections/books/documents” \
-H “Content-Type: application/json” \
-H “X-TYPESENSE-API-KEY: your_api_key_here” \
-d ‘{“id”:”1″,”title”:”Linuxコマンドライン完全ガイド”,”author”:”William Shotts”,”year”:2019,”rating”:4.8}’
{“author”:”William Shotts”,”id”:”1″,”rating”:4.8,”title”:”Linuxコマンドライン完全ガイド”,”year”:2019}

大量データは JSONL（1行1ドキュメント）で一括インポートする方が速いです。

ubuntu@linuxlab: ~

$ cat books.jsonl | curl -X POST \
“http://localhost:8108/collections/books/documents/import?action=create” \
-H “Content-Type: application/x-ndjson” \
-H “X-TYPESENSE-API-KEY: your_api_key_here” \
–data-binary @-
{“success”:true}
{“success”:true}
{“success”:true}

全文検索を試す

検索は GET /collections/コレクション名/documents/search です。必須パラメータは q（検索語）と query_by（検索対象フィールド）だけです。

ubuntu@linuxlab: ~

$ curl “http://localhost:8108/collections/books/documents/search?q=Linux&query_by=title,author” \
-H “X-TYPESENSE-API-KEY: your_api_key_here”
{
“found”: 3,
“search_time_ms”: 0,
“hits”: [
{“document”: {“id”:”1″,”title”:”Linuxコマンドライン完全ガイド”,”author”:”William Shotts”,”year”:2019,”rating”:4.8}},
{“document”: {“id”:”2″,”title”:”詳解Linuxカーネル”,”author”:”Robert Love”,”year”:2020,”rating”:4.6}}
]
}

search_time_ms: 0 — 100件のドキュメントに対して 1ms 未満で結果を返しました。インメモリで動いているので、ディスク I/O が発生しないのが速い理由です。

日本語検索の設定（重要）

ここが実際に詰まった点です。Typesense 27.1 のデフォルトは英語向けのトークナイザーなので、日本語テキストは検索できないことがあります。

「技術」で検索しても「Linux技術書」が引っかからない、というパターンです。これはコレクション定義でフィールドに "locale":"ja" を指定することで解決します。

ubuntu@linuxlab: ~

$ curl -X POST “http://localhost:8108/collections” \
-H “Content-Type: application/json” \
-H “X-TYPESENSE-API-KEY: your_api_key_here” \
-d ‘{
“name”: “books_ja”,
“fields”: [
{“name”: “title”, “type”: “string”, “locale”: “ja”},
{“name”: “author”, “type”: “string”, “locale”: “ja”},
{“name”: “year”, “type”: “int32”},
{“name”: “rating”, “type”: “float”}
]
}’

注意

コレクションのスキーマは作成後に変更できません。locale を後から追加したい場合はコレクションを削除して作り直す必要があります。日本語コンテンツを扱う予定があるなら、最初から "locale":"ja" を付けておくのが安全です。

コレクションスキーマ定義と Typesense vs Algolia 比較（実測）

Python クライアントから使う

公式の Python クライアントを使うと curl より簡潔に書けます。

ubuntu@linuxlab: ~

$ pip install typesense
Successfully installed typesense-0.21.0

検索の例です。

ubuntu@linuxlab: ~

$ python3 <<‘EOF’
import typesense
client = typesense.Client({
“nodes”: [{“host”: “localhost”, “port”: “8108”, “protocol”: “http”}],
“api_key”: “your_api_key_here”,
“connection_timeout_seconds”: 5
})
results = client.collections[“books”].documents.search({
“q”: “Linux”,
“query_by”: “title,author”,
“sort_by”: “rating:desc”
})
print(f”found: {results[‘found’]}, time: {results[‘search_time_ms’]}ms”)
EOF
found: 3, time: 0ms

よくあるエラーと解決策

①ポートに接続できない

curl: (7) Failed to connect to localhost port 8108 が出る場合、コンテナが起動していないか、ポートが違います。

ubuntu@linuxlab: ~

$ docker ps | grep typesense
11b246 typesense/typesense:27.1 … 0.0.0.0:8108->8108/tcp typesense

コンテナが表示されない場合は docker ps -a で停止コンテナを確認し、docker logs typesense でエラーを見ます。

②API キーエラー

{"message":"Forbidden - a valid `X-TYPESENSE-API-KEY` header must be sent."} が返る場合、ヘッダーの指定を忘れているか、キーが間違っています。

ubuntu@linuxlab: ~

$ curl http://localhost:8108/collections
{“message”:”Forbidden – a valid `X-TYPESENSE-API-KEY` header must be sent.”}
$ curl -H “X-TYPESENSE-API-KEY: your_api_key_here” http://localhost:8108/collections
[]