Firestore 入門：文件資料、即時更新與存取規則

前言

如果 App 要在多個裝置上同步資料，也希望離線時仍能操作，Firestore 值得評估。不過資料怎麼切成文件、查詢怎麼做，以及誰可以讀寫，都得先想清楚。

這篇從文件與集合開始，接著看即時監聽、安全規則和費用。讀完後，再拿需求去比較它與其他資料庫。

什麼是 Firestore？

Firestore 是 GCP 的 NoSQL 文件資料庫（Document Database），資料以 JSON-like 文件形式儲存：

flowchart TB
  DB["Firestore Database"] --> USERS["Collection<br/>users"]
  USERS --> U1["Document<br/>user-001"]
  USERS --> U2["Document<br/>user-002"]
  U1 --> FIELDS1["Fields<br/>name、email、age"]
  U2 --> FIELDS2["Fields<br/>name = Alice"]
  U1 --> ORDERS["Subcollection<br/>orders"]
  ORDERS --> O1["Document<br/>order-001"]
  ORDERS --> O2["Document<br/>order-002"]
  O1 --> ORDER_FIELDS["Fields<br/>amount、status"]
  DELETE["刪除 user-001 Document"] -. "不會自動遞迴刪除" .-> ORDERS
  ORDERS -. "須由程式或管理工具<br/>另外清理" .-> CLEANUP["Recursive delete／<br/>生命週期清理"]

Firestore 是 Cloud Datastore 的下一代。原本的 Datastore 已經不是獨立產品了，現在改以 Firestore in Datastore mode 的形式繼續活著。

Native Mode vs Datastore Mode

建立 Firestore 資料庫時，你必須選擇模式：

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

強一致性（strong consistency）指寫入成功後，後續讀取與查詢能看到已提交的資料；不用靠等幾秒來避開舊值。Native 與 Datastore Mode 都支援。

能切換嗎？

只有資料庫是空的時候才能切換模式。一旦寫進去任何資料，模式就鎖死了。

建議

• 新應用若沒有 Datastore API 相容需求，通常選 Native Mode；伺服器端程式也能使用。
• 若現有 App Engine 應用依賴 Datastore API，再考慮 Datastore Mode。

💡 重點提點

模式只能在資料庫為空時切換；有資料後若要更換，就得規劃新資料庫與資料遷移。建立前先確認應用使用 Firestore API 還是既有 Datastore API，不必因為程式跑在伺服器端就選 Datastore Mode。（參考：Firestore API 模式選擇、資料庫類型變更限制）

flowchart TB
  subgraph CHOOSE["1. 選擇相容模式"]
    direction TB
    START["建立新的 Firestore Database"] --> LEGACY{"既有 Datastore 應用，<br/>必須沿用 API 與行為？"}
    LEGACY -->|"是"| DATASTORE["Datastore Mode<br/>維持伺服器端相容性"]
    LEGACY -->|"否"| CLIENT{"需要 Mobile／Web SDK、<br/>即時監聽或離線同步？"}
    CLIENT -->|"是"| NATIVE["Native Mode<br/>新應用的預設建議"]
    CLIENT -->|"否或不確定"| NATIVE
  end
  subgraph COMMIT["2. 寫入前確認"]
    direction TB
    EMPTY{"第一筆資料<br/>已經寫入？"}
    EMPTY -->|"尚未"| REVIEW["仍可重新檢查模式"]
    EMPTY -->|"已寫入"| LOCKED["模式鎖定<br/>要改只能建新資料庫並遷移"]
  end
  DATASTORE --> EMPTY
  NATIVE --> EMPTY

Enterprise edition 另有 Firestore with MongoDB compatibility（見下面的 Editions）。

資料模型核心概念

文件（Document）

文件是 Firestore 的基本單位，類似 JSON 物件：

# Python 範例：新增文件
from google.cloud import firestore

db = firestore.Client()

