Firexport / Guides

Comment renommer un document Firestore (modifier son ID)

Firestore ne sait pas renommer un document. L’ID d’un document fait partie de son chemin, et ni la console Firebase ni les SDK ne permettent de le modifier. Renommer revient à recréer le document sous le nouvel ID et à supprimer l’ancien, avec tout le contenu de ses sous-collections, auxquelles la suppression d’un document ne touche pas. Il existe trois façons de le faire, selon ce qui se trouve sous le document.

Mis à jour le 27 octobre 2026. Firexport, l’extension de la méthode 1, est la nôtre. Les méthodes 2 et 3 n’en ont pas besoin.

1. Modifier l’ID depuis la console Firebase avec Firexport

Firexport est une extension Chrome gratuite qui ajoute Modifier l’ID du document au menu ⋮ de chaque document dans la vue en panneaux (Panel view) de Firestore. Elle déplace le document et tout le contenu de ses sous-collections vers le nouvel ID en une seule écriture : tout se fait, ou rien ne se fait. Elle écrit avec un compte Google que vous connectez, donc il n’y a ni clé de compte de service ni code à configurer.

1. Installez Firexport depuis le Chrome Web Store.
2. Dans la console Firebase, ouvrez Firestore Database > Données (Data) en vue en panneaux (Panel view) et cliquez sur la collection qui contient le document.
3. Survolez le document dans la liste et cliquez sur le ⋮ qui apparaît à gauche de son ID, puis sur Modifier l’ID du document.
4. La première fois, la fenêtre vous demande de Connecter un compte Google : choisissez le compte avec lequel vous êtes connecté à la console et autorisez l’accès dans la fenêtre de Google.
5. Saisissez le nouvel ID dans Nouvel ID du document et cliquez sur Modifier l’ID. Un document sans sous-collections est déplacé immédiatement.
6. S’il a des sous-collections, Firexport les lit d’abord et indique combien de documents seront déplacés, combien d’écritures cela demande et combien de lectures il a fallu pour vérifier. Cliquez sur Déplacer. La console ouvre ensuite le document sous son nouvel ID.

Ce qui bloque un déplacement

• Un document existe déjà au nouvel ID, ou en dessous. Firexport n’écrase jamais rien : l’écriture est refusée et rien ne change.
• L’un des documents a changé après sa lecture par Firexport. Sinon, l’ancien contenu arriverait sous le nouvel ID pendant que le nouveau contenu serait supprimé : rien n’est donc écrit, et vous pouvez réessayer.
• Plus de 250 documents, ou plus que ce qu’une écriture peut contenir (10 Mio). Firexport s’arrête avant d’écrire quoi que ce soit ; utilisez la méthode 2.
• Un ID que Firestore n’accepte pas : un ID qui contient /, qui vaut . ou .., qui commence et finit par __, ou qui dépasse 1 500 octets. Les espaces au début ou à la fin font partie de l’ID, et le champ les conserve donc.

Chaque champ garde exactement sa valeur et son type, car Firexport écrit ce qu’il a lu dans Firestore et non ce que la console affiche. Les écritures utilisent les autorisations du compte connecté, donc les règles de sécurité ne s’appliquent pas. Les documents vont de votre navigateur directement chez Google, et jamais chez nous. La fonction Modifier l’ID du document est gratuite dans toutes les formules.

Modifiez l’ID d’un document Firestore depuis la console, avec ses sous-collections, en une seule écriture.

Ajouter à Chrome — gratuit

2. Le déplacer avec un script Admin SDK

Pour un document sous lequel se trouvent plus de 250 documents, ou pour renommer de nombreux documents, un script Node.js avec le SDK Admin Firebase fait le même déplacement. Celui ci-dessous lit le document et toutes les sous-collections qui se trouvent dessous, puis recrée chaque document au nouveau chemin et supprime les anciens. Le nouveau chemin peut aussi se trouver dans une autre collection : le même script sert donc à déplacer un document. Il lui faut un compte qui peut écrire dans Firestore : un Propriétaire ou un Éditeur du projet, ou le rôle Utilisateur Cloud Datastore.

1. Installez le SDK : npm install firebase-admin
2. Connectez-vous pour obtenir des identifiants locaux : gcloud auth application-default login. Sur un serveur, faites plutôt pointer GOOGLE_APPLICATION_CREDENTIALS vers une clé de compte de service.
3. Enregistrez le script ci-dessous sous rename-document.mjs, remplacez your-project-id et exécutez node rename-document.mjs users/alice users/alice-smith.

