Cloud Firestore 資料模型

Cloud Firestore 是 NoSQL 文件資料庫與 SQL 資料庫不同，沒有資料表或資料列。您應該將資料儲存在「文件」中，而文件會整理成「集合」。

每份文件都含有一組鍵/值組合。Cloud Firestore 適合用於儲存大量小型文件。

所有文件都必須儲存在集合中。文件可包含「子集合」和巢狀物件，且兩種物件均包含「字串」等原始欄位，或「清單」等複雜物件。

集合和文件是在 Cloud Firestore 中以隱含方式建立。只要將資料指派給集合中的文件即可。如果集合或文件不存在，Cloud Firestore 會建立集合或文件。

文件

Cloud Firestore 中的儲存空間單位為文件。文件是輕量記錄，包含欄位會對應至值。每份文件都能透過名稱識別。

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

• 座情人節

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

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

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

• 座情人節

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

您可能會注意到，文件看起來很像 JSON。實際上基本上。這也有一些差異 (例如，文件支援額外的資料類型，大小限制為 1 MB)，但一般來說，您可以將文件視為輕量的 JSON 記錄。

集合

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

• 位使用者

  • 座情人節

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

  • 人

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

Cloud Firestore 沒有結構定義，可讓您完全自由調整每份文件中的欄位，以及儲存在這些欄位中的資料類型。相同集合內的文件可以包含不同欄位，或是在這些欄位中儲存不同類型的資料。不過，建議您在多份文件中使用相同的欄位和資料類型，這樣才能更輕鬆地查詢文件。

集合中含有文件，但沒有內容。不能直接包含有值的原始欄位，也不能包含其他集合。(如需瞭解如何在 Cloud Firestore 中建構更複雜的資料，請參閱階層資料相關說明)。

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

你不需要「建立」或「刪除」集合。當您在集合中建立第一份文件後，該集合就會存在。如果您刪除集合中的所有文件，則文件不存在。

參考資料

Cloud Firestore 中的每份文件都會依其在資料庫中的位置識別。先前的範例顯示了集合 users 內的文件 alovelace。如要在程式碼中參照這個位置，您可以建立指向該位置的參照。

網頁模組 API

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { doc } from "firebase/firestore";

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

網路命名空間 API

進一步瞭解可樹狀結構的模組化 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

小茹

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

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

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

網頁模組 API

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { collection } from "firebase/firestore";

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

網路命名空間 API

進一步瞭解可樹狀結構的模組化 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

小茹

collection_ref = firestore.col "users"
data_model.rb

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

為方便起見，您也可以使用字串來指定文件或集合的路徑，並填入以正斜線 (/) 分隔的路徑元件，藉此建立參照。舉例來說，建立 alovelace 文件的參照：

網頁模組 API

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { doc } from "firebase/firestore"; 

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

網路命名空間 API

進一步瞭解可樹狀結構的模組化 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

小茹

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

階層式資料

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

你可以建立名為 rooms 的珍藏內容來儲存不同的聊天室：

• 個房間

  • 間客房 A

    name : "my chat room"
    

  • 間房間 B

    ...
    

建立聊天室後，接著請決定訊息的儲存方式。因此建議您 不要將這些文件儲存在聊天室的文件裡。Cloud Firestore 中的文件應精簡，且聊天室可以含有大量訊息。不過，您可以在聊天室的文件中建立其他集合，做為子集合。

子集合

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

注意： 您可以使用集合群組查詢，查詢具有相同集合 ID 的子集合。

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

• 個房間

  • 間客房 A

    name : "my chat room"
    

    • 訊息

      • 訊息 1

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

      • 訊息 2

        ...
        

  • 間房間 B

    ...
    

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

網頁模組 API

進一步瞭解可樹狀結構的模組化 Web API，以及透過命名空間 API 升級。

import { doc } from "firebase/firestore"; 

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

網路命名空間 API

進一步瞭解可樹狀結構的模組化 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

小茹

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

請注意集合和文件的交替模式。您的集合和文件一律須採用這個模式。但不得在集合或文件中參照集合。

子集合可讓您按階層結構建構資料，讓資料更容易存取。如要取得 roomA 中的所有訊息，您可以建立子集合 messages 的集合參照，並像處理任何其他集合參照一樣與其互動。

子集合中的文件也可以包含子集合，方便您進一步巢狀資料。您可以為資料建立巢狀結構，最深可達 100 層。

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

刪除含有子集合的文件並不會刪除這些子集合。舉例來說，即使 coll/doc 文件已不存在，coll/doc/subcoll/subdoc 中仍可能有文件。如要在刪除上層文件時刪除子集合中的文件，您必須手動刪除，如「刪除集合」一節中所述。