索引の同期

「商品を追加したのに検索に出ない」を説明します。

まるっと検索は Shopify のデータをそのまま検索するのではなく、自前の索引を持ちます。 索引が現実のカタログとずれないよう、3つの経路で更新しています。

1. Webhook — 変更のたびに即時

商品の作成・更新・削除は Shopify の Webhook で届きます。通常はこれで数秒以内に 反映されます。

受け取っているもの	反映されるもの
products/create	新しい商品
products/update	商品名・価格・在庫・タグ等の変更
products/delete	削除された商品

Webhook は変更があったときにだけ届きます。 アプリが停止していた間の変更は 届かないため、それを補うのが次の2つです。

2. 整合チェック — 6時間ごと

6時間ごとに、索引の件数と Shopify の件数を照合します。 ずれていれば索引を 自動で作り直します。

• マーチャントの操作は不要です。管理画面を開いていなくても走ります
• 照合は商品数を数えるだけなので軽く、作り直しはずれていたショップだけが払います
• 管理画面のトップに、最終同期時刻と照合結果が表示されます

なぜこれが要るのか。 全件同期はマーチャントがボタンを押したときにしか走らず、 間は Webhook が支えています。Webhook は変更時にしか飛ばないので、取りこぼしは 誰かが気づくまで残ります。実際に、49日間にわたって全件同期が走っていないショップ、 一度も走っていないショップが本番で見つかりました。

3. 全件同期

次のタイミングで、カタログ全体を読み直します。

• マーチャントが管理画面で同期ボタンを押したとき
• プランを変更したとき（上位プランで索引される項目が増えるため）
• 整合チェックがずれを検出したとき

商品数が多いストアでは数十秒から数分かかります。この間の検索は degraded が立ちます。

索引に入らないもの

対象	理由
下書き（DRAFT）の商品	ストアフロントで買えないため
非公開の商品	同上
アーカイブ済みの商品	同上

検索結果の件数が Shopify の管理画面の商品数より少ないのは、多くの場合これが理由です。

degraded になる期間

索引がまだ使えない間、レスポンスは degraded: true を返します。

degraded_reason	状況
sync_pending	初回同期またはプラン変更後の再構築が未完了
analyzer_mismatch	ストアの言語設定と解析器が食い違っている
search_unavailable	検索基盤の一時障害

新規ストアは導入初日に必ず sync_pending を通ります。FAQ の該当項目もご覧ください。

degraded_reason の値は将来増えます。分岐は degraded（真偽値）で行い、 degraded_reason は表示とログに留めてください。

翻訳の同期

多言語ストアでは、翻訳も別途同期します。Shopify には翻訳の Webhook が存在しない ため、こちらは定期的な照合だけで維持しています（→ 多言語ストアでの動作）。

---

次に読む: 管理画面でできる調整 — コードを書かずに検索結果を変える