本頁面由 Cloud Translation API 翻譯而成。

資料模型

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

每個文件都包含一組鍵/值組合。Firestore 經過最佳化，可儲存大量小型文件。

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

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

文件

在 Firestore 中，儲存單位是文件。文件是輕量型記錄，內含對應至值的欄位。每個文件都有自己的名稱。

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

alovelace

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

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

alovelace

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

您可能會發現文件與 JSON 非常相似。事實上，這兩者基本上是相同的。兩者之間有些差異 (例如，文件支援額外的資料類型，但大小上限為 1 MB)，不過一般來說，您可以將文件視為輕量型 JSON 記錄。

集合

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

位使用者
- alovelace
  
  first : "Ada"
  last : "Lovelace"
  born : 1815
- aturing
  
  first : "Alan"
  last : "Turing"
  born : 1912

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

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

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

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

參考資料

Firestore 中的每個文件都有專屬 ID，也就是該文件在資料庫中的位置。上例顯示集合 users 中的文件 alovelace。如要在程式碼中參照這個位置，可以建立該位置的參照。

網頁版 9

import { doc } from "firebase/firestore";

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

網頁版 8

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
Android

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

Java
Android

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
(Async)

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

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Unity

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

C#

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Ruby

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

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

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

網頁版 9

import { collection } from "firebase/firestore";

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

網頁版 8

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
Android

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

Java
Android

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
(Async)

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

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Unity

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

C#

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Ruby

collection_ref = firestore.col "users"data_model.rb

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

網頁版 9

import { doc } from "firebase/firestore"; 

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

網頁版 8

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
Android

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

Java
Android

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
(Async)

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

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Unity

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

C#

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Ruby

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

階層式資料

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

你可以建立名為「rooms」的集合，用來儲存不同的聊天室：

間會議室
- roomA
  
  name : "my chat room"
- roomB
  
  ...

現在您已建立聊天室，請決定如何儲存訊息。您可能不想將這些檔案儲存在聊天室的文件中。Firestore 中的文件應為輕量級，而聊天室可能包含大量訊息。不過，您可以在聊天室的文件中建立其他集合，做為子集合。

子集合

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

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

間會議室
- roomA
  
  name : "my chat room"
  - 訊息
    - message1
      
      from : "alex"
      msg : "Hello World!"
    - message2
      
      ...
- roomB
  
  ...

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

網頁版 9

import { doc } from "firebase/firestore"; 

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

網頁版 8

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
Android

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

Java
Android

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
(Async)

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

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Unity

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

C#

如要向 Firestore 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證」。

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

Ruby

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

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

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

子集合中的文件也可以包含子集合，讓您進一步將資料設為巢狀結構。資料最多可巢狀結構化 100 層。

資料模型

文件

集合

參考資料

網頁版 9

網頁版 8

Swift

Objective-C

KotlinAndroid

JavaAndroid

Dart

Java

Python

Python(Async)

C++

Node.js

Go

PHP

PHP

Unity

C#

C#

Ruby

網頁版 9

網頁版 8

Swift

Objective-C

KotlinAndroid

JavaAndroid

Dart

Java

Python

Python(Async)

C++

Node.js

Go

PHP

PHP

Unity

C#

C#

Ruby

網頁版 9

網頁版 8

Swift

Objective-C

KotlinAndroid

JavaAndroid

Dart

Java

Python

Python(Async)

C++

Node.js

Go

PHP

PHP

Unity

C#

C#

Ruby

階層式資料

子集合

網頁版 9

網頁版 8

Swift

Objective-C

KotlinAndroid

JavaAndroid

Dart

Java

Python

Python(Async)

C++

Node.js

Go

PHP

PHP

Unity

C#

Kotlin
Android

Java
Android

Python
(Async)

Kotlin
Android

Java
Android

Python
(Async)

Kotlin
Android

Java
Android

Python
(Async)

Kotlin
Android

Java
Android

Python
(Async)