# 自動生成 ID
doc_ref = db.collection("users").document()
doc_ref.set({
    "name": "Bobo",
    "email": "bobo@example.com",
    "age": 30,
    "tags": ["gcp", "cloud"],
    "address": {
        "city": "Taipei",
        "country": "Taiwan"
    }
})

# 指定 ID
db.collection("users").document("user-001").set({
    "name": "Alice"
})

重要限制

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

這裡的「文件名稱大小 6 KiB」指的是整段完整路徑（例如 users/user-001/orders/order-001）的上限，不要跟單一文件 ID（你自己取或自動生成的那一小段，上限 1,500 bytes）搞混。一般情況根本碰不到，路徑取名別太誇張就好。

集合（Collection）

集合是放文件的容器，不用事先建好。寫進第一個文件時它自動冒出來，刪掉最後一個文件時又自動消失。

子集合（Subcollection）

文件可以包含子集合，用來建立層級關係：

# 在 user-001 下建立 orders 子集合
db.collection("users").document("user-001") \
  .collection("orders").document("order-001").set({
    "item": "Cloud certification",
    "amount": 200
})

%%{init: {"flowchart": {"rankSpacing": 30, "nodeSpacing": 30}}}%%
  flowchart TB
  START["一對多或巢狀資料<br/>要放在哪裡？"] --> BINARY{"大型二進位檔，<br/>或可能超過 1 MiB？"}
  BINARY -->|"是"| STORAGE["Cloud Storage<br/>Firestore 只存 metadata 與 URI"]
  BINARY -->|"否"| BOUNDED{"筆數有明確上限，<br/>且總與父文件一起讀寫？"}
  BOUNDED -->|"是"| EMBED["嵌入 Map／Array<br/>監控文件大小與索引膨脹"]
  BOUNDED -->|"否"| PARENT{"隸屬單一父項，<br/>並需獨立分頁或權限？"}
  PARENT -->|"是"| SUB["Subcollection<br/>規劃遞迴刪除與群組索引"]
  PARENT -->|"否，需跨父項查詢"| TOP["Top-level Collection<br/>保存 parentId 並用 Rules 維護關聯"]

CRUD 操作

讀取

# 讀取單一文件
doc = db.collection("users").document("user-001").get()
if doc.exists:
    print(doc.to_dict())

# 查詢
query = db.collection("users") \
    .where("age", ">=", 25) \
    .where("tags", "array_contains", "gcp") \
    .order_by("age") \
    .limit(10)

for doc in query.stream():
    print(f"{doc.id}: {doc.to_dict()}")

更新

# 更新特定欄位（不影響其他欄位）
db.collection("users").document("user-001").update({
    "age": 31,
    "address.city": "Kaohsiung"  # 更新巢狀欄位
})

刪除

# 刪除文件
db.collection("users").document("user-001").delete()

# 刪除特定欄位
db.collection("users").document("user-001").update({
    "age": firestore.DELETE_FIELD
})

批次與交易

# 批次寫入（現已無 500 筆上限，改受單次提交約 10 MiB 大小限制；舊版曾限制 500 筆）
batch = db.batch()
for i in range(100):
    ref = db.collection("items").document(f"item-{i}")
    batch.set(ref, {"value": i})
batch.commit()

# 交易（讀取 + 寫入的原子操作）
@firestore.transactional
def transfer(transaction, from_ref, to_ref, amount):
    from_doc = from_ref.get(transaction=transaction)
    to_doc = to_ref.get(transaction=transaction)

    from_balance = from_doc.get("balance") - amount
    to_balance = to_doc.get("balance") + amount

    transaction.update(from_ref, {"balance": from_balance})
    transaction.update(to_ref, {"balance": to_balance})

transaction = db.transaction()
transfer(transaction,
         db.collection("accounts").document("A"),
         db.collection("accounts").document("B"),
         100)

