This quickstart shows you how to set up Cloud Firestore, add data, then view
the data you just added in the Firebase console.
Create a Cloud Firestore database
If you haven't already, create a Firebase project: In the
Firebase console
, click
Add project
,
then follow the on-screen instructions to create a Firebase project or to
add Firebase services to an existing GCP project.
Navigate to the
Cloud Firestore
section of the
Firebase console
.
You'll be prompted to select an existing Firebase project.
Follow the database creation workflow.
Select a starting mode for your Cloud Firestore Security Rules:
- Test mode
Good for getting started with the mobile and web client libraries,
but allows anyone to read and overwrite your data. After testing,
make
sure to review the
Secure your data
section.
To get started with the web, Apple platforms, or Android SDK, select test mode.
- Locked mode
Denies all reads and writes from mobile and web clients.
Your authenticated application servers (C#, Go, Java, Node.js, PHP,
Python, or Ruby) can still access your database.
To get started with the C#, Go, Java, Node.js, PHP, Python, or Ruby
server client library, select locked mode.
Your initial set of Cloud Firestore Security Rules will apply to your default
Cloud Firestore database. If you create multiple databases for your project,
you can deploy Cloud Firestore Security Rules for each database.
Select a
location
for your database.
This location setting is your project's
default Google Cloud Platform (GCP) resource location
.
Note that this location will be used for GCP services in your project
that require a location setting, specifically, your default
Cloud Storage
bucket and your
App Engine
app (which is
required if you use Cloud Scheduler).
If you aren't able to select a location, then your project already
has a default GCP resource location. It was set either during project
creation or when setting up another service that requires a location
setting.
Click
Done
.
When you enable Cloud Firestore, it also enables the API in the
Cloud API Manager
.
Set up your development environment
Add the required dependencies and client libraries to your app.
Web namespaced API
- Follow the instructions to
add Firebase to your Web app
.
- Add the Firebase and Cloud Firestore libraries to your app:
<script src="https://www.gstatic.com/firebasejs/10.11.1/firebase-app-compat.js"></script>
<script src="https://www.gstatic.com/firebasejs/10.11.1/firebase-firestore-compat.js"></script>
The Cloud Firestore SDK is also available as an npm package.
npm install firebase@10.11.1 --save
You'll need to manually require both Firebase and Cloud Firestore.
import firebase from "firebase/compat/app";
// Required for side-effects
import "firebase/firestore";
Web modular API
- Follow the instructions to
add Firebase to your Web app
.
-
The Cloud Firestore SDK is available as an npm package.
npm install firebase@10.11.1 --save
You'll need to import both Firebase and Cloud Firestore.
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";
iOS+
Follow the instructions to
add Firebase to your Apple app
.
Use Swift Package Manager to install and manage Firebase dependencies.
- In Xcode, with your app project open, navigate to
File > Swift Packages >
Add Package Dependency
.
- When prompted, add the Firebase Apple platforms SDK repository:
https://github.com/firebase/firebase-ios-sdk
- Choose the Firestore library.
-
When finished, Xcode will automatically begin resolving and downloading your
dependencies in the background.
Android
- Follow the instructions to
add Firebase to your Android app
.
- Using the
Firebase Android BoM
,
declare the dependency for the Cloud Firestore library for Android in
your
module (app-level) Gradle file
(usually
app/build.gradle.kts
or
app/build.gradle
).
dependencies {
// Import the BoM for the Firebase platform
implementation(platform("com.google.firebase:firebase-bom:32.8.1"))
// Declare the dependency for the Cloud Firestore library
// When using the BoM, you don't specify versions in Firebase library dependencies
implementation("com.google.firebase:firebase-firestore")
}
By using the
Firebase Android BoM
,
your app will always use compatible versions of the Firebase Android
libraries.
(Alternative)
Declare Firebase library dependencies
without
using the
BoM
If you choose not to use the Firebase BoM, you must specify each
Firebase library version in its dependency line.
Note that if you use
multiple
Firebase libraries in
your app, we highly recommend using the BoM to manage library
versions, which ensures that all versions are compatible.
dependencies {
// Declare the dependency for the Cloud Firestore library
// When NOT using the BoM, you must specify versions in Firebase library dependencies
implementation("com.google.firebase:firebase-firestore:24.11.1")
}
Looking for a Kotlin-specific library module?
Starting with the
October 2023 release
,
both Kotlin and Java developers can depend on the main library module
(for details, see the
FAQ about this initiative
).
Dart
- If you haven't already,
configure and
initialize Firebase
in your Flutter app.
- From the root of your Flutter project, run the following command to
install the plugin:
flutter pub add cloud_firestore
- Once complete, rebuild your Flutter application:
flutter run
- Optional:
Improve iOS & macOS build times by including the
pre-compiled framework.
Currently, the Firestore SDK for iOS depends on code that can take
upwards of 5 minutes to build in Xcode. To reduce build times
significantly, you can use a pre-compiled version by adding this line to
the
target 'Runner' do
block in your Podfile:
target 'Runner' do
use_frameworks!
use_modular_headers!
pod 'FirebaseFirestore',
:git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
:tag => '
IOS_SDK_VERSION
'
flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
target 'RunnerTests' do
inherit! :search_paths
end
end
Replace
IOS_SDK_VERSION
with the version of the Firebase iOS
SDK specified in
firebase_core
's
firebase_sdk_version.rb
file. If you're not using the latest version of
firebase_core
, look for this file in your local Pub package
cache (usually
~/.pub-cache
).
Additionally, ensure that you have upgraded CocoaPods to 1.9.1 or
higher:
gem install cocoapods
For more information see the
issue
on GitHub
.
Java
- Add the Firebase Admin SDK to your app:
- Follow the instructions below to initialize Cloud Firestore
with the proper credentials in your environment.
Python
- Add the Firebase Admin SDK to your Python app:
pip install --upgrade firebase-admin
- Follow the instructions below to initialize Cloud Firestore
with the proper credentials in your environment.
C++
- Follow the instructions to
add Firebase to your C++ project
.
- C++ interface for Android.
- Gradle dependencies.
Add the following to your module
(app-level) Gradle file (usually
app/build.gradle
):
android.defaultConfig.externalNativeBuild.cmake {
arguments "-DFIREBASE_CPP_SDK_DIR=$gradle.firebase_cpp_sdk_dir"
}
apply from: "$gradle.firebase_cpp_sdk_dir/Android/firebase_dependencies.gradle"
firebaseCpp.dependencies {
// earlier entries
auth
firestore
}
- Binary dependencies.
Similarly, the recommended way to get
the binary dependencies is to add the following to your
CMakeLists.txt
file:
add_subdirectory(${FIREBASE_CPP_SDK_DIR} bin/ EXCLUDE_FROM_ALL)
set(firebase_libs firebase_auth firebase_firestore firebase_app)
# Replace the target name below with the actual name of your target,
# for example, "native-lib".
target_link_libraries(${YOUR_TARGET_NAME_HERE} "${firebase_libs}")
- To set up
desktop integration
, see
Add Firebase to your C++ project
.
Unity
- Follow the instructions to
add Firebase to your Unity
project
.
- Use the Unity interface to configure your project to minify Android builds.
You must minify the build to avoid the message
Error while merging dex archives
.
-
The option can be found in
Player Settings > Android > Publishing
Settings > Minify
.
-
The options may differ in different versions of Unity so refer to the
official
Unity documentation
and the
Firebase Unity Build Debug Guide
.
-
If, after enabling minification, the number of referenced methods still
exceeds the limit, another option is to enable
multidex
in:
-
mainTemplate.gradle
if
Custom Gradle Template
under
Player Settings
is enabled
-
or, the module-level
build.gradle
file, if you use Android Studio to build the exported project.
Node.js
-
Add the Firebase Admin SDK to your app:
npm install firebase-admin --save
-
Follow the instructions below to initialize Cloud Firestore
with the proper credentials in your environment.
Go
- Add the Firebase Admin SDK to your Go app:
go get firebase.google.com/go
- Follow the instructions below to initialize Cloud Firestore
with the proper credentials in your environment.
PHP
-
The Cloud Firestore server client libraries (Java, Node.js, Python, Go, PHP, C#, and Ruby) use
Google Application Default Credentials
for authentication.
-
Install and enable the
gRPC extension
for PHP, which you will need to use the client library.
-
Add the Cloud Firestore PHP library to your app:
composer require google/cloud-firestore
C#
-
The Cloud Firestore server client libraries (Java, Node.js, Python, Go, PHP, C#, and Ruby) use
Google Application Default Credentials
for authentication.
-
Add the Cloud Firestore C# library to your app in your
.csproj
file:
<ItemGroup>
<PackageReference Include="Google.Cloud.Firestore" Version="1.1.0-beta01" />
</ItemGroup>
-
Add the following to your
Program.cs
file:
using Google.Cloud.Firestore;
Ruby
-
The Cloud Firestore server client libraries (Java, Node.js, Python, Go, PHP, C#, and Ruby) use
Google Application Default Credentials
for authentication.
-
Add the Cloud Firestore Ruby library to your app in your
Gemfile
:
gem "google-cloud-firestore"
-
Install dependencies from your
Gemfile
using:
bundle install
(Optional) Prototype and test with Firebase Local Emulator Suite
For mobile developers, before talking about how your app writes to and reads
from Cloud Firestore, let's introduce a set of tools you can use to
prototype and test Cloud Firestore functionality:
Firebase Local Emulator Suite. If you're trying out different data models,
optimizing your security rules, or working to find the most cost-effective way
to interact with the back-end, being able to work locally without deploying
live services can be a great idea.
A Cloud Firestore emulator is part of the Local Emulator Suite, which
enables your app to interact with your emulated database content and config, as
well as optionally your emulated project resources (functions, other databases,
and security rules).
Using the Cloud Firestore emulator involves just a few steps:
- Adding a line of code to your app's test config to connect to the emulator.
- From the root of your local project directory, running
firebase emulators:start
.
- Making calls from your app's prototype code using a Cloud Firestore platform
SDK as usual.
A detailed
walkthrough involving Cloud Firestore and Cloud Functions
is available. You should also have a look at the
Local Emulator Suite introduction
.
Initialize Cloud Firestore
Initialize an instance of Cloud Firestore:
Web modular API
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";
// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
FIREBASE_CONFIGURATION
};
// Initialize Firebase
const app = initializeApp(firebaseConfig);
// Initialize Cloud Firestore and get a reference to the service
const db = getFirestore(app);
Replace
FIREBASE_CONFIGURATION
with your web app's
firebaseConfig
.
To persist data when the device loses its connection, see the
Enable Offline Data
documentation.
Web namespaced API
import firebase from "firebase/app";
import "firebase/firestore";
// TODO: Replace the following with your app's Firebase project configuration
// See: https://support.google.com/firebase/answer/7015592
const firebaseConfig = {
FIREBASE_CONFIGURATION
};
// Initialize Firebase
firebase.initializeApp(firebaseConfig);
// Initialize Cloud Firestore and get a reference to the service
const db = firebase.firestore();
Replace
FIREBASE_CONFIGURATION
with your web app's
firebaseConfig
.
To persist data when the device loses its connection, see the
Enable Offline Data
documentation.
Swift
Note:
This product is not available on watchOS and App Clip targets.
import FirebaseCore
import FirebaseFirestore
FirebaseApp.configure()
let db = Firestore.firestore()
Objective-C
Note:
This product is not available on watchOS and App Clip targets.
@import FirebaseCore;
@import FirebaseFirestore;
// Use Firebase library to configure APIs
[FIRApp configure];
FIRFirestore *defaultFirestore = [FIRFirestore firestore];
Kotlin+KTX
// Access a Cloud Firestore instance from your Activity
val db = Firebase.firestore
Java
// Access a Cloud Firestore instance from your Activity
FirebaseFirestore db = FirebaseFirestore.getInstance();
Dart
db = FirebaseFirestore.instance;
Java
The Cloud Firestore SDK is initialized in different ways depending on
your environment. Below are the most common methods. For a complete reference,
see
Initialize
the Admin SDK
.
Initialize on Google Cloud
import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;
import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;
// Use the application default credentials
GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
FirebaseOptions options = new FirebaseOptions.Builder()
.setCredentials(credentials)
.setProjectId(projectId)
.build();
FirebaseApp.initializeApp(options);
Firestore db = FirestoreClient.getFirestore();
Initialize on your own server
To use the Firebase Admin SDK on your own server, use a
service account
.
Go to
IAM & admin > Service accounts
in the Google Cloud console. Generate a new private key and save the JSON
file. Then use the file to initialize the SDK:
import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;
import com.google.firebase.FirebaseApp;
import com.google.firebase.FirebaseOptions;
// Use a service account
InputStream serviceAccount = new FileInputStream("
path/to/serviceAccount.json
");
GoogleCredentials credentials = GoogleCredentials.fromStream(serviceAccount);
FirebaseOptions options = new FirebaseOptions.Builder()
.setCredentials(credentials)
.build();
FirebaseApp.initializeApp(options);
Firestore db = FirestoreClient.getFirestore();
Python
The Cloud Firestore SDK is initialized in different ways depending on
your environment. Below are the most common methods. For a complete reference,
see
Initialize
the Admin SDK
.
Initialize on Google Cloud
import firebase_admin
from firebase_admin import firestore
# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore.client()
An existing application default credential can also be used to initialize the SDK.
import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore
# Use the application default credentials.
cred = credentials.ApplicationDefault()
firebase_admin.initialize_app(cred)
db = firestore.client()
Initialize on your own server
To use the Firebase Admin SDK on your own server, use a
service account
.
Go to
IAM & admin > Service accounts
in the Google Cloud console. Generate a new private key and save the JSON
file. Then use the file to initialize the SDK:
import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore
# Use a service account.
cred = credentials.Certificate('path/to/serviceAccount.json')
app = firebase_admin.initialize_app(cred)
db = firestore.client()
Python
The Cloud Firestore SDK is initialized in different ways depending on
your environment. Below are the most common methods. For a complete reference,
see
Initialize
the Admin SDK
.
Initialize on Google Cloud
import firebase_admin
from firebase_admin import firestore_async
# Application Default credentials are automatically created.
app = firebase_admin.initialize_app()
db = firestore_async.client()
An existing application default credential can also be used to initialize the SDK.
import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore_async
# Use the application default credentials.
cred = credentials.ApplicationDefault()
firebase_admin.initialize_app(cred)
db = firestore_async.client()
Initialize on your own server
To use the Firebase Admin SDK on your own server, use a
service account
.
Go to
IAM & admin > Service accounts
in the Google Cloud console. Generate a new private key and save the JSON
file. Then use the file to initialize the SDK:
import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore_async
# Use a service account.
cred = credentials.Certificate('path/to/serviceAccount.json')
app = firebase_admin.initialize_app(cred)
db = firestore_async.client()
C++
// Make sure the call to `Create()` happens some time before you call Firestore::GetInstance().
App::Create();
Firestore* db = Firestore::GetInstance();
Node.js
The Cloud Firestore SDK is initialized in different ways depending on
your environment. Below are the most common methods. For a complete reference,
see
Initialize
the Admin SDK
.
-
Initialize on Cloud Functions
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp();
const db = getFirestore();
-
Initialize on Google Cloud
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
initializeApp({
credential: applicationDefault()
});
const db = getFirestore();
-
Initialize on your own server
To use the Firebase Admin SDK on your own server (or any other Node.js environment),
use a
service account
.
Go to
IAM & admin > Service accounts
in the Google Cloud console. Generate a new private key and save the JSON file. Then use the file to initialize the SDK:
const { initializeApp, applicationDefault, cert } = require('firebase-admin/app');
const { getFirestore, Timestamp, FieldValue, Filter } = require('firebase-admin/firestore');
const serviceAccount = require('./path/to/serviceAccountKey.json');
initializeApp({
credential: cert(serviceAccount)
});
const db = getFirestore();
Go
The Cloud Firestore SDK is initialized in different ways depending on
your environment. Below are the most common methods. For a complete reference,
see
Initialize
the Admin SDK
.
Initialize on Google Cloud
import (
"log"
firebase "firebase.google.com/go"
"google.golang.org/api/option"
)
// Use the application default credentials
ctx := context.Background()
conf := &firebase.Config{ProjectID: projectID}
app, err := firebase.NewApp(ctx, conf)
if err != nil {
log.Fatalln(err)
}
client, err := app.Firestore(ctx)
if err != nil {
log.Fatalln(err)
}
defer client.Close()
Initialize on your own server
To use the Firebase Admin SDK on your own server, use a
service account
.
Go to
IAM & admin > Service accounts
in the Google Cloud console. Generate a new private key and save the JSON
file. Then use the file to initialize the SDK:
import (
"log"
firebase "firebase.google.com/go"
"google.golang.org/api/option"
)
// Use a service account
ctx := context.Background()
sa := option.WithCredentialsFile("path/to/serviceAccount.json")
app, err := firebase.NewApp(ctx, nil, sa)
if err != nil {
log.Fatalln(err)
}
client, err := app.Firestore(ctx)
if err != nil {
log.Fatalln(err)
}
defer client.Close()
Unity
using Firebase.Firestore;
using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
Add data
Cloud Firestore stores data in Documents, which are stored in Collections.
Cloud Firestore creates collections and documents implicitly
the first time you add data to the document. You do not need to explicitly
create collections or documents.
Create a new collection and a document using the following example code.
Web modular API
import { collection, addDoc } from "firebase/firestore";
try {
const docRef = await addDoc(collection(db, "users"), {
first: "Ada",
last: "Lovelace",
born: 1815
});
console.log("Document written with ID: ", docRef.id);
} catch (e) {
console.error("Error adding document: ", e);
}
Web namespaced API
db.collection("users").add({
first: "Ada",
last: "Lovelace",
born: 1815
})
.then((docRef) => {
console.log("Document written with ID: ", docRef.id);
})
.catch((error) => {
console.error("Error adding document: ", error);
});
Swift
Note:
This product is not available on watchOS and App Clip targets.
// Add a new document with a generated ID
do {
let ref = try await db.collection("users").addDocument(data: [
"first": "Ada",
"last": "Lovelace",
"born": 1815
])
print("Document added with ID: \(ref.documentID)")
} catch {
print("Error adding document: \(error)")
}
Objective-C
Note:
This product is not available on watchOS and App Clip targets.
// Add a new document with a generated ID
__block FIRDocumentReference *ref =
[[self.db collectionWithPath:@"users"] addDocumentWithData:@{
@"first": @"Ada",
@"last": @"Lovelace",
@"born": @1815
} completion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error adding document: %@", error);
} else {
NSLog(@"Document added with ID: %@", ref.documentID);
}
}];
Kotlin+KTX
// Create a new user with a first and last name
val user = hashMapOf(
"first" to "Ada",
"last" to "Lovelace",
"born" to 1815,
)
// Add a new document with a generated ID
db.collection("users")
.add(user)
.addOnSuccessListener { documentReference ->
Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}")
}
.addOnFailureListener { e ->
Log.w(TAG, "Error adding document", e)
}
Java
// Create a new user with a first and last name
Map<String, Object> user = new HashMap<>();
user.put("first", "Ada");
user.put("last", "Lovelace");
user.put("born", 1815);
// Add a new document with a generated ID
db.collection("users")
.add(user)
.addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
@Override
public void onSuccess(DocumentReference documentReference) {
Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId());
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Error adding document", e);
}
});
Dart
// Create a new user with a first and last name
final user = <String, dynamic>{
"first": "Ada",
"last": "Lovelace",
"born": 1815
};
// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
print('DocumentSnapshot added with ID: ${doc.id}'));
C++
// Add a new document with a generated ID
Future<DocumentReference> user_ref =
db->Collection("users").Add({{"first", FieldValue::String("Ada")},
{"last", FieldValue::String("Lovelace")},
{"born", FieldValue::Integer(1815)}});
user_ref.OnCompletion([](const Future<DocumentReference>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "DocumentSnapshot added with ID: " << future.result()->id()
<< std::endl;
} else {
std::cout << "Error adding document: " << future.error_message() << std::endl;
}
});
Unity
DocumentReference docRef = db.Collection("users").Document("alovelace");
Dictionary<string, object> user = new Dictionary<string, object>
{
{ "First", "Ada" },
{ "Last", "Lovelace" },
{ "Born", 1815 },
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
Debug.Log("Added data to the alovelace document in the users collection.");
});
Now add another document to the
users
collection. Notice that this document
includes a key-value pair (middle name) that does not appear in the first
document. Documents in a collection can contain different sets of information.
Web modular API
// Add a second document with a generated ID.
import { addDoc, collection } from "firebase/firestore";
try {
const docRef = await addDoc(collection(db, "users"), {
first: "Alan",
middle: "Mathison",
last: "Turing",
born: 1912
});
console.log("Document written with ID: ", docRef.id);
} catch (e) {
console.error("Error adding document: ", e);
}
Web namespaced API
// Add a second document with a generated ID.
db.collection("users").add({
first: "Alan",
middle: "Mathison",
last: "Turing",
born: 1912
})
.then((docRef) => {
console.log("Document written with ID: ", docRef.id);
})
.catch((error) => {
console.error("Error adding document: ", error);
});
Swift
Note:
This product is not available on watchOS and App Clip targets.
// Add a second document with a generated ID.
do {
let ref = try await db.collection("users").addDocument(data: [
"first": "Alan",
"middle": "Mathison",
"last": "Turing",
"born": 1912
])
print("Document added with ID: \(ref.documentID)")
} catch {
print("Error adding document: \(error)")
}
Objective-C
Note:
This product is not available on watchOS and App Clip targets.
// Add a second document with a generated ID.
__block FIRDocumentReference *ref =
[[self.db collectionWithPath:@"users"] addDocumentWithData:@{
@"first": @"Alan",
@"middle": @"Mathison",
@"last": @"Turing",
@"born": @1912
} completion:^(NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error adding document: %@", error);
} else {
NSLog(@"Document added with ID: %@", ref.documentID);
}
}];
Kotlin+KTX
// Create a new user with a first, middle, and last name
val user = hashMapOf(
"first" to "Alan",
"middle" to "Mathison",
"last" to "Turing",
"born" to 1912,
)
// Add a new document with a generated ID
db.collection("users")
.add(user)
.addOnSuccessListener { documentReference ->
Log.d(TAG, "DocumentSnapshot added with ID: ${documentReference.id}")
}
.addOnFailureListener { e ->
Log.w(TAG, "Error adding document", e)
}
Java
// Create a new user with a first, middle, and last name
Map<String, Object> user = new HashMap<>();
user.put("first", "Alan");
user.put("middle", "Mathison");
user.put("last", "Turing");
user.put("born", 1912);
// Add a new document with a generated ID
db.collection("users")
.add(user)
.addOnSuccessListener(new OnSuccessListener<DocumentReference>() {
@Override
public void onSuccess(DocumentReference documentReference) {
Log.d(TAG, "DocumentSnapshot added with ID: " + documentReference.getId());
}
})
.addOnFailureListener(new OnFailureListener() {
@Override
public void onFailure(@NonNull Exception e) {
Log.w(TAG, "Error adding document", e);
}
});
Dart
// Create a new user with a first and last name
final user = <String, dynamic>{
"first": "Alan",
"middle": "Mathison",
"last": "Turing",
"born": 1912
};
// Add a new document with a generated ID
db.collection("users").add(user).then((DocumentReference doc) =>
print('DocumentSnapshot added with ID: ${doc.id}'));
C++
db->Collection("users")
.Add({{"first", FieldValue::String("Alan")},
{"middle", FieldValue::String("Mathison")},
{"last", FieldValue::String("Turing")},
{"born", FieldValue::Integer(1912)}})
.OnCompletion([](const Future<DocumentReference>& future) {
if (future.error() == Error::kErrorOk) {
std::cout << "DocumentSnapshot added with ID: "
<< future.result()->id() << std::endl;
} else {
std::cout << "Error adding document: " << future.error_message()
<< std::endl;
}
});
Unity
DocumentReference docRef = db.Collection("users").Document("aturing");
Dictionary<string, object> user = new Dictionary<string, object>
{
{ "First", "Alan" },
{ "Middle", "Mathison" },
{ "Last", "Turing" },
{ "Born", 1912 }
};
docRef.SetAsync(user).ContinueWithOnMainThread(task => {
Debug.Log("Added data to the aturing document in the users collection.");
});
Read data
Use the data
viewer in the
Firebase console
to quickly verify that you've added data to Cloud Firestore.
You can also use the "get" method to retrieve the entire collection.
Web modular API
import { collection, getDocs } from "firebase/firestore";
const querySnapshot = await getDocs(collection(db, "users"));
querySnapshot.forEach((doc) => {
console.log(`${doc.id} => ${doc.data()}`);
});
Web namespaced API
db.collection("users").get().then((querySnapshot) => {
querySnapshot.forEach((doc) => {
console.log(`${doc.id} => ${doc.data()}`);
});
});
Swift
Note:
This product is not available on watchOS and App Clip targets.
do {
let snapshot = try await db.collection("users").getDocuments()
for document in snapshot.documents {
print("\(document.documentID) => \(document.data())")
}
} catch {
print("Error getting documents: \(error)")
}
Objective-C
Note:
This product is not available on watchOS and App Clip targets.
[[self.db collectionWithPath:@"users"]
getDocumentsWithCompletion:^(FIRQuerySnapshot * _Nullable snapshot,
NSError * _Nullable error) {
if (error != nil) {
NSLog(@"Error getting documents: %@", error);
} else {
for (FIRDocumentSnapshot *document in snapshot.documents) {
NSLog(@"%@ => %@", document.documentID, document.data);
}
}
}];
Kotlin+KTX
db.collection("users")
.get()
.addOnSuccessListener { result ->
for (document in result) {
Log.d(TAG, "${document.id} => ${document.data}")
}
}
.addOnFailureListener { exception ->
Log.w(TAG, "Error getting documents.", exception)
}
Java
db.collection("users")
.get()
.addOnCompleteListener(new OnCompleteListener<QuerySnapshot>() {
@Override
public void onComplete(@NonNull Task<QuerySnapshot> task) {
if (task.isSuccessful()) {
for (QueryDocumentSnapshot document : task.getResult()) {
Log.d(TAG, document.getId() + " => " + document.getData());
}
} else {
Log.w(TAG, "Error getting documents.", task.getException());
}
}
});
Dart
await db.collection("users").get().then((event) {
for (var doc in event.docs) {
print("${doc.id} => ${doc.data()}");
}
});
Python
users_ref = db.collection("users")
docs = users_ref.stream()
for doc in docs:
print(f"{doc.id} => {doc.to_dict()}")
C++
Future<QuerySnapshot> users = db->Collection("users").Get();
users.OnCompletion([](const Future<QuerySnapshot>& future) {
if (future.error() == Error::kErrorOk) {
for (const DocumentSnapshot& document : future.result()->documents()) {
std::cout << document << std::endl;
}
} else {
std::cout << "Error getting documents: " << future.error_message()
<< std::endl;
}
});
Unity
CollectionReference usersRef = db.Collection("users");
usersRef.GetSnapshotAsync().ContinueWithOnMainThread(task =>
{
QuerySnapshot snapshot = task.Result;
foreach (DocumentSnapshot document in snapshot.Documents)
{
Debug.Log(String.Format("User: {0}", document.Id));
Dictionary<string, object> documentDictionary = document.ToDictionary();
Debug.Log(String.Format("First: {0}", documentDictionary["First"]));
if (documentDictionary.ContainsKey("Middle"))
{
Debug.Log(String.Format("Middle: {0}", documentDictionary["Middle"]));
}
Debug.Log(String.Format("Last: {0}", documentDictionary["Last"]));
Debug.Log(String.Format("Born: {0}", documentDictionary["Born"]));
}
Debug.Log("Read all data from the users collection.");
});
Secure your data
If you're using the Web, Android, or Apple platforms SDK, use
Firebase
Authentication
and
Cloud Firestore Security Rules
to secure your data in
Cloud Firestore.
Here are some basic rule sets you can use to get started. You can modify your
security rules in the
Rules
tab
of
the console.
Auth required
// Allow read/write access to a document keyed by the user's UID
service cloud.firestore {
match /databases/{database}/documents {
match /users/{uid} {
allow read, write: if request.auth != null && request.auth.uid == uid;
}
}
}
Locked mode
// Deny read/write access to all users under any conditions
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if false;
}
}
}
Before you deploy your Web, Android, or iOS app to production, also take steps
to ensure that only your app clients can access your Cloud Firestore data.
See the
App Check
documentation.
If you're using one of the server SDKs, use
Identity and Access Management
(IAM)
to secure your data
in Cloud Firestore.
Watch a video tutorial
For detailed guidance on getting started with the Cloud Firestore
mobile client libraries, watch one of the following video tutorials:
You can find more videos in the Firebase
YouTube channel
.
Next steps
Deepen your knowledge with the following topics:
- Codelabs
— Learn to use Cloud Firestore in a real app by
following the codelab for
Android
,
iOS
, or
Web
.
- Data model
— Learn more about how data is
structured in Cloud Firestore, including hierarchical data and subcollections.
- Add data
— Learn more about creating and updating data in Cloud Firestore.
- Get data
— Learn more about how to retrieve
data.
- Perform simple and compound queries
— Learn how to run simple and compound queries.
- Order and limit queries
Learn how to order
and limit the data returned by your queries.