便利なソフトをAIが実際に動かしてわかりやすくレポート

🤖 AI自動レポート column

SQLite FTS5 で動く軽量 RESTful 検索サーバー「Scout」— ElasticSearch なしで本格全文検索を実現

タグ SQLiteFTS5全文検索REST APIPythonFlaskDocker軽量サーバーcolumnコラムlinuxLinuxwindowsWindowsGitHubオープンソースcoleiferscout
📦 GitHubで見る 📥 デモスクリプトをダウンロード (.sh) 📥 デモ一式をダウンロード (.zip)
🚀 今すぐ試せます！ デモスクリプトをダウンロードして、解凍後にターミナルで bash ファイル名.sh を実行してください（中身を一度確認してから実行すると安心です）。 （macOS / Linux 環境が必要）

SQLite FTS5 で動く軽量 RESTful 検索サーバー「Scout」— ElasticSearch なしで本格全文検索を実現

ひとことでいうと

Scout（スカウト）は、SQLite の全文検索拡張機能 FTS5 を使った、軽量な検索サーバーです。Python と Flask で作られており、ElasticSearch（エラスティックサーチ）のような大がかりなシステムを用意しなくても、ファイル 1 つの SQLite データベースで本格的な全文検索 API をすぐに立ち上げられます。ドキュメントの登録・更新・削除はもちろん、メタデータ（付加情報）によるフィルタリング検索や、ファイルの添付・取得も REST API（インターネットの標準的な通信方式）を通じて行えます。小規模なチームや個人開発者が「検索機能をさくっと実装したい」ときにぴったりの選択肢です。

こんな人におすすめ

1. ブログや社内 Wiki に検索機能を手軽に追加したい人 ElasticSearch や Solr（ソーラー）のような検索エンジンは、別途サーバーを用意する必要があり、導入コストが高めです。Scout は SQLite（ひとつのファイルとして扱えるデータベース）を使うため、追加のサーバーが不要です。個人ブログ、社内ナレッジベース、プロジェクトの Wiki など、小〜中規模のコンテンツへの検索機能追加に向いています。

2. 言語やフレームワークを問わず REST API で検索を呼び出したい開発者 Scout は HTTP リクエストを受け付ける REST API として動くため、Python に限らず JavaScript・Go・Ruby など好きな言語から curl コマンドや HTTP クライアントで連携できます。フロントエンドとバックエンドを分けて設計したい場合に、検索バックエンドとして独立して置けるのが強みです。

3. 本番導入の前に検索 API の設計をプロトタイプで確かめたい人 大規模な検索基盤を本番に入れる前に、API の設計や検索ロジックを先に試したい場面があります。Scout なら Docker（ドッカー：アプリをまるごと箱に詰めて動かす仕組み）イメージも公開されているため、手元でも CI/CD（継続的インテグレーション・デリバリー）環境でも素早く検証を始められます。

インストール・使い方

Step 1: pip でインストールする

pip install scout

pip（ピップ）とは、Python のパッケージ（部品）を取得・管理するコマンドです。ターミナル（文字で命令を送る画面）にこの 1 行をコピー＆ペーストして実行するだけでインストールできます。

Python 3.8 以上と、FTS5 に対応した SQLite（バージョン 3.9.0 以降、2015 年以降リリース）が必要です。ほとんどのモダンな Linux・macOS 環境ではデフォルトで条件を満たしています。FTS5 が使えるか確認したい場合は、次のコマンドを実行してください。エラーが出なければ問題ありません。

python -c "import sqlite3; sqlite3.connect(':memory:').execute('CREATE VIRTUAL TABLE t USING fts5(x)')"

Step 2: サーバーを起動する

scout /path/to/search-index.db

/path/to/search-index.db は、データを保存したい場所とファイル名です（例：~/mydata/search.db）。指定したファイルが存在しない場合は自動で作成されます。デフォルトではポート 8000（通信の入り口番号）で起動します。

本番環境向けには、gevent（ジーイベント：Python の非同期 I/O ライブラリ）を使った高性能起動コマンドも用意されています。

scout_wsgi /path/to/search-index.db

Step 3: Docker で起動する

Docker を使うと、環境の差異を気にせず動かせます。次のコマンドでポート 9004 にサーバーが立ち上がり、データベースはコンテナ（Docker の「箱」）内の /data/search-index.db に保存されます。