flowchart TB
  subgraph DECIDE["1. 判斷寫入依賴"]
    direction TB
    START["這次操作要修改幾筆文件，<br/>新值如何決定？"] --> COUNT{"只修改單一 Document？"}
    COUNT -->|"否"| READ{"寫入內容依賴<br/>剛讀到的目前值？"}
  end
  subgraph METHOD["2. 選擇原子操作"]
    direction TB
    SINGLE["set／update／<br/>delete<br/>單文件寫入具原子性"]
    BATCH["Batched Write<br/>多筆一起成功或失敗"]
    TX["Transaction<br/>先讀再寫，<br/>衝突時重試"]
  end
  subgraph SAFETY["3. 保持可重跑"]
    direction TB
    SIDE{"交易內包含寄信、<br/>付款等外部副作用？"}
    SIDE -->|"是"| REMOVE["移出交易<br/>改用 Outbox／後續工作"]
    SIDE -->|"否"| RETRY["避免全域可變狀態<br/>讓函式可安全重跑"]
  end
  COUNT -->|"是"| SINGLE
  READ -->|"否"| BATCH
  READ -->|"是"| TX
  TX --> SIDE

即時監聽（Real-time Listeners）

Native Mode 的獨家功能，資料變更時自動推送通知：

# 監聽單一文件
def on_snapshot(doc_snapshot, changes, read_time):
    for doc in doc_snapshot:
        print(f"Changed: {doc.to_dict()}")

doc_ref = db.collection("users").document("user-001")
doc_watch = doc_ref.on_snapshot(on_snapshot)

# 監聽查詢結果
query_ref = db.collection("users").where("age", ">=", 25)
query_watch = query_ref.on_snapshot(on_snapshot)

# 停止監聽
doc_watch.unsubscribe()

用戶端訂閱某份文件或查詢後，結果有變動時會收到更新，不必自己固定間隔輪詢（polling）。但連線中斷、重新連線與畫面暫存狀態，仍要在應用裡處理。

索引設計

自動索引

Firestore 會幫每個欄位自動建好單欄位索引，基本的等式和範圍查詢都罩得住。

複合索引

複合索引（composite index）就是把「好幾個欄位綁在一起」建的索引。當你的查詢同時用到多個欄位（例如又篩 age、又排序 name），單欄位索引不夠用，就得手動建一個複合索引：

# 這個查詢需要複合索引：(age ASC, name ASC)
query = db.collection("users") \
    .where("age", ">=", 25) \
    .order_by("age") \
    .order_by("name")

# 建立複合索引
gcloud firestore indexes composite create \
  --collection-group=users \
  --field-config=field-path=age,order=ascending \
  --field-config=field-path=name,order=ascending

索引限制

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

flowchart TB
  subgraph DESIGN["1. 由查詢反推索引"]
    direction TB
    START["定義篩選、排序、<br/>集合範圍與回傳筆數"] --> SIMPLE{"只有單欄位條件<br/>或簡單排序？"}
    SIMPLE -->|"是"| AUTO["使用自動單欄位索引"]
    SIMPLE -->|"否"| MULTI{"組合多個 where、<br/>range 與 orderBy？"}
    MULTI -->|"是"| COMPOSITE["建立 Composite Index<br/>欄位順序符合查詢"]
    MULTI -->|"否"| EXEMPT["豁免不查詢的大欄位<br/>降低寫入與儲存成本"]
  end
  subgraph VALIDATE["2. 執行與驗證"]
    direction TB
    TEST["在 Emulator／測試環境<br/>執行實際查詢"] --> ERROR{"出現 missing index？"}
    ERROR -->|"是"| LINK["依錯誤提供的組合建索引<br/>等待建置後重試"]
    ERROR -->|"否"| REVIEW["量測讀取筆數、延遲、<br/>索引項目與寫入成本"]
  end
  AUTO --> TEST
  COMPOSITE --> TEST
  EXEMPT --> TEST

