目的
次の 3 つを、PostgreSQL 同梱の pg_trgm による title の trigram 類似度 1 本で実現する。API の形と現在の振る舞いはタスク拡張に書き、このページは設計の理由と比較を残す。
| # | 機能 | 入口 |
|---|---|---|
| ① | 曖昧検索(部分一致・表記ゆれ) | GET /tasks/search(ダッシュボード検索、親タスク・サブタスクの選択 UI) |
| ② | 関連タスク候補 | タスク詳細に「似ているタスク」欄 |
| ③ | 作成時の重複候補 | 作成ダイアログ(CreateTaskDialog.vue)のタイトル入力中に候補を表示 |
検索エンジン(Meilisearch 等)は入れない。別のデータソース・同期ジョブ・認可の再検証・コンテナ運用が増える一方、この 3 機能は trigram で足りる。横断検索(コメント・ドライブ・PR)や意味的な類似が必要になった時点で再検討する。
背景
導入前の search_tasks(handler/src/handlers/task_extensions.rs)は既定で search_vector(to_tsvector('pg_catalog.simple', title || description))を plainto_tsquery で引いていた。問題は次のとおりである。
simple設定は空白・記号でしか語を切らないため、日本語は「ログイン画面の修正」が 1 トークンになる。「ログイン」で検索してもヒットしない- 英語もトークン完全一致のみである。前方一致(
authからauthentication)や typo に弱い - 日本語向けの
USE_PG_BIGM=true分岐は、本番のpostgres:17イメージに pg_bigm が無いので使えない
pg_trgm は contrib 同梱で postgres:17 にそのまま入っており、PG13 以降は trusted extension なので DB への CREATE 権限で CREATE EXTENSION できる(superuser 不要)。テストハーネス(testcontainers の postgres:17)も同じである。
本番での確認
2026-10-20 に dokploy 上の postgres:17.10 を読み取りのみで確認した結果は次のとおりである。
| 項目 | 値 |
|---|---|
| DB ロケール / encoding | en_US.utf8 / UTF8(CJK が trigram 化される条件を満たす) |
pg_trgm |
利用可能(1.6)、未インストール。入っている拡張は plpgsql と pgcrypto のみ |
接続ロール task |
superuser かつ DB owner。CREATE EXTENSION に支障なし |
USE_PG_BIGM |
未設定(tsvector 経路で稼働中)。pg_bigm は利用不可 |
tasks |
478 行(生存 463、日本語タイトル 456)、9 プロジェクト、テーブル全体 4.3 MB、title 平均 32 文字・最大 114 文字 |
| 既存 index | idx_tasks_search_vector(GIN)のみ |
当時の検索の取りこぼしを本番データで比較した。search_vector @@ plainto_tsquery と title/description ILIKE のヒット数は次のとおりである。
| 検索語 | tsvector | ILIKE |
|---|---|---|
| 修正 | 1 | 12 |
| 追加 | 9 | 116 |
| タスク | 4 | 115 |
| レビュー | 3 | 59 |
| 対応 | 25 | 55 |
| GitHub | 44 | 66 |
| PR | 74 | 158 |
日本語の一般語で 1 桁〜10 倍以上の差があり、背景の問題は実データでも確認できた。
全体像
経路は次のとおりである。
① 検索ボックス ③ 作成ダイアログ ② タスク詳細
q title(300ms debounce) title, exclude_task_id=自分
│ │ │
▼ └──────────┬────────────────┘
GET /tasks/search ▼
WHERE に title/description ILIKE GET /tasks/similar
%q% と q <% title を OR │
ORDER BY title 一致 → score ▼
│ service::tasks::find_similar()
│ title % $text(similarity 降順)
└──────────────┬───────────────────────┘
▼
tasks.title + GIN (title gin_trgm_ops) ← migration で pg_trgm 拡張と index を追加①は「検索語がタイトルに含まれるか」(ILIKE、部分一致の保証)と「近似的に含まれるか」(<%、表記ゆれ)、②③は「タイトル同士が全体として似ているか」(%)で、演算子を使い分ける。いずれも GIN gin_trgm_ops が効く。
<%(word_similarity)だけでは部分一致を保証できない。検索語には語境界の空白 trigram が付くため、「ログイン」と「認証ログイン画面」のように日本語の連続文字列の途中にある場合は共有 trigram が減り、既定の 0.6 を下回る。部分一致は ILIKE が担う。
DB
マイグレーション
m20261020000000_tasks_title_trgm.rs が pg_trgm 拡張(IF NOT EXISTS)と GIN index idx_tasks_title_trgm を足す。判断は次のとおりである。
- 対象は title のみである。description は index が大きくなる割に、重複判定・候補提示には title で足りる。description の全文検索は
search_vectorを残す - UNIQUE でない通常の index なので、起動時の SeaORM
sync()(2.0.4)に消されない。AGENTS.md の部分 UNIQUE index の既知の落とし穴には該当しない。sync()は拡張も index も作らないので、migration の適用漏れは補えない。migration の適用自体は e2e CI の起動(e2e/scripts/start-backend.shが実 migration バイナリで適用してから backend を起動)で踏まれ、失敗すれば全ケースが落ちる downは index だけ落とす。拡張はIF NOT EXISTSで既存を流用した可能性があり、他の依存や別ロール所有だとDROP EXTENSIONが失敗するため残す- 通常の
CREATE INDEXは構築中tasksへの書き込みを待たせる。本番 compose のdepends_onは新しい backend の起動を migration 完了まで待たせるだけで、更新デプロイ中は旧 backend とワーカーが動いたまま index が構築される。構築中の書き込み待ちは許容する(title のみの GIN で、本番は 478 行・4.3 MB なので 1 秒未満)。CONCURRENTLYはMigrationTrait::use_transaction()をSome(false)にすれば使えるが、失敗時の INVALID index の片付けが要るので、待ちが問題になる規模になるまで単純なCREATE INDEXを採る - ロケールを検査する。trigram は
lc_ctypeがCだと CJK を英数字とみなさず trigram を作らない。マイグレーション内でSELECT array_length(show_trgm('日本語テスト'), 1)を実行し、NULLか 0 ならエラーで止める。本番はen_US.utf8と確認済みで、検査は他環境(セルフホスト、手元のTEST_DATABASE_URL)向けに残す
テストハーネス
tests/common/mod.rs の ensure_test_env() は sync() で schema を作り、マイグレーションは流さない(search_vector も手で足している)。同じ場所で pg_trgm 拡張と idx_tasks_title_trgm を IF NOT EXISTS で作る。TEST_DATABASE_URL で手元の Postgres を使う場合は、その DB に CREATE 権限が要る。
しきい値
% は pg_trgm.similarity_threshold(既定 0.3)、<% は pg_trgm.word_similarity_threshold(既定 0.6)を使う。既定値で始めた。日本語の短いタイトル(trigram が少ない)で取りこぼすなら、SET LOCAL をクエリと同じトランザクションで発行して下げる。GUC をサーバー側で恒久変更すると、設定が見えない場所に散るので行わない。
service
service::tasks::find_similar(crates/service/src/tasks.rs)が②③の両方を支える。引数は project_id、trim 済みで非空の text、exclude_task_id、limit である。戻りは SimilarTask(id、seq_id、title、score)の並びである。
同じプロジェクトの削除されていない(deleted_at IS NULL)タスクのうち、title % text のものを similarity(title, text) の降順で返す。exclude_task_id があれば除く。score の同値で順序が揺れないよう、search_tasks と同じく id で固定する。プレースホルダは $N で書く(? を書かない。AGENTS.md の既知の落とし穴)。
API
① GET /tasks/search
search_tasks_tsvector の WHERE は、search_vector @@ tsq、title ILIKE、COALESCE(description, '') ILIKE、q <% title の OR である。count と一覧の両方に同じ条件を使う。ずれると total が合わない。ILIKE のパターンは escape_like 済みの %q% である。
tsqはFROM tasks CROSS JOIN plainto_tsquery('pg_catalog.simple', q) AS tsqで 1 回だけ組む。ORDER BY で SELECT の別名は式の中では使えないためである- description の ILIKE は index なし(trigram index は title のみ)だが、
project_idで絞った後の行数なら実用上足りる。これが無いと description にだけ「ログイン画面が崩れる」と書かれたタスクがq=ログインでヒットせず、背景の問題が title でしか直らない。search_tasks_ilike(pg_bigm 経路)と同じ形である - 並び順はタイトル一致(
title ILIKEまたはq <% title)を第 1 キー、GREATEST(ts_rank(search_vector, tsq), word_similarity(q, title))を第 2 キー、id を第 3 キーにする。ts_rank(重み D=0.1、通常 0.1 前後)とword_similarity(0.6〜1.0)は値域が揃わないので、大小で比べない scoreには第 2 キーの値を返す。ILIKE のみで一致した行(2 文字の日本語など)はscoreが 0 になり得る- レスポンス形(
SearchTasksResponse)は変えていない highlight_ilikeのfind_match_char_rangeは、検索語の方が対象文字列より長ければNoneを返す。修正前は範囲外スライスで panic していた(saturating_subが 0 になっても 1 回ループする)。検索語はtrim()しかしないためq="a b"(内部の空白連続、8 文字)が titlea b・description なし(text は 4 文字)に'a' & 'b'で一致して panic し、CatchPanic層が無いので接続が切れた。<%の近似一致(authenticationxxからauthentication)でも到達するので、PR 1 で既存バグの修正として直した。近似一致で部分文字列でない場合は<em>なしで返すUSE_PG_BIGM=trueのsearch_tasks_ilike経路は触らない(ILIKE で既に部分一致する)。分岐の撤去は本件の範囲外である
②③ GET /tasks/similar
呼び方は次のとおりである。
GET /v1/tenants/{tenant_id}/projects/{project_id}/tasks/similar?title=ログイン画面&exclude_task_id=<uuid>&limit=5| パラメータ | 必須 | 既定 | 制約 |
|---|---|---|---|
title |
○ | trim 後に空、または 255 文字(文字数。CreateTaskRequest と同じ)を超えたら 400。長い入力の trigram 比較コストを抑える |
|
exclude_task_id |
なし | 自タスクを除く(②用) | |
limit |
5 | 上限 20(超過は 20 に丸める。search の min(100) と同じ流儀) |
レスポンスの例は次のとおりである。
{ "tasks": [ { "id": "uuid", "seq_id": 42, "title": "ログイン画面の修正", "score": 0.58 } ] }- 認可は
search_tasksと同じで、Scope::ReadTask+ensure_tenant_access(tenant_id, Some(project_id))である。候補は同一プロジェクト内に限る(project_idで WHERE)。テナント内の他プロジェクトは出さない(権限表が増えるのを避ける。必要になったら別途) - DTO は
payload::task_extensionsのSimilarTasksQuery/SimilarTaskHit/SimilarTasksResponseである。レスポンス DTO にはDeserializeも付ける(CLI 規約)。スキーマはroutes!から自動収集されるので手登録は不要である - routes は
tenants.rsの/{project_id}/tasksnest にsearch_tasksと並べて登録する(#[utoipa::path]は nest からの相対パス/similar)。/{task_id}より静的セグメントが優先されるので順序は問題にならない GET /tasks/{task_id}/similarは作らない。③の時点ではタスク id が無く、1 本で両方を賄える
フロントエンド
composable useSimilarTasks({ tenantId, projectId, title, excludeTaskId }) を共通で使い、title が trim 後 2 文字未満なら enabled: false にする。型は openapi.json の再生成(pnpm openapi と vp fmt)で付く。画面ごとの扱いは次のとおりである。
| 画面 | 扱い |
|---|---|
③ CreateTaskDialog.vue |
タイトル入力を 300ms debounce(tasks/+Page.vue の SEARCH_DEBOUNCE_MS と同じ手法)して問い合わせる。タイトル欄の下に最大 5 件を表示する。作成はブロックしない(注意喚起のみ。取得失敗時も作成できる)。TaskTitleLink と taskDetailHref は表示用の tenant ID を使い、ダイアログは API 用 UUID の tenantId しか持たないので、ダイアログ内で usePageContext().routeParams.tenant を読む(他の component 層でも使っている手法。これで DashboardCreateTask.vue / HomeDashboard.vue の変更が不要)。TaskTitleLink は通常クリックで遷移せず select を emit するので、ダイアログ側で受けて navigate(taskDetailHref(tenantDisplayId, projectKey, seqId)) し、ダイアログを閉じる |
| ② タスク詳細 | 「似ているタスク」欄である。TaskDetailHub.vue は tenant id を受け取っていないため、Hub 内ではなく呼び出し側が既存の main slot に置く。tasks/@taskId/+Page.vue では select で navigate、TaskDetailPane.vue では既存の open-task-ref emit に繋ぐ(ペイン内でタスクを切り替える既存経路)。形は { projectKey, seqKey, href } なので、候補の seq_id から taskSeqKey() と taskDetailHref() で組み立てる(open-task は TaskResponse 全体を要求するので候補では使えない)。title に現在のタイトル、excludeTaskId に自分の id を渡す。0 件なら欄ごと非表示にする |
| ① | 変更なし(同じエンドポイント) |
古い応答は見せない。TanStack Query は enabled: false にしてもキャッシュ済みの data を返すので、無効化では消えない。query key に tenant / project / title / excludeTaskId を全部含め(key が変われば data は新しい key のものになる)、遅れて届いた旧応答は旧 key に保存されて表示されない。残る隙間は debounce 中の 300ms だけなので、表示条件は「ダイアログが開いている ∧ debouncedTitle === title.trim() ∧ 2 文字以上」にする。詳細のタスク切替も key が変わるので持ち越さない。
DashboardCreateTask.vue は同じ CreateTaskDialog を開くので、③の変更がそのまま効く。
実装の段階
実装は次の 3 段に分けた。PR 2 と 3 は 1 本にまとめてよいとした。API 単体では利用者が居ないためである。
| PR | 内容 |
|---|---|
| 1 | migration + ハーネス + search_tasks の変更 + 回帰テスト(①) |
| 2 | find_similar + GET /tasks/similar + 統合テスト + openapi.json |
| 3 | フロント(③ 作成ダイアログ、② 詳細欄)+ unit テスト |
未実装と既知の制限
- 短い語の typo は拾えない(
OAtuhとOAuthは共有 trigram が少ない)。trigram の性質で、主な改善は部分一致と長めの語の表記ゆれである - 意味的な類似(「ログインできない」と「サインイン失敗」)は対象外である。必要になれば埋め込み + pgvector だが、埋め込み API・pgvector 入りイメージ・更新ジョブが要るため別設計とする
- しきい値の調整は実データで 1 回確認が要る(しきい値)
- 性能。GIN は候補抽出までで、類似度順の上位 N 件は候補全件を採点してソートする。短い語・頻出語(「修正」など)で候補が膨らむプロジェクトがあり得る。さらに 2 文字の
ILIKE '%画面%'は検索側の trigram を抽出できず、GIN の絞り込みが効かない(全 index スキャン + recheck)。本番は 478 行・9 プロジェクトなので当面は問題にならない。「2 文字の語」「頻出語」「他プロジェクトに大量の行がある状態」の 3 ケースでEXPLAIN ANALYZEを取り、遅ければ GiST(<->の KNN 順序付けが効く)や 3 文字未満の ILIKE 省略を検討する - ロケール。DB の
lc_ctypeがCだと日本語で効かない。本番はen_US.utf8を確認済みで、他環境は migration のロケール検査で起動前に検出する
レビューで見送った指摘
2026-10-20 の設計レビュー(Codex gpt-6.1-sol)で挙がったが、採らなかったものを再検討の材料として残す。
| 指摘 | 見送った理由 |
|---|---|
「migration、sync()、再起動」を通して index と拡張が維持されることを検証するテスト(専用ハーネス、または e2e への 1 ケース追加) |
sync() が落とすのは UNIQUE index だけで拡張は触らない(sea-orm 2.0.4 schema/builder.rs)ことはソースで確認済み。migration の適用は既存 e2e の起動で踏まれ、失敗すれば全ケース落ちる。e2e は現状 users しか seed せず検索 UI までの fixture も無いので 1 ケースでは済まず、index の有無は検索結果に出ないので index の検証にもならない |
ハーネスでの show_trgm('日本語テスト') 非空テスト |
ロケールの保証はマイグレーション内の show_trgm 検査が担う。①の日本語部分一致テストでは代わりにならない(ILIKE の条件がロケール C でも一致するので、trigram が作られなくても通る)。負のケース(C ロケールで migration が止まる)は手元では試験しない |
| GiST index への変更 | 性能問題が実測で出てから判断する(未実装と既知の制限) |
CREATE INDEX CONCURRENTLY |
sea-orm-migration 2.0.4 では use_transaction() を Some(false) にすれば実装できる。ただし失敗時に INVALID index が残る片付けが要り、更新デプロイ中に旧 backend が動いたまま構築されても title のみの GIN で現状の件数なら書き込み待ちは秒単位なので、単純な CREATE INDEX を採る。待ちが問題になる規模になったら切り替える |
| PAT のテナント・プロジェクト束縛や project-only guest の許可範囲の網羅試験 | search_tasks と同じ ensure_tenant_access を通すので新しい認可規則は増えない。既存の認可テストが担う範囲を重複して書かない。ReadTask 無し PAT の 403 と別テナント project id の拒否だけテストに足した |
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-10-20 | Meilisearch 等の外部検索エンジンは導入しない。pg_trgm で 3 機能を実現する | 別のデータソース・同期ジョブ・認可の再検証・コンテナ運用が増える一方、3 機能は trigram で足りる |
| 2026-10-20 | 類似候補は同一プロジェクト内に限る。テナント横断は行わない | 権限表が増えるのを避ける |
| 2026-10-20 | ②③は GET /tasks/similar の 1 本で賄い、/{task_id}/similar は作らない |
③の時点ではタスク id が無く、1 本で両方を賄える |
| 2026-10-20 | trigram index は title のみ。description は従来の tsvector のまま | description は index が大きくなる割に、重複判定・候補提示には title で足りる |
| 2026-10-20 | 部分一致の保証は ILIKE(title と description、description は index なし)、表記ゆれは <% で担う |
<% だけでは日本語の中間一致を取りこぼす |
| 2026-10-20 | migration の down は index だけ落とし、pg_trgm 拡張は残す |
拡張は既存を流用した可能性があり、他の依存や別ロール所有だと DROP EXTENSION が失敗する |
| 2026-10-20 | 初回 index 構築中の tasks への書き込み待ちを許容する。旧 backend の停止は要求しない |
title のみの GIN で、本番は 478 行・4.3 MB なので 1 秒未満 |
| 2026-10-20 | 類似候補の UI は TaskDetailHub 内ではなく呼び出し側に置く。クリックはページでは遷移、ペインでは open-task-ref |
TaskDetailHub.vue は tenant id を受け取っていない |
