Firexport / Anleitungen

Ein Firestore-Dokument umbenennen (seine ID ändern)

Firestore kann ein Dokument nicht umbenennen. Die ID eines Dokuments ist Teil seines Pfads, und weder die Firebase Console noch die SDKs bieten eine Möglichkeit, sie zu ändern. Umbenennen heißt, das Dokument unter der neuen ID neu anzulegen und das alte zu löschen – zusammen mit allem in seinen Untersammlungen, die beim Löschen eines Dokuments unberührt bleiben. Es gibt drei Wege dafür. Welcher passt, hängt davon ab, wie viel unter dem Dokument liegt.

Aktualisiert am 27. Oktober 2026. Firexport, die Erweiterung in Methode 1, ist von uns. Die Methoden 2 und 3 brauchen sie nicht.

1. Mit Firexport die ID in der Firebase Console ändern

Firexport ist eine kostenlose Chrome-Erweiterung, die dem ⋮-Menü jedes Dokuments in der Panelansicht von Firestore den Eintrag Dokument-ID ändern hinzufügt. Sie verschiebt das Dokument und alles in seinen Untersammlungen in einem einzigen Schreibvorgang zur neuen ID – es passiert also alles oder nichts. Es schreibt mit einem Google-Konto, das Sie verbinden – kein Dienstkontoschlüssel und kein Code einzurichten.

1. Installieren Sie Firexport aus dem Chrome Web Store.
2. Öffnen Sie in der Firebase Console Firestore Database > Daten (Data) in der Panelansicht (Panel view) und klicken Sie auf die Sammlung, die das Dokument enthält.
3. Fahren Sie in der Liste mit der Maus über das Dokument, klicken Sie auf das ⋮, das links neben seiner ID erscheint, und dann auf Dokument-ID ändern.
4. Beim ersten Mal verlangt das Fenster, dass Sie Ihr Google-Konto verbinden: Klicken Sie auf Google-Konto verbinden, wählen Sie das Konto, das in der Console angemeldet ist, und erlauben Sie den Zugriff im Fenster von Google.
5. Tragen Sie die ID unter Neue Dokument-ID ein und klicken Sie auf ID ändern. Ein Dokument ohne Untersammlungen wird sofort verschoben.
6. Hat es Untersammlungen, liest Firexport sie zuerst und zeigt, wie viele Dokumente verschoben werden, wie viele Schreibvorgänge das braucht und wie viele Lesevorgänge die Prüfung gekostet hat. Klicken Sie auf Verschieben. Die Console öffnet dann das Dokument unter seiner neuen ID.

Was ein Verschieben verhindert

• Ein Dokument, das es unter der neuen ID oder darunter schon gibt. Firexport überschreibt nie: Der Schreibvorgang wird abgelehnt, und nichts ändert sich.
• Eine Änderung an einem der Dokumente, nachdem Firexport sie gelesen hat. Sonst landete der alte Inhalt unter der neuen ID, während der neue Inhalt gelöscht würde. Deshalb wird nichts geschrieben, und Sie können es erneut versuchen.
• Mehr als 250 Dokumente oder mehr, als ein Schreibvorgang tragen kann (10 MiB). Firexport hält an, bevor etwas geschrieben wird; nutzen Sie Methode 2.
• Eine ID, die Firestore nicht erlaubt: eine, die / enthält, nur aus . oder .. besteht, mit __ beginnt und endet oder mehr als 1.500 Byte lang ist. Leerzeichen am Anfang oder Ende gehören zur ID, deshalb behält das Feld sie.

Jedes Feld behält genau seinen Wert und Typ, denn Firexport schreibt, was es aus Firestore gelesen hat, und nicht, was die Console anzeigt. Die Schreibvorgänge nutzen die Berechtigungen des verbundenen Kontos, daher gelten die Sicherheitsregeln nicht. Die Dokumente gehen von Ihrem Browser direkt zu Google und nie zu uns. „Dokument-ID ändern“ ist in jedem Tarif kostenlos.

Ändern Sie die ID eines Firestore-Dokuments direkt in der Console – samt Untersammlungen, in einem Schreibvorgang.

Zu Chrome hinzufügen – kostenlos

2. Mit einem Admin-SDK-Skript verschieben

Für ein Dokument mit mehr als 250 Dokumenten darunter oder um viele Dokumente umzubenennen, erledigt ein Node.js-Skript mit dem Firebase Admin SDK dasselbe Verschieben. Das Skript unten liest das Dokument und jede Untersammlung darunter, legt dann jedes davon unter dem neuen Pfad an und löscht die alten. Der neue Pfad kann auch in einer anderen Sammlung liegen, dasselbe Skript verschiebt also auch Dokumente. Es braucht ein Konto, das in Firestore schreiben darf: einen Projekt-Inhaber oder -Bearbeiter oder die Rolle Cloud Datastore-Nutzer.

