索引の同期

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

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

1. Webhook（変更のたびに即時）

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

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

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

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

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

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

3. 全件同期

次のタイミングでカタログ全体を同期します。

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

商品数が多いストアでは、数十秒から数分かかります。

索引に入らないもの

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

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

degraded になる期間

索引がまだ使えない間は、レスポンスの degraded が true になります。

degraded_reason	状況
paid_sync_pending	有料プランの初回同期・再構築が未完了
language_sync_pending	多言語ストアの翻訳同期が未完了
starter_product_limit	Free プランの商品数上限を超えている
analyzer_mismatch	ストアの言語設定と解析器が食い違っている
settings_unavailable	設定の読み取りに失敗した（一時的）
search_unavailable	検索基盤の一時障害

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

この表は現時点の主なものです。値はこれ以外にもあり、将来さらに増えます。

値は増えていくため、分岐は degraded（真偽値）で行い、degraded_reason は表示とログにとどめてください。

翻訳の同期

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

---

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