docker run -d \
    --name scout \
    -p 9004:9004 \
    -v scout-data:/data \
    coleifer/scout

-v scout-data:/data の部分はボリューム（データの保存領域）をマウント（接続）する設定です。これにより、コンテナを再起動してもデータが消えずに残ります。

認証（API キー）を設定したい場合は、-k フラグで秘密鍵を指定します。その後のリクエストには ?key=my-secret-key を付けるか、Authorization ヘッダーを使います。

docker run -d -p 9004:9004 -v scout-data:/data coleifer/scout -k my-secret-key

Step 4: ドキュメントを登録して検索する

# インデックス（検索対象のまとまり）を作りながらドキュメントを登録
curl -X POST http://localhost:8000/blog/ \
     -H "Content-Type: application/json" \
     -d '{"content": "Scout is a lightweight search server.", "metadata": {"author": "alice"}}'

# 全文検索を実行
curl "http://localhost:8000/blog/?q=lightweight+search"

curl（カール）は HTTP リクエストをコマンドラインから送るツールです。上のコマンドをコピー＆ペーストするだけで、ドキュメントの登録と検索を試せます。metadata には任意のキーと値を設定でき、あとでフィルタリング検索に使えます。

動かしてみた

Docker 環境（Python 3.12.13）でパッケージのインストールを実行したところ、setup.py と scout.egg-info ディレクトリが正常に生成されました。Scout のソースコードは models.py・views.py・search.py・server.py・serializers.py などのファイルで構成されており、役割ごとにきれいに分離されていることが確認できました。

リポジトリには migrate_fts5.py というマイグレーション（移行）スクリプトも含まれています。旧バージョンで使われていた FTS4 形式のデータベースを FTS5 形式へ変換するためのものです。Docker コンテナ内で --migrate フラグを付けて実行することで、既存のデータを引き継ぎながらアップグレードできます。

また、gevent_server.py が独立したモジュールとして実装されており、本番向けの高性能 WSGI（ウィスキー：Python の Web アプリとサーバー間の標準インターフェース仕様）サーバーが標準で用意されていることも確認しました。

ブラウザで試す（デモ）

ブラウザ上から Scout の動作を手軽に体験できる Gradio（グラディオ）デモも用意されています。サンプルドキュメントとして Python・データベース・検索技術に関する英語テキストがあらかじめ登録されており、キーワードを入力するだけで検索結果をその場で確認できます。新しいドキュメントを追加してみると、追加した直後から検索対象に反映されることも確かめられます。実際に手を動かして挙動をつかみたいときに便利です。

実践のコツ — はじめの一歩

Scout をスムーズに使い始めるために、押さえておくと役立つポイントをまとめます。

  • まず Docker で試す: 環境構築が最も簡単で、1 コマンドで API が立ち上がります。pip インストールで進む前に Docker で全体の流れをつかむと理解が早まります。
  • インデックスは用途ごとに分ける: 1 つの SQLite データベースの中に複数のインデックスを作れます。「記事」「ユーザー」「ファイル」などカテゴリ別に分けると、検索精度の調整がしやすくなります。
  • メタデータでフィルタリングを活用する: ドキュメント登録時に metadata に著者名・タグ・日付などを入れておくと、検索時にそれらで絞り込みができます。コンテンツの中身だけでなく属性情報も検索に活かせます。
  • 本番環境では scout_wsgi を使う: 開発用の scout コマンドに対し、scout_wsgi は gevent を使った非同期処理に対応しており、同時アクセスが増えても安定して動きます。
  • API キーで保護する: 公開サーバーで動かす場合は必ず -k フラグで API キーを設定してください。キーなしでは誰でもデータの追加・削除ができてしまいます。
  • FTS5 の確認を先に済ませる: インストール前に FTS5 が使えるか確かめておくと、後から詰まるリスクを減らせます。Step 1 の確認コマンドを先に実行しておきましょう。

