Firexport / Guias

Como renomear um documento do Firestore (alterar o ID)

O Firestore não consegue renomear um documento. O ID de um documento faz parte do caminho dele, e nem o Console do Firebase nem os SDKs têm como alterá-lo. Renomear significa recriar o documento com o novo ID e excluir o antigo, junto com tudo o que há nas subcoleções dele, que a exclusão de um documento não alcança. Há três formas de fazer isso. Qual delas serve depende de quanta coisa há abaixo do documento.

Atualizado em 27 de outubro de 2026. O Firexport, a extensão do método 1, é nosso. Os métodos 2 e 3 não precisam dele.

1. Alterar o ID no Console do Firebase com o Firexport

O Firexport é uma extensão gratuita do Chrome que adiciona Alterar ID do documento ao menu ⋮ de cada documento na visualização em painel (Panel view) do Firestore. Ele move o documento e tudo o que há nas subcoleções dele para o novo ID em uma única gravação, então ou tudo acontece, ou nada. Ele grava com uma conta do Google que você conecta, então não há chave de conta de serviço nem código para configurar.

1. Instale o Firexport pela Chrome Web Store.
2. No Console do Firebase, abra Firestore Database > Dados (Data) na visualização em painel (Panel view) e clique na coleção que contém o documento.
3. Passe o mouse sobre o documento na lista e clique no ⋮ que aparece à esquerda do ID dele, depois em Alterar ID do documento.
4. Na primeira vez, a janela pede que você clique em Conectar conta do Google: escolha a conta com que você entrou no console e permita o acesso na janela do Google.
5. Digite o Novo ID do documento e clique em Alterar ID. Um documento sem subcoleções é movido na hora.
6. Se ele tiver subcoleções, o Firexport as lê primeiro e mostra quantos documentos serão movidos, quantas gravações isso exige e quantas leituras foram feitas para verificar. Clique em Mover. Depois, o console abre o documento no novo ID.

O que impede a movimentação

• Um documento que já existe no novo ID, ou abaixo dele. O Firexport nunca sobrescreve: a gravação é recusada e nada muda.
• Uma alteração em qualquer um dos documentos depois que o Firexport os leu. Do contrário, o conteúdo antigo iria parar no novo ID enquanto o conteúdo novo seria excluído; por isso nada é gravado e você pode tentar de novo.
• Mais de 250 documentos, ou mais do que cabe em uma gravação (10 MiB). O Firexport para antes de gravar qualquer coisa; use o método 2.
• Um ID que o Firestore não permite: um que contenha /, que seja apenas . ou .., que comece e termine com __, ou que tenha mais de 1.500 bytes. Espaços no início ou no fim fazem parte do ID, então a caixa os mantém.

Cada campo mantém exatamente o valor e o tipo, porque o Firexport grava o que leu do Firestore, e não o que o console mostra. As gravações usam as permissões da conta conectada, então as regras de segurança não se aplicam. Os documentos vão do seu navegador direto para o Google, e nunca para nós. A função Alterar ID do documento é gratuita em todos os planos.

Altere o ID de um documento do Firestore no console, com as subcoleções, em uma única gravação.

Adicionar ao Chrome — grátis

2. Mover o documento com um script do Admin SDK

Para um documento com mais de 250 documentos abaixo dele, ou para renomear muitos documentos, um script em Node.js com o Firebase Admin SDK faz a mesma movimentação. O script abaixo lê o documento e todas as subcoleções abaixo dele, depois cria cada documento no novo caminho e exclui os antigos. O novo caminho também pode ficar em outra coleção, então o mesmo script serve para mover um documento. Ele precisa de uma conta que possa gravar no Firestore: um Proprietário ou Editor do projeto, ou o papel Usuário do Cloud Datastore.

