Cloud Firestore is a NoSQL, document-oriented database. Unlike a SQL database,there are no tables or rows. Instead, you store data indocuments, which areorganized intocollections.

Eachdocument contains a set of key-value pairs.Cloud Firestore isoptimized for storing large collections of small documents.

All documents must be stored in collections. Documents can containsubcollections and nested objects, both of which can include primitive fieldslike strings or complex objects like lists.

Collections and documents are created implicitly inCloud Firestore.Simply assign data to a document within a collection. If either the collectionor document does not exist,Cloud Firestore creates it.

Documents

InCloud Firestore, the unit of storage is the document. A document is alightweight record that contains fields, which map to values. Each document isidentified by a name.

A document representing a useralovelace might look like this:

• class alovelace

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

A collection contains documents and nothing else. It can't directly contain rawfields with values, and it can't contain other collections. (SeeHierarchicalData for an explanation of how to structure more complexdata inCloud Firestore.)

The names of documents within a collection are unique. You can provide your ownkeys, such as user IDs, or you can letCloud Firestore create random IDsfor you automatically.

You do not need to "create" or "delete" collections. After you create the firstdocument in a collection, the collection exists. If you delete all of thedocuments in a collection, it no longer exists.

References

Every document inCloud Firestore is uniquely identified by its locationwithin the database. The previous example showed a documentalovelace withinthe collectionusers. To refer to this location in your code, you can create areference to it.

import{doc}from"firebase/firestore";constalovelaceDocumentRef=doc(db,'users','alovelace');
doc_reference.js

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

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

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

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

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

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

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

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

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

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

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

import("cloud.google.com/go/firestore")funccreateDocReference(client*firestore.Client){alovelaceRef:=client.Collection("users").Doc("alovelace")_=alovelaceRef}
retrieve_data_reference_document.go

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

DocumentReferencedocumentRef=db.Collection("users").Document("alovelace");

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

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

A reference is a lightweight object that just points to a location in yourdatabase. You can create a reference whether or not data exists there, andcreating a reference does not perform any network operations.

You can also create references tocollections:

import{collection}from"firebase/firestore";constusersCollectionRef=collection(db,'users');
collection_reference.js

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

letusersCollectionRef=db.collection("users")
ViewController.swift

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

valusersCollectionRef=db.collection("users")
DocSnippets.kt

CollectionReferenceusersCollectionRef=db.collection("users");
DocSnippets.java

finalusersCollectionRef=db.collection("users");
firestore.dart

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

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

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

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

constusersCollectionRef=db.collection('users');
index.js

import("cloud.google.com/go/firestore")funccreateCollectionReference(client*firestore.Client){usersRef:=client.Collection("users")_=usersRef}
retrieve_data_reference_collection.go

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

CollectionReferencecollectionRef=db.Collection("users");

CollectionReferencecollectionRef=db.Collection("users");
Program.cs

collection_ref=firestore.col"users"
data_model.rb

import{doc}from"firebase/firestore";constalovelaceDocumentRef=doc(db,'users/alovelace');
doc_reference_alternative.js

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

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

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

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

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

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

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

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

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

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

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

import("cloud.google.com/go/firestore")funccreateDocReferenceFromString(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

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

DocumentReferencedocumentRef=db.Document("users/alovelace");

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

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

Hierarchical Data

To understand how hierarchical data structures work inCloud Firestore,consider an example chat app with messages and chat rooms.

You can create a collection calledrooms to store different chat rooms:

• collections_bookmark rooms

  • class roomA

    name : "my chat room"
    

  • class roomB

    ...
    

Now that you have chat rooms, decide how to store your messages. You might notwant to store them in the chat room's document. Documents inCloud Firestoreshould be lightweight, and a chat room could contain a large number of messages.However, you can create additional collections within your chat room's document,as subcollections.

Subcollections

The best way to store messages in this scenario is by using subcollections. Asubcollection is a collection associated with a specific document.

You can create a subcollection calledmessages for every room document inyourrooms collection:

• collections_bookmark rooms

  • class roomA

    name : "my chat room"
    

    • collections_bookmarkmessages

      • classmessage1

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

      • classmessage2

        ...
        

  • class roomB

    ...
    

In this example, you would create a reference to a message in the subcollectionwith the following code:

import{doc}from"firebase/firestore";constmessageRef=doc(db,"rooms","roomA","messages","message1");
subcollection_reference.js

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

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

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

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

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

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

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

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

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

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

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

import("cloud.google.com/go/firestore")funccreateSubcollectionReference(client*firestore.Client){messageRef:=client.Collection("rooms").Doc("roomA").Collection("messages").Doc("message1")_=messageRef}
retrieve_data_reference_subcollection.go

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

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

DocumentReferencedocumentRef=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

Notice the alternating pattern of collections and documents. Your collectionsand documents must always follow this pattern. You cannot reference a collectionin a collection or a document in a document.

Subcollections allow you to structure data hierarchically, making data easier toaccess. To get all messages inroomA, you can create a collection referenceto the subcollectionmessages and interact with it like you would any othercollection reference.

Documents in subcollections can contain subcollections as well, allowing you tofurther nest data. You can nest data up to 100 levels deep.