安全規則 vs IAM

安全規則（Security Rules）

用於 Mobile/Web 用戶端的存取控制：

// firestore.rules
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    // 用戶只能讀寫自己的資料
    match /users/{userId} {
      allow read, write: if request.auth != null
                         && request.auth.uid == userId;
    }

    // 公開讀取，只有管理員能寫入
    match /posts/{postId} {
      allow read: if true;
      allow write: if request.auth.token.admin == true;
    }
  }
}

IAM

用於伺服器端的存取控制：

# 授予 Service Account Firestore 讀寫權限
gcloud projects add-iam-policy-binding my-project \
  --member="serviceAccount:my-app-sa@my-project.iam.gserviceaccount.com" \
  --role="roles/datastore.user"

何時用哪個？

flowchart TB
  START["誰直接呼叫 Firestore？"] --> CLIENT{"Firebase Mobile／Web SDK<br/>由終端使用者直接存取？"}
  CLIENT -->|"是"| RULES["Security Rules<br/>以 request.auth、文件路徑與資料驗證"]
  RULES --> AUTH["Firebase Authentication<br/>提供使用者身分與 claims"]
  CLIENT -->|"否，由後端或自動化呼叫"| SERVER["Server SDK／REST<br/>使用 Service Account"]
  SERVER --> IAM["IAM<br/>roles/datastore.* 與最小權限"]
  IAM --> BYPASS["伺服器 SDK 不靠 Security Rules<br/>應在後端再做業務授權"]
  START --> MIXED{"同時有用戶端直連<br/>與後端管理作業？"}
  MIXED -->|"是"| BOTH["兩套都要設計<br/>Rules 保護客戶端、IAM 保護後端"]
  RULES --> TEST["用 Emulator、Rules tests<br/>與拒絕案例驗證"]
  IAM --> AUDIT["用 IAM Policy Analyzer<br/>與 Audit Logs 驗證"]

Firestore Editions

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

多資料庫支援

Firestore 支援在同一個專案中建立多個資料庫（Named Databases）：

# 建立額外的資料庫
gcloud firestore databases create \
  --database=analytics-db \
  --location=asia-east1 \
  --type=firestore-native

# 連線到特定資料庫
db = firestore.Client(database="analytics-db")

💡 重點提點

一個專案只有一個資料庫可享免費額度，資格給第一個建立的資料庫，名稱不一定要是 (default)。後續新增的資料庫會依使用量計費；練習前先確認哪個資料庫取得免費額度，再估算讀寫、儲存與網路用量。（參考：Firestore 計費說明）

flowchart TB
  subgraph EDITION["1. 選擇 Edition"]
    direction TB
    START["建立 Firestore Database"] --> FEATURE{"需要 MongoDB 相容 API<br/>或 Enterprise 專屬能力？"}
    FEATURE -->|"是"| ENTERPRISE["Enterprise<br/>驗證相容性、<br/>區域與費用"]
    FEATURE -->|"否"| STANDARD["Standard<br/>一般 Native 應用起點"]
  end
  subgraph DATABASE["2. 決定資料庫隔離"]
    direction TB
    ISOLATION{"需要獨立資料庫<br/>做隔離、位置<br/>或生命週期？"}
    ISOLATION -->|"否"| DEFAULT["使用 (default)<br/>確認是否為首個資料庫"]
    ISOLATION -->|"是"| NAMED["建立 Named Database<br/>估算使用量與費用"]
    NAMED --> GUARD["獨立設定 IAM、<br/>備份、索引、<br/>TTL、預算與監控"]
  end
  ENTERPRISE --> ISOLATION
  STANDARD --> ISOLATION

TTL（自動過期刪除）

Firestore TTL 讓你指定欄位作為過期時間，文件到期後自動刪除：

# 設定 TTL 欄位
gcloud firestore fields ttls update expiresAt \
  --collection-group=sessions \
  --enable-ttl