1. Instale o SDK: npm install firebase-admin
2. Faça login para obter credenciais locais: gcloud auth application-default login. Em um servidor, aponte GOOGLE_APPLICATION_CREDENTIALS para uma chave de conta de serviço.
3. Salve o script abaixo como rename-document.mjs, substitua your-project-id e execute 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() também retorna um lugar que tem subcoleções mas nenhum campo próprio (os IDs em itálico no console), então o script chega aos documentos abaixo dele. O lugar em si não é copiado: ele aparece no novo caminho assim que as subcoleções dele aparecem lá.
• Com ONE_BATCH ativado, todas as criações e exclusões vão em um único lote. Se já existir um documento no novo caminho, ou se algum mudou depois que o script o leu, o Firestore rejeita o lote e nada é gravado.
• Um lote comporta até 10 MiB. Para uma árvore maior, defina ONE_BATCH como false: o script copia tudo com o BulkWriter e só exclui os documentos antigos se todas as cópias forem gravadas. Isso não é tudo ou nada, então não grave nesses documentos enquanto ele roda.
• Como o método 1, ele ignora as regras de segurança. Timestamps, referências, geopoints e bytes mantêm seus tipos, e useBigInt mantém exatos os inteiros além de 2⁵³. Uma coisa o Admin SDK não consegue manter: um double sem parte fracionária, como 2.0, é lido como um número simples e gravado de volta como o inteiro 2.

3. Copiar o documento à mão no console

Para um documento com poucos campos e sem subcoleções, o console basta. São duas gravações que não estão ligadas entre si, e você digita cada valor de novo.

1. Abra o documento e anote o nome, o tipo e o valor de cada campo.
2. Na mesma coleção, clique em Adicionar documento (Add document), digite o novo ID em ID do documento (Document ID) e adicione os mesmos campos com os mesmos tipos. Clique em Salvar (Save).
3. Confira o novo documento, depois abra o menu ⋮ do antigo e clique em Excluir documento (Delete document).

Preste atenção aos tipos: um número digitado em um campo do tipo string continua sendo string, e um timestamp precisa ser inserido de novo com o tipo timestamp. As subcoleções não vêm junto. Cada uma teria de ser copiada do mesmo jeito, um documento por vez.

O que um novo ID muda

Seja qual for a forma de mover, o documento no novo ID é um documento novo. Algumas coisas decorrem disso.

• Data de criação. Cada documento movido ganha novas datas de criação e de atualização.
• Referências. Campos de referência em outros documentos continuam apontando para o caminho antigo, assim como IDs guardados como strings, por exemplo um ownerId. Atualize-os você mesmo.
• Cloud Functions e listeners. Cada documento movido dispara os gatilhos de criação e de exclusão, e os apps que escutam a coleção veem um documento removido e outro adicionado.
• Custo. Cada documento movido conta na fatura como uma gravação e uma exclusão, mais as leituras para encontrá-lo e lê-lo.

Perguntas frequentes

É possível renomear um documento no Firestore?

Não diretamente. O Firestore não tem uma operação de renomear, e o ID de um documento não pode mudar depois que ele é criado. Para renomear um documento, crie outro com o novo ID e os mesmos dados e depois exclua o antigo. A função Alterar ID do documento do Firexport e o script do Admin SDK acima fazem as duas coisas em uma única gravação.

Renomear um documento move as subcoleções dele?

Só se você as mover também. As subcoleções pertencem ao caminho do documento, não aos dados dele, então copiar os campos as deixa para trás, e excluir o documento antigo também não as exclui. O Firexport e o script acima movem todas as subcoleções, em todos os níveis, junto com o documento.

Posso renomear uma coleção no Firestore?

Não. Uma coleção só existe por meio dos documentos que ela contém, então renomear uma coleção significa mover cada documento para o novo nome de coleção. Nem o console nem o Firexport fazem isso em uma só etapa; um script que execute a movimentação acima para cada documento, sim.

O que acontece com as referências ao documento antigo?

Elas continuam apontando para o caminho antigo, que deixa de existir depois da movimentação. O Firestore não atualiza campos de referência nem IDs guardados em outros documentos, então encontre-os e atualize-os depois de renomear.

Quanto custa renomear um documento do Firestore?

Cada documento movido é uma gravação e uma exclusão, mais as leituras para encontrar o documento e as subcoleções dele. O Firexport mostra o número antes de você clicar em Mover. No plano Spark gratuito, isso sai das 20.000 gravações e 20.000 exclusões por dia.