// 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() renvoie aussi un emplacement qui a des sous-collections mais aucun champ propre (les ID en italique dans la console), si bien que le script atteint les documents qui se trouvent dessous. L’emplacement lui-même n’est pas copié : il apparaît au nouveau chemin dès que ses sous-collections y arrivent.
• Avec ONE_BATCH activé, chaque création et chaque suppression passent dans un seul lot. Si un document existe déjà au nouveau chemin, ou si l’un d’eux a changé après sa lecture par le script, Firestore rejette le lot et rien n’est écrit.
• Un lot peut contenir jusqu’à 10 Mio. Pour une arborescence plus grande, réglez ONE_BATCH sur false : le script copie tout avec BulkWriter et ne supprime les anciens documents que si chaque copie a été écrite. Ce n’est pas du tout ou rien : n’écrivez donc pas dans ces documents pendant son exécution.
• Comme la méthode 1, il contourne les règles de sécurité. Les horodatages, les références, les geopoints et les octets gardent leur type, et useBigInt garde exacts les entiers au-delà de 2⁵³. Seule chose que le SDK Admin ne peut pas conserver : un double sans partie décimale, comme 2.0, est lu comme un simple nombre et réécrit sous la forme de l’entier 2.

3. Le copier à la main dans la console

Pour un document avec quelques champs et aucune sous-collection, la console suffit. Il faut deux écritures qui ne sont pas liées entre elles, et vous ressaisissez chaque valeur.

1. Ouvrez le document et notez le nom, le type et la valeur de chaque champ.
2. Dans la même collection, cliquez sur Ajouter un document (Add document), saisissez le nouvel ID dans ID du document (Document ID) et ajoutez les mêmes champs avec les mêmes types. Cliquez sur Enregistrer (Save).
3. Vérifiez le nouveau document, puis ouvrez le menu ⋮ de l’ancien et cliquez sur Supprimer le document (Delete document).

Surveillez les types au fur et à mesure : un nombre saisi dans un champ de type chaîne reste une chaîne, et un horodatage doit être ressaisi avec le type horodatage. Les sous-collections ne suivent pas. Il faudrait copier chacune de la même façon, un document à la fois.

Ce que change un nouvel ID

Quelle que soit la méthode, le document sous le nouvel ID est un nouveau document. Cela a quelques conséquences.

• Date de création. Chaque document déplacé reçoit de nouvelles dates de création et de mise à jour.
• Références. Les champs de type référence des autres documents pointent toujours vers l’ancien chemin, tout comme les ID stockés sous forme de chaînes, par exemple un ownerId. Mettez-les à jour vous-même.
• Cloud Functions et écouteurs. Chaque document déplacé active les déclencheurs de création et de suppression, et les applications qui écoutent la collection voient un document supprimé et un autre ajouté.
• Coût. Chaque document déplacé compte pour une écriture et une suppression sur la facture, plus les lectures pour le trouver et le lire.

FAQ

Peut-on renommer un document dans Firestore ?

Pas directement. Firestore n’a pas d’opération de renommage, et l’ID d’un document ne peut plus changer une fois celui-ci créé. Pour renommer un document, créez-en un avec le nouvel ID et les mêmes données, puis supprimez l’ancien. La fonction Modifier l’ID du document de Firexport et le script Admin SDK ci-dessus font les deux en une seule écriture.

Renommer un document déplace-t-il ses sous-collections ?

Seulement si vous les déplacez aussi. Les sous-collections sont rattachées au chemin du document, pas à ses données : copier les champs les laisse donc sur place, et supprimer l’ancien document ne les supprime pas non plus. Firexport et le script ci-dessus déplacent toutes les sous-collections, à tous les niveaux, avec le document.

Puis-je renommer une collection dans Firestore ?

Non. Une collection n’existe qu’à travers les documents qu’elle contient : la renommer revient donc à déplacer chaque document vers le nouveau nom de collection. Ni la console ni Firexport ne le font en une seule étape ; un script qui effectue le déplacement ci-dessus pour chaque document, si.

Qu’advient-il des références à l’ancien document ?

Elles pointent toujours vers l’ancien chemin, qui n’existe plus après le déplacement. Firestore ne met à jour ni les champs de référence ni les ID stockés dans d’autres documents : retrouvez-les et mettez-les à jour après le renommage.

Combien coûte le renommage d’un document Firestore ?

Chaque document déplacé correspond à une écriture et une suppression, plus les lectures pour le trouver, lui et ses sous-collections. Firexport affiche ce nombre avant que vous ne cliquiez sur Déplacer. Avec la formule Spark gratuite, cela entre dans les 20 000 écritures et les 20 000 suppressions par jour.