AIものさし

Cloud Firestoreの複合クエリでMissing indexが出たとき、必要な索引を安全に作る

Cloud Firestoreの複合クエリがMissing indexで失敗したら、エラーに表示された作成リンクを手掛かりにしつつ、クエリ条件と既存の索引定義を先に照合します。

AIものさし編集部

Cloud Firestoreの複合クエリがMissing indexで失敗したら、エラーに表示された作成リンクを手掛かりにしつつ、クエリ条件と既存の索引定義を先に照合します。Consoleの提案をそのまま作成するのではなく、対象Database、CollectionまたはCollection group、各fieldの順序・mode、配列条件を確認してください。Indexの構築中はqueryがまだ実行できないことがあるため、構築完了を確認してから同じ条件で再試験します。

すでに firestore.indexes.json などをsource controlで管理しているProjectでは、Consoleだけで索引を追加すると、Consoleとrepositoryの定義がずれるおそれがあります。チームの管理方法に合わせて定義を更新し、正しいProjectへ反映してください。必要な索引を作る権限がない場合は、error linkを共有するだけでなく、query例・環境・提案される定義を管理者へ渡します。

目次

Missing indexを読み解く

Cloud Firestoreはqueryを支えるindexを使って結果を取得します。単一fieldで実行できる基本queryには自動作成されるindexがありますが、複数fieldを組み合わせるqueryなどでは手動の複合indexが必要になる場合があります。必要なindexがないと、Firestoreはエラーとともに作成用のConsole linkを返すことがあります。このlinkは失敗したqueryに対する候補を示すため、診断を早めますが、アプリケーションの全体設計や環境別管理を検証したものではありません。

まずエラー全文を保存し、次を記録します。

  1. Firebase Project IDとFirestore Database ID。複数Databaseがある場合は (default) と別Databaseを区別する。

  2. Collection pathと、通常のcollection queryかcollection group queryか。

  3. queryの where 条件、array-contains / array-contains-any 条件、orderBy、範囲条件、SDK。

  4. エラーが出た環境（開発・検証・本番）と、再現した操作。

  5. 提案されたindexのfield、順序、fieldごとのindex mode、scope。

実際の文書データや秘密情報が含まれる場合は、エラー全文を公開Issueへ貼らず、Project ID等も共有相手に必要な範囲へ限定します。Index作成は対象Databaseの読み取り・検索動作と保存量に影響し得るため、意図したProjectを間違えないことが重要です。

Queryから必要なindexを読み取る

複合indexは、対象collectionに対してどのfieldをどの順序・modeで索引化するかを定義します。Queryのfilterとsort orderが変われば、同じfield集合でも別のindexが必要なことがあります。field名だけを比べて「同じ索引」と判断しないでください。

表は横にスクロールできます

Queryの要素Index定義で見ること確認ポイント
collection / collection groupCollection名とquery scopeサブコレクションをまたぐgroup queryか、1 collection内か
等価条件（== や in など）対象fieldとindex mode提案と既存indexがどのfieldに対応するか
配列条件array-contains 等のarray mode1つの複合indexで扱えるarray field数に制約がある
範囲・不等価条件対象fieldと方向範囲条件が複数ある場合、query orderとの関係も確認
orderByfield順と昇順・降順sort directionの違いは別indexになり得る
複数のsort / range条件fieldの順序全体不等価fieldとorderByの並びをqueryと照合する

Firestoreのindex定義ではfield順序が意味を持ちます。一般に複合indexは等価条件に使うfield、sort order、range/inequality条件などから構成され、Firestoreはqueryのcollection、filter、operator、sort orderに合うindexを選びます。個々のqueryでどの順序が必要かは、画面の提案と公式のindex仕様を照合してください。記事だけから具体的なfield名やindex設定を推測してはいけません。

たとえば、仮に status == "open" と createdAt >= ... で絞り、createdAt の昇順で並べるqueryを考えます。ここで status と createdAt の2fieldが必要だとだけ考えると、descending sortやcollection group scopeの違いを見落とします。実際には、queryに記述したscope、演算子、field directionをConsoleの候補と一つずつ対応させます。この例はindexの構造を説明するための架空例であり、特定アプリの設定や測定結果ではありません。

Consoleの作成リンクを安全に確認する

エラーリンクを開く前に、リンク先のProjectとDatabaseが期待した対象か確認します。Firebase Consoleで提案されたcollection、field、mode、scopeが実際のqueryと一致するか確認し、必要な場合だけCreateを実行します。別環境のリンクや古いログから開いたリンクを、そのまま本番へ作成しないでください。

Consoleで作成するときの確認順：

  1. Project名とProject IDを確認する。

  2. Databaseを選び、正しい (default) または指定Databaseであることを確認する。

  3. collectionまたはcollection groupをqueryコードと照合する。

  4. 提案されたfield名、順序、昇順・降順、array mode、query scopeを照合する。

  5. 既存Index一覧に同じ定義がないか、または同じqueryが既存定義で実行できないかを見る。

  6. チームがsource controlでindexを管理しているなら、Consoleでの直接作成前にその運用に従う。

  7. Create後はIndex状態を確認し、構築完了を待つ。

