Firexport / Guias

Como exportar dados do Firestore para JSON

O Realtime Database tem um botão Exportar JSON no Console do Firebase. O Firestore, não. Há três formas práticas de tirar documentos do Firestore como JSON, desde os resultados de uma consulta até uma coleção inteira com suas subcoleções.

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

1. Exportar do Console do Firebase com o Firexport

A página do Firestore no Console do Firebase tem um criador de consultas (Query builder) que executa uma consulta e mostra os resultados em uma tabela, mas nada para baixá-los. O Firexport é uma extensão gratuita do Chrome que adiciona um botão Exportar ao lado desses resultados.

1. Instale o Firexport pela Chrome Web Store.
2. No Console do Firebase, abra Firestore Database e mude de visualização em painel (Panel view) para criador de consultas (Query builder) (canto superior direito da guia Dados).
3. Escolha a coleção em Escopo da consulta (Query scope) e Caminho (Path), adicione filtros ou um limite se quiser e clique em Executar (Run).
4. Abra o menu ⋮ ao lado do botão Exportar e escolha Exportar para JSON. O Firexport percorre todas as páginas dos resultados e baixa um único arquivo JSON. (O botão Exportar em si salva CSV.)

O arquivo é um array JSON com um objeto por documento: uma chave Document ID e depois os campos do documento. Números, booleanos e null mantêm seus tipos JSON, e mapas e arrays saem aninhados. O que muda entre a versão gratuita e o Advanced são os valores que o console só mostra como texto:

Grátis: timestamps, geopoints e referências como o console os exibe:

[
  {
    "Document ID": "2PomjkgoCISvwnlGrypP",
    "name": "firexport",
    "count": 1,
    "tags": ["dev", "export"],
    "settings": { "theme": "dark", "beta": true },
    "createdAt": "August 24, 2026 at 1:16:09 PM UTC+9",
    "location": "[37.5665° N, 126.978° E]",
    "owner": "/users/u1"
  }
]

Advanced (licença de compra única): os mesmos valores restaurados a partir dos dados que o console já carregou:

[
  {
    "Document ID": "2PomjkgoCISvwnlGrypP",
    "name": "firexport",
    "count": 1,
    "tags": ["dev", "export"],
    "settings": { "theme": "dark", "beta": true },
    "createdAt": "2026-08-24T04:16:09.012207Z",
    "location": { "latitude": 37.5665, "longitude": 126.978 },
    "owner": "projects/my-app/databases/(default)/documents/users/u1"
  }
]

Na versão gratuita, um mapa ou array cujo texto no console não pode ser lido de volta como JSON (um que o console cortou com “…”, por exemplo) continua como string. O Advanced grava esses por completo. De qualquer forma, não há chave de conta de serviço nem faturamento para configurar: funciona na sessão do console em que você já está conectado, e o arquivo é montado no seu navegador. Funciona no Chrome e em outros navegadores baseados no Chromium.

Exporte sua próxima consulta do Firestore como JSON direto do console, sem script nem chave de conta de serviço.

Adicionar ao Chrome — grátis

2. Exportar com um script do Admin SDK

Um script curto em Node.js com o Firebase Admin SDK consegue exportar uma coleção inteira e pode descer às subcoleções, o que nenhum dos outros métodos faz. Ele precisa de uma conta que possa ler o Firestore: um Proprietário ou Editor do projeto, ou o papel Leitor 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 export-to-json.mjs, substitua your-project-id e execute node export-to-json.mjs users. Adicione --subcollections para incluir as subcoleções de cada documento.

// Usage: node export-to-json.mjs users [--subcollections]   → writes users.json
import { writeFileSync } from 'node:fs';
import { initializeApp } from 'firebase-admin/app';
import {
  getFirestore,
  FieldPath,
  Timestamp,
  GeoPoint,
  DocumentReference,
} from 'firebase-admin/firestore';

initializeApp({ projectId: 'your-project-id' });
const db = getFirestore();
const [collection, flag] = process.argv.slice(2);
if (!collection) throw new Error('Usage: node export-to-json.mjs <collection> [--subcollections]');
const withSubcollections = flag === '--subcollections';

// Firestore types become JSON values: timestamps as ISO 8601, references as paths.
function plain(value) {
  if (value instanceof Timestamp) return value.toDate().toISOString();
  if (value instanceof DocumentReference) return value.path;
  if (value instanceof GeoPoint) return { latitude: value.latitude, longitude: value.longitude };
  if (value instanceof Uint8Array) return Buffer.from(value).toString('base64');
  if (Array.isArray(value)) return value.map(plain);
  if (value && typeof value === 'object') {
    return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, plain(v)]));
  }
  return value;
}

