JSON＋KVによるFAQデータ管理と検索インデックス

はじめに

FAQを自サイトに作るとき、最初に決めることになるのが「データをどこに、どんな形で置くか」です。ここを軽く作れるかどうかで、その後の運用の手間が大きく変わります。凝った仕組みにすると1問直すたびに開発の手が必要になりますし、置き場所を決めずに始めると、どのファイルが最新なのか分からなくなります。

この記事では、アパレル・ギア系のECサイトでFAQを内製したときに採用したデータの持ち方を解説します。カテゴリ別のJSONファイル（項目名と値が並んだ、人が読める形式のデータファイル）を元データにして、表示はVercel KV（データを高速に出し入れできる保管場所）から配り、検索は別に作った索引が担う、という三段構えの構成です。データベースを一から組むほどではないけれど、テキストを並べただけでは検索が弱い。その中間を狙った設計になっています。

FAQの中身はカテゴリ別のファイルで持つ

1カテゴリを1ファイルに分ける

扱っているFAQは約10カテゴリ、100問超。これを1つの大きなファイルにまとめると、1問直すだけでもファイル全体を開くことになり、変更箇所も追いにくくなります。そこで「送料・配送」「返品・交換」「会員登録」といったカテゴリごとに1ファイルへ分割しました。カテゴリを増やしたいときは新しいファイルを足すだけ。編集の影響がファイル単位で閉じるので、複数の人が同時に触っても内容がぶつかりにくくなります。

1問に持たせる項目は4つで足りる

FAQ1問に持たせている情報は、識別用の番号、質問文、回答本文、カテゴリ内での並び順の4つです。項目を増やせば表現力は上がりますが、そのぶん管理画面の入力欄も増え、編集する人の負担になります。回答文の中に簡単なリンクや強調を書けるようにしておけば、たいていの説明はこの4項目で足ります。構造を平らに保つと、管理画面からの編集も、変更履歴で差分を見るときも素直になります。

表にすると、FAQ1問はこれだけの情報で成り立っている、ということが分かります。

データベースを組まずにファイルで始めた理由

「FAQのためにデータベースを用意するのは大げさ」というのが正直なところでした。件数は数百件で、更新も毎日発生するわけではありません。ファイルで持てばGit（変更履歴を記録しながらファイルを管理する仕組み）にそのまま載せられるので、いつ・誰が・どこを直したかが自動的に残ります。データベースにありがちな、項目を増やすたびの構造変更作業も発生しません。小さく始めて、件数が増えて困ったら考える。この順番で十分に回っています。

表示用のデータは高速な保管場所から配る

元データはファイル、ユーザーに見せるのはKVから

ファイルは管理には向いていますが、ユーザーがページを開くたびに読み込んで中身を解析するのは効率がよくありません。そこで、ファイルを「これが正しい」という基準のデータとして持ちつつ、実際の表示はVercel KVから引く形にしました。ファイルを更新したらKVへ写し、ユーザーが目にするのは常にKV側のデータです。管理のしやすさと表示の速さを、どちらも諦めずに済みます。

カテゴリ単位で取り出せるようにキーを決める

KVにはカテゴリ単位でデータを載せています。ユーザーが「返品・交換」のページを開いたとき、必要なのはそのカテゴリのFAQだけなので、全100問をまとめて読み込む必要はありません。カテゴリ名を手がかりに、そのひとまとまりを一度で取り出せるようにしておく。取り出す量が小さいほど表示は速くなりますし、カテゴリを増やしても取り出し方は変わりません。

姉妹サイト分もサイト名で分けて持つ

運営していたのは姉妹ECサイトが複数ある環境なので、保管場所にはサイトごとの区別も持たせています。取り出すときの手がかりを「サイト名＋カテゴリ名」にしておけば、同じ仕組みのまま別サイトのFAQを扱えます。サイトを1つ増やしたときにやることは、そのサイト用のファイルを用意して写すだけ。データの形も表示の仕組みも共通なので、サイトごとに作り直す作業は発生しません。

元データを直したら、表示用と検索用の2か所へ写して初めてユーザーの画面に反映される、という流れです。

カテゴリをまたいで探せる索引をもう一つ作る

ユーザーは自分の疑問がどのカテゴリにあるか知らない

カテゴリ分けは管理する側には便利ですが、探す側にとってはそうとも限りません。「返金」について知りたいユーザーは、それが「返品・交換」にあるのか「支払い」にあるのか分からないまま、カテゴリを順番に開くことになります。100問を超えると、この探し方はかなり面倒です。そこで、全カテゴリのFAQをまとめた検索用の索引（本の巻末索引にあたるデータ）を別に用意し、カテゴリを意識せず言葉だけで探せるようにしました。

表記のゆれを吸収する軽い下ごしらえ

索引には、質問文と回答本文の両方を入れています。回答の中にしか出てこない言葉で検索されることも多いためです。あわせて、全角と半角の統一やアルファベットの大文字小文字をそろえるといった軽い整形をかけておくと、検索の当たり方が目に見えて安定します。専用の検索エンジンを立てなくても、この程度の下ごしらえで「打った言葉で見つかる」感覚は十分に作れます。

索引はデータを更新するたびに作り直す

索引はFAQ本体のコピーなので、元データを直したのに索引が古いままだと、検索結果と実際のページの内容がずれます。これを避けるため、データを更新したら索引も必ず作り直す手順にしています。件数が数百件なら作り直しは一瞬で終わるので、差分だけを更新するような凝った作りにはしていません。作り直した索引もKVに載せ、ユーザーが文字を入力するそばから候補を返します。

まとめ

FAQのデータ設計は、カテゴリ別のファイルを元データとして持ち、表示はVercel KVから配り、横断検索は事前に作った索引が担う、という三点で組み立てました。データベースを組むほどではないけれど、テキストを並べただけよりは賢い。数百件規模のFAQには、この程度の重さがちょうど良いバランスでした。

この構成を決めるにあたっては、AIエージェント（AIによる開発支援）に選択肢を洗い出してもらいながら比較しています。非エンジニアでも、判断すべき点さえ整理できれば形にできる範囲です。全体像はFAQシステムの内製をご覧ください。