Firestore 2026.1 Import: Merge vs Overwrite Ambiguity

Answer to the Questions

1. Default behavior when IDs overlap

• During a Firestore import, any document in the export that has the same collection/document path as a document already present in the target database will be overwritten entirely.
• Only the fields that exist in the exported document replace the target document; fields that were present in the target but not in the export are removed.
• Documents that do not exist in the target are added normally, so the final state is the union of the export set and the original set, with export‑side documents taking precedence on ID collisions.

2. Options to change the behavior

• The gcloud firestore import command and the Firebase Console import UI expose no flags or UI controls for merge‑only or skip‑duplicates modes.
• Only options available are specifying --database, --async, and an optional --output-uri-prefix for operation logging.
• To achieve a merge‑only or skip‑duplicates strategy, you must perform a custom import script using the Admin SDK or the Firestore REST API.

3. Recommended verification steps

• After the import completes, run a gcloud firestore export on the target database to a new GCS bucket.
• Compare the SHA‑256 checksums of the original export bucket and the new export bucket. Matching checksums confirm an exact byte‑for‑byte match.
• Alternatively, compare export.overall_export_metadata counts with the target collection counts using the Admin SDK:

const admin = require('firebase-admin');
admin.initializeApp();
const db = admin.firestore();

async function verifyCounts() {
  const meta = await db.collection('export').doc('overall_export_metadata').get();
  const counts = meta.data().collection_counts;
  for (const [col, expected] of Object.entries(counts)) {
    const actual = (await db.collection(col).get()).size;
    console.log(col, 'expected', expected, 'actual', actual);
  }
}
verifyCounts();

For field‑level assurance, export both databases to JSON (using the emulator or a custom script) and run a diff tool. This catches any unexpected field deletions or additions.

How to Poll an Import Operation

gcloud firestore operations describe <operation-name>

Replace <operation-name> with the name returned by the import command. The operation status will be DONE when the import finishes.

When to Use a Custom Import Script

If you need to preserve certain fields, skip duplicates, or perform a merge‑only import, write a small script that reads the export files (JSON or protobuf) and writes to Firestore using the Admin SDK’s set with merge:true or delete logic as required.

Always run such scripts on a staging instance first to validate the logic.