1. SDK installieren: npm install firebase-admin
2. Für lokale Anmeldedaten anmelden: gcloud auth application-default login. Auf einem Server lassen Sie stattdessen GOOGLE_APPLICATION_CREDENTIALS auf einen Dienstkontoschlüssel zeigen.
3. Speichern Sie das Skript unten als rename-document.mjs, ersetzen Sie your-project-id und führen Sie node rename-document.mjs users/alice users/alice-smith aus.

// Usage: node rename-document.mjs users/alice users/alice-smith   → moves users/alice and everything under it
// Firestore has no rename: this creates the document at the new path with all its subcollections, then deletes the old ones.
import { initializeApp } from 'firebase-admin/app';
import { getFirestore } from 'firebase-admin/firestore';

initializeApp({ projectId: 'your-project-id' });
const db = getFirestore();
db.settings({ useBigInt: true }); // integers past 2^53 would otherwise lose their last digits on the way through
const [from, to] = process.argv.slice(2);
if (!from || !to) throw new Error('Usage: node rename-document.mjs <document path> <new document path>');
if (to === from || to.startsWith(`${from}/`)) throw new Error('The new path must be outside the document you move');

// true: one batch, so every write happens or none does (up to 10 MiB of data in all).
// false: for more than that. Copies everything first and deletes the old documents only once every copy is written.
const ONE_BATCH = true;

// The document and every document under it, in subcollections of subcollections too. listDocuments() also returns
// places that have subcollections but no fields, so the walk reaches what is under them; the places themselves aren't copied.
async function collect(ref, found) {
  const snapshot = await ref.get();
  if (snapshot.exists) found.push(snapshot);
  for (const collection of await ref.listCollections()) {
    for (const child of await collection.listDocuments()) await collect(child, found);
  }
  return found;
}

const docs = await collect(db.doc(from), []);
if (docs[0]?.ref.path !== from) throw new Error(`${from} doesn't exist`);
const target = (doc) => db.doc(to + doc.ref.path.slice(from.length));

if (ONE_BATCH) {
  // create() fails if a document is already at the new path, and lastUpdateTime fails if one changed after it was read.
  // Either way Firestore rejects the whole batch and nothing is written.
  const batch = db.batch();
  for (const doc of docs) batch.create(target(doc), doc.data());
  for (const doc of docs) batch.delete(doc.ref, { lastUpdateTime: doc.updateTime });
  await batch.commit();
} else {
  // BulkWriter keeps under Firestore's rate limits and retries what can be retried, but it isn't all or nothing.
  const writer = db.bulkWriter();
  const failures = [];
  for (const doc of docs) {
    writer.create(target(doc), doc.data()).catch((error) => failures.push(`${doc.ref.path}: ${error.message}`));
  }
  await writer.flush();
  if (failures.length) {
    failures.forEach((failure) => console.log(failure));
    throw new Error('Some copies failed, so nothing was deleted. Delete the copies that were written, then try again.');
  }
  for (const doc of docs) {
    writer.delete(doc.ref, { lastUpdateTime: doc.updateTime }).catch((error) => failures.push(`${doc.ref.path}: ${error.message}`));
  }
  await writer.close();
  failures.forEach((failure) => console.log(`Not deleted, ${failure}`));
}
console.log(`Moved ${docs.length} documents from ${from} to ${to}`);

• listDocuments() liefert auch eine Stelle, die Untersammlungen, aber keine eigenen Felder hat – die kursiven IDs in der Console –, sodass das Skript die Dokumente darunter erreicht. Die Stelle selbst wird nicht kopiert: Sie erscheint unter dem neuen Pfad, sobald ihre Untersammlungen dort sind.
• Ist ONE_BATCH eingeschaltet, landen alle Anlege- und Löschvorgänge in einem Batch. Existiert unter dem neuen Pfad schon ein Dokument oder hat sich eines geändert, nachdem das Skript es gelesen hat, lehnt Firestore den Batch ab, und nichts wird geschrieben.
• Ein Batch kann bis zu 10 MiB tragen. Für einen größeren Baum setzen Sie ONE_BATCH auf false: Das Skript kopiert dann alles mit BulkWriter und löscht die alten Dokumente nur, wenn jede Kopie geschrieben wurde. Das ist nicht alles oder nichts, schreiben Sie also nicht in diese Dokumente, solange es läuft.
• Wie Methode 1 umgeht es die Sicherheitsregeln. Zeitstempel, Referenzen, Geopunkte und Bytes behalten ihre Typen, und useBigInt sorgt dafür, dass Ganzzahlen über 2⁵³ exakt bleiben. Eines kann das Admin SDK nicht bewahren: Ein Double-Wert ohne Nachkommastellen wie 2.0 wird als gewöhnliche Zahl gelesen und als Ganzzahl 2 zurückgeschrieben.

