Firexport / 가이드

Firestore 데이터를 JSON으로 내보내는 방법

Realtime Database에는 Firebase 콘솔에 JSON 내보내기 버튼이 있지만 Firestore에는 없습니다. Firestore 문서를 JSON으로 꺼내는 실용적인 방법은 세 가지로, 쿼리 하나의 결과부터 하위 컬렉션까지 포함한 컬렉션 전체까지 다룹니다.

2026년 9월 24일 업데이트. 방법 1의 확장 프로그램 Firexport는 저희가 만든 것입니다. 방법 2와 3에는 필요 없습니다.

1. Firexport로 Firebase 콘솔에서 내보내기

Firebase 콘솔의 Firestore 페이지에는 쿼리를 실행해 결과를 표로 보여 주는 쿼리 빌더(Query builder)가 있지만, 그 결과를 내려받을 방법은 없습니다. Firexport는 그 결과 옆에 내보내기 버튼을 추가하는 무료 Chrome 확장 프로그램입니다.

1. Chrome 웹 스토어에서 Firexport를 설치합니다.
2. Firebase 콘솔에서 Firestore Database를 열고 패널 뷰(Panel view)에서 쿼리 빌더(Query builder)로 전환합니다(데이터 탭의 오른쪽 위).
3. 쿼리 범위(Query scope)와 경로(Path)에서 컬렉션을 고르고, 필요하면 필터나 제한을 더한 뒤 실행(Run)을 클릭합니다.
4. 내보내기 버튼 옆의 ⋮ 메뉴를 열어 JSON 내보내기를 고릅니다. Firexport가 결과의 모든 페이지를 훑어 JSON 파일 하나를 내려받습니다. (내보내기 버튼 자체는 CSV를 저장합니다.)

파일은 문서마다 객체 하나가 든 JSON 배열 하나입니다. Document ID 키 다음에 문서의 필드가 옵니다. 숫자·불리언·null은 JSON 타입을 그대로 유지하고, 맵과 배열은 중첩된 채로 나옵니다. 무료 버전과 Advanced의 차이는 콘솔이 텍스트로만 보여 주는 값에서 납니다:

무료 — 타임스탬프·지오포인트·참조는 콘솔에 표시되는 그대로:

