はじめに
SQLiteの全文検索(FTS5)で日本語を検索したら、登録したはずの言葉が0件——原因はトークナイザです。既定の unicode61 は空白や記号で区切るため、日本語の連続した文字列を1つのトークンとして扱います。
この記事では、unicode61 と trigram を同じデータで比較し、日本語検索の条件を実測します。
環境
- Windows 11(ビルド 10.0.26200)
- Python 3.11.5
- SQLite 3.42.0(Python同梱)
やったこと
1. テストデータを用意する
import sqlite3
docs = [
("Ollama入門", "ローカルLLMをWindowsで動かす"),
("SQLite backup", "WALモードの安全なバックアップ"),
("Python logging", "RotatingFileHandlerでログを回転"),
]
2. unicode61で検索する
con = sqlite3.connect(":memory:")
con.execute("CREATE VIRTUAL TABLE docs USING fts5(title, body, tokenize='unicode61')")
con.executemany("INSERT INTO docs(title, body) VALUES (?, ?)", docs)
for q in ["バックアップ", "Windows", "ログ"]:
rows = con.execute("SELECT title FROM docs WHERE docs MATCH ?", (q,)).fetchall()
print(q, rows)
結果:
バックアップ []
Windows []
ログ []
すべて0件です。unicode61 は日本語を単語分割しないため、body 全体が1つのトークンになり、部分一致ではヒットしません。
3. trigramで検索する
con = sqlite3.connect(":memory:")
con.execute("CREATE VIRTUAL TABLE docs USING fts5(title, body, tokenize='trigram')")
con.executemany("INSERT INTO docs(title, body) VALUES (?, ?)", docs)
for q in ["バックアップ", "Windows", "ログを回", "回転"]:
rows = con.execute("SELECT title FROM docs WHERE docs MATCH ?", (q,)).fetchall()
print(q, rows)
結果:
バックアップ [('SQLite backup',)]
Windows [('Ollama入門',)]
ログを回 [('Python logging',)]
回転 []
trigram は3文字以上の部分一致でヒットします。ただし 2文字の「回転」は0件でした。trigramは名前の通り3文字単位で索引を作るため、2文字以下のクエリはヒットしません。
4. 2文字検索の回避策
2文字の検索が必要なら、次のいずれかを選びます。
- クエリに1文字足して3文字以上にする(例: 「ログ回転」)
-
LIKE '%回転%'にフォールバックする - 形態素解析したトークンを別カラムに保存する(外部ライブラリが必要)
# trigramでヒットしない短いクエリはLIKEへ
def search(con, q: str):
if len(q) >= 3:
return con.execute(
"SELECT title FROM docs WHERE docs MATCH ?", (q,)
).fetchall()
return con.execute(
"SELECT title FROM docs WHERE body LIKE ?", (f"%{q}%",)
).fetchall()
5. 日本語のtrigramで注意すること
trigram は大文字小文字を区別しませんが、空白を含むクエリや記号だけのクエリは扱いが変わります。検索対象の表記ゆれ(全角・半角、ひらがな・カタカナ)は別途正規化が必要です。
import unicodedata
def normalize(text: str) -> str:
return unicodedata.normalize("NFKC", text).lower()
ハマった点
既定のトークナイザを確認しない
CREATE VIRTUAL TABLE ... USING fts5(...) でトークナイザを省略すると unicode61 になります。日本語データを入れる前に、必ず tokenize= を指定します。
trigramは2文字で0件
「回転」「バック」のような2文字クエリはヒットしません。UIの検索ボックスで2文字を許すなら、LIKEフォールバックか「3文字以上」の案内が必要です。
インデックスはテーブル作成時に決まる
トークナイザを後から変えるには、テーブルを作り直して再投入します。データ量が多い場合は、移行手順を先に決めます。
まとめ
-
unicode61は日本語を単語分割せず、部分一致で0件になる。 -
trigramは3文字以上の部分一致でヒットする。 - 2文字クエリはtrigramで0件。LIKEフォールバックなどを用意する。
- トークナイザはテーブル作成時に指定する。
- 表記ゆれはNFKC正規化などで別途吸収する。