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 和时间戳。您还可以使用数组或嵌套对象（称为映射）来设计文档中数据的结构。

文档中的复杂嵌套对象称为映射 (map)。例如，您可以使用映射来设计上例中用户姓名的结构，如下所示：

• alovelace

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

您可能会注意到，文档看起来很像 JSON。它们其实基本上就是 JSON，但有稍许差异（例如，文档支持额外的数据类型，大小限制为 1 MB），但总体而言，您可以将文档视为轻量级 JSON 记录。

集合

文档存在于集合中，简单来说，集合就是文档的容器。例如，您可以使用 users 集合来容纳您的各个用户，每个用户用一个文档来表示：

• 位用户

  • alovelace

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

  • aturing

    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

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

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

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 的集合来存储不同的聊天室：

• rooms

  • roomA

    name : "my chat room"
    

  • roomB

    ...
    

现在您已经有聊天室了，需要决定如何存储消息。您可能不想将它们存储在聊天室的文档中。这是因为 Cloud Firestore 中的文档应该是轻量级的，而聊天室可能包含大量消息。 但是，您可以在聊天室的文档中创建额外的集合作为子集合。

子集合

在此例中，存储消息的最佳方式是使用子集合。子集合是指与某个文档相关联的集合。

注意：您可以使用集合组查询在具有相同集合 ID 的多个子集合中执行查询。

您可以为 rooms 集合中的每个聊天室文档创建名为 messages 的子集合：

• rooms

  • roomA

    name : "my chat room"
    

    • messages

      • 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

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 处也可能存在一个文档。删除父文档时，如果要删除其子集合中的文档，必须按照删除集合中的说明手动操作。