// Read a collection 1,000 documents at a time. With --subcollections, each document also gets its
// subcollections under "__collections__", read the same way.
async function readCollection(ref) {
  const docs = [];
  let last;
  while (true) {
    let query = ref.orderBy(FieldPath.documentId()).limit(1000);
    if (last) query = query.startAfter(last);
    const page = await query.get();
    if (page.empty) break;
    for (const doc of page.docs) {
      const row = { documentId: doc.id, ...plain(doc.data()) };
      if (withSubcollections) {
        for (const sub of await doc.ref.listCollections()) {
          row.__collections__ ??= {};
          row.__collections__[sub.id] = await readCollection(sub);
        }
      }
      docs.push(row);
    }
    last = page.docs[page.docs.length - 1];
  }
  return docs;
}

const docs = await readCollection(db.collection(collection));
writeFileSync(`${collection}.json`, JSON.stringify(docs, null, 2));
console.log(`Wrote ${docs.length} documents to ${collection}.json`);

• Com --subcollections, cada documento que tem subcoleções recebe uma chave __collections__ com elas, aninhadas até onde forem. Encontrá-las custa uma requisição a mais por documento, então coleções grandes demoram mais.
• Subcoleções sob um documento que não existe por si só (o console mostra o ID dele em itálico) não são alcançadas a partir da coleção pai. Exporte essas por grupo de coleções.
• O script mantém tudo na memória antes de gravar o arquivo. Para milhões de documentos, use o método 3.

3. Exportar com gcloud e BigQuery

A exportação gerenciada do Firestore grava um backup no Cloud Storage no formato próprio do Firestore, não em JSON. O BigQuery consegue carregar esse formato e gravá-lo de volta como JSON. É o caminho para coleções grandes, mas precisa do faturamento ativado (plano Blaze) e de permissão para executar exportações e gravar no bucket. A documentação de exportação e importação do Google lista os papéis.

# 1. Export one collection. BigQuery only loads exports made with --collection-ids.
gcloud firestore export gs://YOUR_BUCKET/users-export --collection-ids=users

# 2. Load it into a BigQuery dataset in the same location as the bucket.
bq --location=US mk --dataset firestore_export
bq load --source_format=DATASTORE_BACKUP firestore_export.users \
  gs://YOUR_BUCKET/users-export/all_namespaces/kind_users/all_namespaces_kind_users.export_metadata

# 3. Write it out as newline-delimited JSON and download it.
bq extract --destination_format=NEWLINE_DELIMITED_JSON firestore_export.users gs://YOUR_BUCKET/users.json
gcloud storage cp gs://YOUR_BUCKET/users.json .

• O arquivo é JSON delimitado por linha: um documento por linha, não um array. Para transformá-lo em um array, execute jq -s . users.json > users-array.json.
• Mapas e arrays continuam aninhados. Cada linha também tem um objeto __key__ da exportação, que guarda o ID do documento.
• O BigQuery grava no máximo 1 GB por arquivo. Para mais, use um curinga como gs://YOUR_BUCKET/users-*.json.
• A exportação é cobrada como uma leitura de documento por documento. Apague a pasta de exportação quando terminar, para que ela pare de ocupar o Cloud Storage.

Perguntas frequentes

O Console do Firebase consegue exportar dados do Firestore para JSON?

Não. O Realtime Database tem Exportar JSON no menu do visualizador de dados, mas a guia Dados do Firestore não tem download. A exportação gerenciada (a página Importar/Exportar do console do Google Cloud, ou gcloud firestore export) grava um backup no formato próprio do Firestore no Cloud Storage, não em JSON.

Por que a API REST do Firestore retorna valores como {"stringValue": "..."}?

A API REST embrulha cada campo no seu tipo: stringValue, integerValue, timestampValue, mapValue e assim por diante. É JSON, mas não no formato dos seus documentos. O Admin SDK (método 2) desembrulha esses tipos para você.

Posso importar o JSON de volta para o Firestore?

Não diretamente. O gcloud firestore import só lê exportações gerenciadas, e nenhum desses arquivos JSON é uma. Para carregar um arquivo JSON, grave-o de volta com um script (o BulkWriter do Admin SDK lida com lotes grandes). Se o objetivo é restaurar dados, use a exportação e a importação gerenciadas em vez de JSON.

Exportar dados do Firestore custa dinheiro?

Todos os métodos leem cada documento exportado pelo menos uma vez, e o Firestore cobra isso como leituras de documento. Dentro da cota gratuita diária, não custa nada. A exportação gerenciada também exige faturamento ativado no projeto, e seus arquivos ocupam o Cloud Storage até você apagá-los.