エラーがvector indexを要求する場合は、通常の複合indexとは作成手順が異なることがあります。エラーに含まれるGoogle Cloud CLI command等を使う前に、対象Project、Database、field、vector設定を確認します。vector fieldがあるというだけで、通常のcomposite index画面へ同じ操作を適用しないでください。

source controlで管理している場合

Projectに firestore.indexes.json または別Database用のindex設定ファイルがあるなら、そこがチームの正本になっているか確認します。複数Databaseでは、firebase.json がDatabaseごとのrules・index fileを対応づける構成もあります。ローカルファイルが存在するだけでは、それが現行Projectに使われる正本とは限りません。branch、CLI設定、Firebase Project alias、対象Databaseの対応を確認してください。

Consoleで作ったindexを後からファイルへ書き戻す場合、既存の定義を消さないようにします。CLIで現在のindexを取得できる場合も、対象ProjectとDatabaseを明示し、取得内容とrepository上の差分を比較してから変更します。設定ファイルの追加・削除をそのままdeployすると、意図しないindex変更が発生することがあります。既存indexを一括置換せず、必要な定義だけを追加する方針にします。

CLIを使う場合は、実行前に firebase.json、Project alias、index fileのパス、コマンドの適用範囲を確認してください。Firestoreのdeploy操作はプロジェクト設定に応じてindex以外のFirestore資源を扱う可能性があるため、「indexだけを更新する」と推測して実行しないこと。利用するCLIの正確なoptionと対象範囲は、現行Firebase CLI公式資料・チームrunbookで照合します。実Projectを見ずにコマンドを実行する必要はありません。変更はレビュー可能な差分にし、production向けなら通常の承認・リリース手順を通します。

IndexのBuilding中と作成エラー

Indexを作成すると、Firestoreは定義を準備し、既存データをbackfillします。データ量などによって所要時間は変わり、作成開始直後は状態がBuildingになることがあります。Building中のquery失敗を、設定が間違っていると即断しないでください。ConsoleのIndexes画面で状態を確認し、構築が完了したことを確認してから再試験します。数分で終わるとは限らず、データ量により時間が延びることがあります。

作成がFailedになった場合、表示されたエラーとlimit情報を保存します。Firestore公式資料ではindex buildが失敗する原因の一例として、文書あたりのindex entry上限などの制約が挙げられています。作成を何度も繰り返すのではなく、対象collection、field数、データ、index limit、権限、対象Projectを確認し、問題が解消してから再試行します。Indexを追加すると保存量や費用にも関わるので、不要な候補を無制限に作らないでください。

失敗原因を分けるチェックリスト

Error linkが開かない、または権限エラーになる

  • linkのProject IDと現在のConsoleのProjectが一致するか。

  • 正しいGoogleアカウント・組織・Projectへアクセスしているか。

  • Indexの作成・参照に必要なIAM権限があるか。

  • IAM管理者へ渡すときは、エラー内容、query、Database、提案indexを添え、credentialやユーザーデータを外さない。

Consoleでindexを作成する権限として、公式資料はDatastore Owner、Index Admin、Editor、Owner等のroleを挙げています。組織の最小権限方針がある場合は、広いOwner/Editor権限を自動で求めず、必要permissionを管理者と確認してください。独自roleでは必要permissionの組み合わせを確認します。

Indexの構築完了後も同じqueryが失敗する

  • 別Project、別Database、別collection pathに接続していないか。

  • queryのfilter、orderBy、scopeが、作成したindexと一致しているか。

  • Queryコード変更後、別のfield順やdirectionが必要になっていないか。

  • 使用SDKのqueryが、画面で想定した条件と同じか。

  • 既存エラーが古いものでないか。最新のエラーを再取得する。

Index作成後に結果が以前と違う

Indexはqueryを実行するための索引であり、アプリケーションの期待するbusiness logicやデータの完全性まで保証するものではありません。特に orderBy は指定fieldが存在する文書だけを結果に含める性質があるため、indexを作った後もquery条件・データ欠損・結果件数を確認します。作成前後で同じfixtureまたは安全な検証データを用い、queryの結果と件数を比較してください。

完了判定と再試験

作業記録に次の情報を残します。

  • Project ID（社外へ共有する記録なら必要範囲に限定）

  • Database ID、collection / collection group

  • Queryのfilter、array条件、orderBy

  • 作成したindexのfield順序、各mode、scope

  • Index状態（構築中・完了・エラー等のConsole表示）

  • 作成手段（Consoleまたはsource-controlled config経由）

  • 再試験したquery、結果、確認日時

  • 既存index設定ファイルとの同期状況

完了は、indexの構築状況を確認するだけではありません。該当する同じqueryが意図した環境で実行できること、結果が期待に合うこと、他の既存queryを壊していないことを確かめて完了とします。権限がない、Projectを識別できない、source of truthの管理方法が不明、または本番設定の変更が必要な場合は、その場で勝手に作成せず、必要情報と提案indexを管理者へ渡します。

この記事で確認できていないこと

特定のFirebase Project、Database、query、現行index一覧、source-controlled config、IAM権限は確認していません。したがって本文は一般的なトラブルシューティングであり、読者のMissing index errorにどのfieldを追加すればよいかを断定するものではありません。実際のerror linkまたはquery定義をもとにProject担当者が確定してください。

Sources