Cloud Firestore 資料模型

Cloud Firestore 是 NoSQL 文件資料庫。與 SQL 資料庫不同的是，這個資料庫中沒有表格或資料列。而是將資料儲存在文件中，並將文件整理成集合。

每個文件都包含一組鍵/值組合。Cloud Firestore 是針對儲存大量小型文件的集合而最佳化。

所有文件都必須儲存在集合中。文件可包含子集合和巢狀物件，兩者皆可包含字串等基本欄位，或列表等複雜物件。

集合和文件會在 Cloud Firestore 中隱含建立。只要在集合中將資料指派給文件即可。如果集合或文件不存在，Cloud Firestore 會建立該項目。

文件

在 Cloud Firestore 中，儲存單位是文件。文件是輕量記錄，其中包含對應至值的欄位。每份文件都會以名稱標示。

代表使用者 alovelace 的文件可能如下所示：

• alovelace

  first : "Ada"
last : "Lovelace"
born : 1815
  

注意： Cloud Firestore 支援多種值資料類型：布林值、數字、字串、地理座標、二進位 blob 和時間戳記。您也可以使用陣列或巢狀物件 (稱為地圖)，為文件中的資料建立結構。

文件中的複雜巢狀物件稱為地圖。舉例來說，您可以使用地圖為上述範例中的使用者名稱建立結構，如下所示：

• alovelace

  name :
    first : "Ada"
    last : "Lovelace"
born : 1815
  

您可能會發現，文件看起來很像 JSON。事實上，它們基本上就是。兩者之間有些差異 (例如，文件支援額外的資料類型，且大小上限為 1 MB)，但一般來說，您可以將文件視為輕量 JSON 記錄。

集合

文件會儲存在集合中，而集合只是文件的容器。舉例來說，您可以建立 users 集合來容納各種使用者，每個使用者都由一個文件代表：

• 位使用者

  • alovelace

    first : "Ada"
last : "Lovelace"
born : 1815
    

  • 轉換

    first : "Alan"
last : "Turing"
born : 1912
    

Cloud Firestore 是無結構的，因此您可以完全自由地決定在每個文件中放入哪些欄位，以及在這些欄位中儲存哪些資料類型。同一個集合中的文件可以包含不同的欄位，或在這些欄位中儲存不同類型的資料。不過，建議您在多個文件中使用相同的欄位和資料類型，以便更輕鬆地查詢文件。

集合只包含文件，它無法直接包含含有值的原始欄位，也無法包含其他集合。(如要瞭解如何在 Cloud Firestore 中建立更複雜的資料結構，請參閱「階層資料」一文)。

集合中的文件名稱不得重複。您可以提供自己的金鑰 (例如使用者 ID)，也可以讓 Cloud Firestore 自動為您建立隨機 ID。

您不需要「建立」或「刪除」珍藏內容。在珍藏內容中建立第一份文件後，珍藏內容就會存在。如果您刪除珍藏內容中的所有文件，該珍藏內容就會消失。

參考資料

Cloud Firestore 中的每份文件都會由資料庫中的實際位置做為識別。先前的範例顯示集合 users 中的文件 alovelace。如要在程式碼中參照這個位置，您可以建立參照。

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

import { doc } from "firebase/firestore";

const alovelaceDocumentRef = doc(db, 'users', 'alovelace');
doc_reference.js

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

var alovelaceDocumentRef = db.collection('users').doc('alovelace');
test.firestore.js

Swift

注意：這項產品不適用於 watchOS 和 App Clip 目標。

let alovelaceDocumentRef = db.collection("users").document("alovelace")
ViewController.swift

Objective-C

注意：這項產品不適用於 watchOS 和 App Clip 目標。