活用例

  • 技術ブログの全文検索バックエンド: 記事を Scout に登録し、タグや著者名でフィルタリングしながらキーワード検索できるバックエンドとして利用できます。フロントエンドは好きな JavaScript フレームワークから REST API を呼ぶだけで実装できます。

  • 社内ドキュメント検索システム: 会議の議事録や仕様書を Scout に格納することで、キーワードで素早く必要な文書を探せる社内検索ツールを構築できます。複数インデックスを使って部署別・年度別にデータを分けることも可能です。

  • ファイル添付付きドキュメント管理: Scout は BLOB（バイナリデータ：画像・PDF など）の添付機能を持っているため、ドキュメント本文と添付ファイルをまとめて管理・検索できる軽量な文書管理システムとして活用できます。

  • 検索 API のプロトタイピング: 本番に大規模な検索基盤を導入する前に、API の設計や検索クエリの挙動を Scout で先行検証できます。仕様を固めてから本番移行するという進め方がとりやすくなります。

  • CI/CD パイプラインでの検索テスト: Docker イメージを使えば、テスト環境に Scout を自動で組み込めます。「検索結果が期待通りかどうか」を自動テストで確かめる用途に向いています。

  • 個人開発の Wiki・ナレッジベース: 学習メモや読書まとめをドキュメントとして登録しておき、後から気になるキーワードで横断検索できる個人用ナレッジベースとして使えます。サーバーを別途立てなくてよいため、ローカル環境だけで完結します。

用語とポイント解説

FTS5（エフティーエス5） SQLite に組み込まれた全文検索の拡張機能（バージョン 5）です。かんたんに言うと、大量のテキストの中から特定の単語を素早く見つけるための専用インデックスを作る仕組みです。SQLite 3.9.0（2015 年）以降に標準搭載されており、追加ライブラリなしで使えます。転置インデックス（単語からドキュメントを逆引きできる索引）を内部で構築することで、高速な検索を実現しています。

BM25（ビーエムにじゅうご） 検索結果の順番（ランキング）を決めるアルゴリズムです。かんたんに言うと、「この単語がどれだけ重要か」を単語の出現頻度と文書の長さを考慮して点数化するしくみです。単純に「何回登場したか」だけで判断するのではなく、文書が長いほど単語が多く出やすいというバイアスも補正します。Scout ではデフォルトでこのスコアを使って検索結果を並べ替えます。

Porter Stemmer（ポーターステマー） 英単語の語幹（stem：単語の根っこの部分）を取り出すアルゴリズムです。かんたんに言うと、「running」「runs」「ran」をすべて「run」として同じ意味の単語とみなして検索できるようにする処理です。活用形や変化形が違っても同じ文書をヒットさせられるため、英語テキストの検索精度が上がります。

peewee ORM（ピーウィー オーアールエム） Python 向けの軽量な ORM ライブラリです。かんたんに言うと、データベースのテーブルと Python のオブジェクト（クラス）を対応付けて、SQL を直接書かなくてもデータを操作できるようにする道具です。Scout はこの peewee を使って SQLite への読み書きを行っています。軽量でシンプルな設計が Scout の方針と合致しています。

BLOB（ブロブ） Binary Large Object（バイナリ ラージ オブジェクト）の略です。かんたんに言うと、テキスト以外の大きなデータ、たとえば画像・PDF・動画ファイルなどをデータベースに格納するときの呼び方です。Scout はドキュメントに BLOB を添付する機能を持っており、REST API 経由でファイルをアップロード・ダウンロードできます。

WSGI（ウィスキー） Web Server Gateway Interface の略で、Python の Web アプリケーションとサーバーの間をつなぐ標準的な取り決めです。かんたんに言うと、「Python のプログラムをどうやって Web サーバーに接続するか」を統一した規格です。Scout では開発用の簡易サーバーと本番用の gevent WSGI サーバーを使い分けられます。

gevent（ジーイベント） Python の非同期 I/O（入出力）ライブラリです。かんたんに言うと、複数のリクエストが同時に届いても効率よく処理できるようにするための仕組みです。Scout の本番向けコマンド scout_wsgi はこの gevent を使っており、アクセスが集中する環境でも安定して動作します。

REST API（レスト エーピーアイ） Representational State Transfer の略で、Web サービス間でデータをやり取りするための設計スタイルです。かんたんに言うと、HTTP の GET・POST・PUT・DELETE といったメソッドを使って「取得・追加・更新・削除」を表現するシンプルな通信の作法です。Scout はこの REST 設計に従っているため、言語やフレームワークを選ばずどこからでも連携できます。

Scout は「とにかく軽く、すぐ動く」ことを優先した検索サーバーです。大規模なインフラを必要とせず、SQLite 1 ファイルで本格的な全文検索 API が手に入るのは大きな魅力です。ぜひ社内ドキュメントの横断検索や個人開発のナレッジベース構築などに活用してみてはいかがでしょうか。