from datetime import datetime, timedelta

# 建立 30 天後自動過期的文件
db.collection("sessions").add({
    "userId": "user-001",
    "expiresAt": datetime.now() + timedelta(days=30)
})

定價與免費層

免費層（僅限專案的首個資料庫）

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

超過免費層（美國區域）

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

Firestore vs Cloud SQL vs Bigtable

若要比較文件資料庫、關聯式資料庫與寬列資料庫，可以先從資料模型和查詢方式看起：

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

選型公式

flowchart LR
  subgraph NEED["1. 判斷核心需求"]
    direction TB
    START["描述資料關係、查詢、<br/>規模與用戶端需求"] --> RELATIONAL{"需要 JOIN、<br/>外鍵、複雜 SQL<br/>或關聯式交易？"}
    RELATIONAL -->|"否"| WIDE{"TB／PB 級，<br/>並以 Row Key<br/>做高吞吐時序／<br/>IoT 存取？"}
    WIDE -->|"否"| DOCUMENT{"文件型 Mobile／<br/>Web 資料，<br/>需要即時同步<br/>或離線 SDK？"}
  end
  subgraph SERVICE["2. 選擇服務"]
    SQL["Cloud SQL<br/>關聯式 OLTP"]
    BIGTABLE["Bigtable<br/>寬列、低延遲與水平擴展"]
    FIRESTORE["Firestore Native<br/>文件查詢與即時監聽"]
    RECHECK["重新檢查 Spanner、<br/>BigQuery、<br/>Cloud Storage 等服務"]
  end
  RELATIONAL -->|"是"| SQL
  WIDE -->|"是"| BIGTABLE
  DOCUMENT -->|"是"| FIRESTORE
  DOCUMENT -->|"否"| RECHECK

ACE 考試重點整理

必背知識點

1. Firestore 的資料存取模式在建立資料庫時選定：Native（推薦）、Datastore，以及 Enterprise edition 才有的 Firestore with MongoDB compatibility；資料庫有資料後就不能更改
2. 文件大小上限 1 MiB，子集合深度上限 100 層
3. 即時監聽是 Native Mode 獨有功能
4. 安全規則用於 Mobile/Web，IAM 用於伺服器端
5. 免費層：50K 讀取/天、20K 寫入/天
6. 多資料庫支援：同一專案可建立多個資料庫
7. 自動索引：單欄位自動建索引，多欄位需手動建複合索引

常見陷阱題

Q：Firestore 和 Datastore 是兩個不同的產品嗎？ A：不是。Datastore 已經併入 Firestore，以 Firestore in Datastore mode 的形式存在。新專案請選 Native Mode。

Q：Firestore 適合儲存 10 MB 的檔案嗎？ A：不適合。文件大小上限 1 MiB。大型檔案應存在 Cloud Storage，Firestore 只存 metadata 和 GCS 路徑。

Q：Mobile App 直接存取 Firestore，要用 IAM 還是 Security Rules？ A：Security Rules。IAM 用於伺服器端，Security Rules 才能做到用戶級別的存取控制。

Q：需要即時同步資料給多個用戶端，用什麼服務？ A：Firestore（Native Mode）的即時監聽功能。

總結

Firestore 適合文件型資料，也能支援即時同步和部分用戶端的離線使用。建立資料庫前先確認模式與位置；設計權限時分清用戶端 Security Rules 和伺服器端 IAM。最後用預期讀寫量估算費用，別把免費額度當成所有資料庫都適用的固定折扣。

下一課 GCP-113：Bigtable 深度解析，來看 Google 那套 PB 級的寬列型 NoSQL 資料庫。

資料庫選型系列

表格超出欄寬時，可左右捲動；鍵盤可聚焦表格後用左右方向鍵查看。

還在比較資料庫？可以接著看 Google Cloud 資料庫怎麼選？。