FIRDocumentReference *alovelaceDocumentRef =
    [[self.db collectionWithPath:@"users"] documentWithPath:@"alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.collection("users").document("alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.collection("users").document("alovelace");
DocSnippets.java

Dart

final alovelaceDocumentRef = db.collection("users").doc("alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.collection("users").document("alovelace");
References.java

Python

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

Python

a_lovelace_ref = db.collection("users").document("alovelace")
snippets.py

C++

DocumentReference alovelace_document_reference =
    db->Collection("users").Document("alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.collection('users').doc('alovelace');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createDocReference(client *firestore.Client) {

	alovelaceRef := client.Collection("users").Doc("alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document.go

PHP

PHP

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

$document = $db->collection('samples/php/users')->document('alovelace');
data_reference_document.php

Unity

DocumentReference documentRef = db.Collection("users").Document("alovelace");

C#

C#

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

DocumentReference documentRef = db.Collection("users").Document("alovelace");
Program.cs

Ruby

document_ref = firestore.col("users").doc("alovelace")
data_model.rb

參照是一種輕量物件，只會指向資料庫中的某個位置。無論資料是否存在，您都可以建立參照，而且建立參照不會執行任何網路作業。

您也可以建立集合的參照項目：

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

import { collection } from "firebase/firestore";

const usersCollectionRef = collection(db, 'users');
collection_reference.js

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

var usersCollectionRef = db.collection('users');
test.firestore.js

Swift

注意：這項產品不適用於 watchOS 和 App Clip 目標。

let usersCollectionRef = db.collection("users")
ViewController.swift

Objective-C

注意：這項產品不適用於 watchOS 和 App Clip 目標。

FIRCollectionReference *usersCollectionRef = [self.db collectionWithPath:@"users"];
ViewController.m

Kotlin+KTX

val usersCollectionRef = db.collection("users")
DocSnippets.kt

Java

CollectionReference usersCollectionRef = db.collection("users");
DocSnippets.java

Dart

final usersCollectionRef = db.collection("users");
firestore.dart

Java

// Reference to the collection "users"
CollectionReference collection = db.collection("users");
References.java

Python

users_ref = db.collection("users")
snippets.py

Python

users_ref = db.collection("users")
snippets.py

C++

CollectionReference users_collection_reference = db->Collection("users");
snippets.cpp

Node.js

const usersCollectionRef = db.collection('users');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createCollectionReference(client *firestore.Client) {
	usersRef := client.Collection("users")

	_ = usersRef
}
retrieve_data_reference_collection.go

PHP

PHP

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

$collection = $db->collection('samples/php/users');
data_reference_collection.php

Unity

CollectionReference collectionRef = db.Collection("users");

C#

C#

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

CollectionReference collectionRef = db.Collection("users");
Program.cs

Ruby

collection_ref = firestore.col "users"
data_model.rb

注意： 集合參照和文件參照是兩種不同的參照類型，可讓您執行不同的作業。舉例來說，您可以使用集合參照來查詢集合中的文件，也可以使用文件參照來讀取或寫入個別文件。

為方便起見，您也可以將文件或集合的路徑指定為字串，並以正斜線 (/) 分隔路徑元件，藉此建立參照。舉例來說，如要建立 alovelace 文件的參照，請按照下列步驟操作：

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

import { doc } from "firebase/firestore"; 

const alovelaceDocumentRef = doc(db, 'users/alovelace');
doc_reference_alternative.js

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

var alovelaceDocumentRef = db.doc('users/alovelace');
test.firestore.js

Swift

注意：這項產品不適用於 watchOS 和 App Clip 目標。

let aLovelaceDocumentReference = db.document("users/alovelace")
ViewController.swift

Objective-C

注意：這項產品不適用於 watchOS 和 App Clip 目標。

FIRDocumentReference *aLovelaceDocumentReference =
    [self.db documentWithPath:@"users/alovelace"];
ViewController.m

Kotlin+KTX

val alovelaceDocumentRef = db.document("users/alovelace")
DocSnippets.kt

Java

DocumentReference alovelaceDocumentRef = db.document("users/alovelace");
DocSnippets.java

Dart

final aLovelaceDocRef = db.doc("users/alovelace");
firestore.dart

Java

// Reference to a document with id "alovelace" in the collection "users"
DocumentReference document = db.document("users/alovelace");
References.java

Python

a_lovelace_ref = db.document("users/alovelace")
snippets.py

Python

a_lovelace_ref = db.document("users/alovelace")
snippets.py

C++

DocumentReference alovelace_document = db->Document("users/alovelace");
snippets.cpp

Node.js

const alovelaceDocumentRef = db.doc('users/alovelace');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createDocReferenceFromString(client *firestore.Client) {
	// Reference to a document with id "alovelace" in the collection "users"
	alovelaceRef := client.Doc("users/alovelace")

	_ = alovelaceRef
}
retrieve_data_reference_document_path.go

PHP

PHP

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

$document = $db->document('users/alovelace');
data_reference_document_path.php

Unity

DocumentReference documentRef = db.Document("users/alovelace");

C#

C#

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

DocumentReference documentRef = db.Document("users/alovelace");
Program.cs

Ruby

document_path_ref = firestore.doc "users/alovelace"
data_model.rb

階層式資料

如要瞭解階層式資料結構在 Cloud Firestore 中的運作方式，請考慮使用含有訊息和聊天室的聊天應用程式範例。

您可以建立名為 rooms 的集合，用於儲存不同的聊天室：

• 間房間

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

建立聊天室後，請決定訊息的儲存方式。您可能不想將這些資料儲存在聊天室的文件中。Cloud Firestore 中的文件應為輕量型，且聊天室可能包含大量訊息。不過，您可以在聊天室的文件中建立其他子集合。

子集合

在這種情況下，使用子集合是儲存訊息的最佳方式。子集合是與特定文件相關聯的集合。

注意： 您可以使用集合群組查詢，在具有相同集合 ID 的子集合中執行查詢作業。

您可以為 rooms 集合中的每個房間文件建立名為 messages 的子集合：

• 間房間

  • roomA

    name : "my chat room"
    

    • 則訊息

      • message1

        from : "alex"
msg : "Hello World!"
        

      • message2

        ...
        

  • roomB

    ...
    

在這個範例中，您會使用下列程式碼建立子集合中訊息的參照：

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

import { doc } from "firebase/firestore"; 

const messageRef = doc(db, "rooms", "roomA", "messages", "message1");
subcollection_reference.js

Web

進一步瞭解樹狀結構可分割模組 Web API，並從命名空間 API 升級。

var messageRef = db.collection('rooms').doc('roomA')
                .collection('messages').doc('message1');
test.firestore.js

Swift

注意：這項產品不適用於 watchOS 和 App Clip 目標。

let messageRef = db
  .collection("rooms").document("roomA")
  .collection("messages").document("message1")
ViewController.swift

Objective-C

注意：這項產品不適用於 watchOS 和 App Clip 目標。

FIRDocumentReference *messageRef =
    [[[[self.db collectionWithPath:@"rooms"] documentWithPath:@"roomA"]
    collectionWithPath:@"messages"] documentWithPath:@"message1"];
ViewController.m

Kotlin+KTX

val messageRef = db
    .collection("rooms").document("roomA")
    .collection("messages").document("message1")
DocSnippets.kt

Java

DocumentReference messageRef = db
        .collection("rooms").document("roomA")
        .collection("messages").document("message1");
DocSnippets.java

Dart

final messageRef = db
    .collection("rooms")
    .doc("roomA")
    .collection("messages")
    .doc("message1");
firestore.dart

Java

// Reference to a document in subcollection "messages"
DocumentReference document =
    db.collection("rooms").document("roomA").collection("messages").document("message1");
References.java

Python

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

Python

room_a_ref = db.collection("rooms").document("roomA")
message_ref = room_a_ref.collection("messages").document("message1")
snippets.py

C++

DocumentReference message_reference = db->Collection("rooms")
    .Document("roomA")
    .Collection("messages")
    .Document("message1");
snippets.cpp

Node.js

const messageRef = db.collection('rooms').doc('roomA')
  .collection('messages').doc('message1');
index.js

Go

import (
	"cloud.google.com/go/firestore"
)

func createSubcollectionReference(client *firestore.Client) {
	messageRef := client.Collection("rooms").Doc("roomA").
		Collection("messages").Doc("message1")

	_ = messageRef
}
retrieve_data_reference_subcollection.go

PHP

PHP

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

$document = $db
    ->collection('rooms')
    ->document('roomA')
    ->collection('messages')
    ->document('message1');
data_reference_subcollection.php

Unity

DocumentReference documentRef = db
	.Collection("Rooms").Document("RoomA")
	.Collection("Messages").Document("Message1");

C#

C#

如要進一步瞭解如何安裝及建立 Cloud Firestore 用戶端，請參閱 Cloud Firestore 用戶端程式庫。

DocumentReference documentRef = db
    .Collection("Rooms").Document("RoomA")
    .Collection("Messages").Document("Message1");
Program.cs

Ruby

message_ref = firestore.col("rooms").doc("roomA").col("messages").doc("message1")
data_model.rb

請注意集合和文件的替換模式。您的集合和文件一律必須遵循這個模式。您無法在集合中參照集合，或在文件中參照文件。

子集合可讓您以階層式架構資料，方便存取資料。如要取得 roomA 中的所有訊息，您可以建立子集 messages 的集合參照，並與其互動，就像與任何其他集合參照互動一樣。

子集合中的文件也可以包含子集合，讓您進一步巢狀資料。資料巢狀結構的深度上限為 100 層。

警告： 刪除文件不會刪除其子集合！

刪除包含子集合的文件時，系統不會刪除這些子集合。舉例來說，即使文件 coll/doc 已不存在，coll/doc/subcoll/subdoc 可能仍會保留該文件。如果您想在刪除父項文件時刪除子集合中的文件，必須手動執行，如「刪除集合」所示。