3. Von Hand in der Console kopieren

Für ein Dokument mit wenigen Feldern und ohne Untersammlungen reicht die Console allein. Das sind zwei Schreibvorgänge, die nicht miteinander verknüpft sind, und Sie tippen jeden Wert neu ein.

1. Öffnen Sie das Dokument und notieren Sie Name, Typ und Wert jedes Felds.
2. Klicken Sie in derselben Sammlung auf Dokument hinzufügen (Add document), geben Sie die neue ID unter Dokument-ID (Document ID) ein und fügen Sie dieselben Felder mit denselben Typen hinzu. Klicken Sie auf Speichern (Save).
3. Prüfen Sie das neue Dokument, öffnen Sie dann das ⋮-Menü des alten und klicken Sie auf Dokument löschen (Delete document).

Achten Sie dabei auf die Typen: Eine Zahl, die in ein String-Feld getippt wird, bleibt ein String, und ein Zeitstempel muss mit dem Typ Zeitstempel neu eingegeben werden. Untersammlungen kommen nicht mit. Jede müsste auf dieselbe Weise kopiert werden, ein Dokument nach dem anderen.

Was eine neue ID ändert

Egal, auf welchem Weg Sie es verschieben: Das Dokument unter der neuen ID ist ein neues Dokument. Daraus folgt einiges.

• Erstellungszeit. Jedes verschobene Dokument erhält eine neue Erstellungs- und Aktualisierungszeit.
• Referenzen. Referenzfelder in anderen Dokumenten zeigen weiter auf den alten Pfad, ebenso als String gespeicherte IDs wie eine ownerId. Aktualisieren Sie sie selbst.
• Cloud Functions und Listener. Jedes verschobene Dokument löst die Trigger für Erstellen und Löschen aus, und Apps mit einem Listener auf der Sammlung sehen, wie ein Dokument entfernt und ein anderes hinzugefügt wird.
• Kosten. Jedes verschobene Dokument steht als ein Schreib- und ein Löschvorgang auf der Rechnung, dazu die Lesevorgänge, um es zu finden und zu lesen.

FAQ

Kann man ein Dokument in Firestore umbenennen?

Nicht direkt. Firestore hat keine Operation zum Umbenennen, und die ID eines Dokuments lässt sich nach dem Anlegen nicht mehr ändern. Um eines umzubenennen, legen Sie ein Dokument mit der neuen ID und denselben Daten an und löschen dann das alte. „Dokument-ID ändern“ von Firexport und das Admin-SDK-Skript oben erledigen beides in einem Schreibvorgang.

Werden beim Umbenennen eines Dokuments seine Untersammlungen mit verschoben?

Nur wenn Sie sie ebenfalls verschieben. Untersammlungen gehören zum Pfad des Dokuments, nicht zu seinen Daten: Beim Kopieren der Felder bleiben sie zurück, und beim Löschen des alten Dokuments werden sie auch nicht gelöscht. Firexport und das Skript oben verschieben jede Untersammlung in jeder Tiefe mit dem Dokument.

Kann ich eine Sammlung in Firestore umbenennen?

Nein. Eine Sammlung existiert nur durch die Dokumente darin. Sie umzubenennen heißt also, jedes Dokument unter den neuen Sammlungsnamen zu verschieben. Weder die Console noch Firexport erledigt das in einem Schritt; ein Skript, das das Verschieben von oben für jedes Dokument ausführt, schon.

Was passiert mit Referenzen auf das alte Dokument?

Sie zeigen weiter auf den alten Pfad, den es nach dem Verschieben nicht mehr gibt. Firestore aktualisiert weder Referenzfelder noch IDs, die in anderen Dokumenten gespeichert sind. Suchen und aktualisieren Sie sie daher nach dem Umbenennen.

Was kostet das Umbenennen eines Firestore-Dokuments?

Jedes verschobene Dokument ist ein Schreib- und ein Löschvorgang, dazu kommen die Lesevorgänge, um es und seine Untersammlungen zu finden. Firexport zeigt die Anzahl, bevor Sie auf Verschieben klicken. Im kostenlosen Spark-Tarif geht das von den 20.000 Schreib- und 20.000 Löschvorgängen pro Tag ab.