[
  {
    "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(1회 구매 라이선스) — 같은 값을 콘솔이 이미 불러온 데이터에서 복원:

[
  {
    "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"
  }
]

무료 버전에서는 콘솔의 텍스트를 JSON으로 되읽을 수 없는 맵이나 배열(예를 들어 콘솔이 “…”로 잘라 버린 것)은 문자열로 남습니다. Advanced는 그것을 온전히 씁니다. 어느 쪽이든 서비스 계정 키도, 결제 설정도 필요 없습니다. 이미 로그인한 콘솔 세션에서 동작하고 파일은 브라우저 안에서 만들어집니다. Chrome과 다른 Chromium 기반 브라우저에서 동작합니다.

스크립트도 서비스 계정 키도 없이, 다음 Firestore 쿼리를 콘솔에서 JSON으로 바로 내보내 보세요.

Chrome에 추가 — 무료

2. Admin SDK 스크립트로 내보내기

Firebase Admin SDK를 쓰는 짧은 Node.js 스크립트는 컬렉션 전체를 내보낼 수 있고, 다른 두 방법이 못 하는 하위 컬렉션까지 내려갈 수 있습니다. Firestore를 읽을 수 있는 계정이 필요합니다. 프로젝트 소유자나 편집자, 또는 Cloud Datastore 뷰어 역할입니다.

1. SDK 설치: npm install firebase-admin
2. 로컬 사용자 인증 정보로 로그인: gcloud auth application-default login. 서버에서는 대신 GOOGLE_APPLICATION_CREDENTIALS가 서비스 계정 키를 가리키게 합니다.
3. 아래 스크립트를 export-to-json.mjs로 저장하고 your-project-id를 바꾼 뒤 node export-to-json.mjs users를 실행합니다. 각 문서의 하위 컬렉션까지 포함하려면 --subcollections를 더합니다.

// 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`);

• --subcollections를 주면 하위 컬렉션이 있는 문서마다 그것을 담은 __collections__ 키가 생기고, 깊이만큼 중첩됩니다. 하위 컬렉션을 찾는 데 문서마다 요청이 하나 더 들어가므로 큰 컬렉션은 더 오래 걸립니다.
• 존재하지 않는 문서(콘솔이 ID를 기울임꼴로 보여 주는 문서) 아래의 하위 컬렉션에는 상위 컬렉션에서 닿지 못합니다. 그런 것은 컬렉션 그룹으로 내보내세요.
• 이 스크립트는 파일을 쓰기 전에 모든 것을 메모리에 담습니다. 문서가 수백만 건이면 방법 3을 쓰세요.

3. gcloud와 BigQuery로 내보내기

Firestore의 관리형 내보내기는 JSON이 아니라 Firestore 고유 형식의 백업을 Cloud Storage에 씁니다. BigQuery가 그 형식을 불러와 다시 JSON으로 써 줄 수 있습니다. 큰 컬렉션에 맞는 길이지만, 결제 계정(Blaze 요금제)과 내보내기를 실행하고 버킷에 쓸 권한이 필요합니다. 필요한 역할은 Google의 내보내기 및 가져오기 문서에 있습니다.

# 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 .

• 파일은 줄바꿈으로 구분된 JSON입니다. 배열 하나가 아니라 한 줄에 문서 하나입니다. 배열로 바꾸려면 jq -s . users.json > users-array.json을 실행합니다.
• 맵과 배열은 중첩된 채로 남습니다. 각 줄에는 내보내기에서 온 __key__ 객체도 있는데, 문서 ID가 거기 들어 있습니다.
• BigQuery는 파일 하나에 최대 1GB를 씁니다. 더 크면 gs://YOUR_BUCKET/users-*.json처럼 와일드카드를 씁니다.
• 내보내기는 문서마다 문서 읽기 1회로 과금됩니다. 끝나면 Cloud Storage 용량을 계속 쓰지 않도록 내보내기 폴더를 삭제하세요.

FAQ

Firebase 콘솔에서 Firestore 데이터를 JSON으로 내보낼 수 있나요?

아니요. Realtime Database는 데이터 뷰어 메뉴에 JSON 내보내기가 있지만, Firestore의 데이터 탭에는 다운로드가 없습니다. 관리형 내보내기(Google Cloud 콘솔의 가져오기/내보내기 페이지 또는 gcloud firestore export)는 JSON이 아니라 Firestore 고유 형식의 백업을 Cloud Storage에 씁니다.

Firestore REST API는 왜 {"stringValue": "..."} 같은 값을 돌려주나요?

REST API는 모든 필드를 stringValue, integerValue, timestampValue, mapValue 같은 타입으로 감쌉니다. JSON이긴 하지만 문서의 모양은 아닙니다. Admin SDK(방법 2)가 그 타입을 풀어 줍니다.

JSON을 다시 Firestore로 가져올 수 있나요?

바로는 안 됩니다. gcloud firestore import는 관리형 내보내기만 읽는데, 이 JSON 파일들은 그것이 아닙니다. JSON 파일을 올리려면 스크립트로 다시 쓰세요(큰 배치는 Admin SDK의 BulkWriter가 처리합니다). 데이터 복원이 목적이라면 JSON 대신 관리형 내보내기와 가져오기를 쓰세요.

Firestore 데이터를 내보내면 비용이 드나요?

어떤 방법이든 내보내는 문서마다 최소 한 번은 읽고, Firestore는 그것을 문서 읽기로 과금합니다. 일일 무료 할당량 안에서는 비용이 없습니다. 관리형 내보내기는 추가로 프로젝트에 결제 계정이 연결돼 있어야 하고, 그 파일은 삭제하기 전까지 Cloud Storage 용량을 차지합니다.