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
- Follow the instructions to add Firebase to your Web app.
- Add the Firebase and Cloud Firestore libraries to your app:
The Cloud Firestore SDK is also available as an npm package.<script src="https://www.gstatic.com/firebasejs/10.14.0/firebase-app-compat.js"></script> <script src="https://www.gstatic.com/firebasejs/10.14.0/firebase-firestore-compat.js"></script>
You'll need to manually require both Firebase and Cloud Firestore.npm install firebase@10.14.0 --save
import firebase from "firebase/compat/app"; // Required for side-effects import "firebase/firestore";
Web
- Follow the instructions to add Firebase to your Web app.
-
The Cloud Firestore SDK is available as an npm package.
You'll need to import both Firebase and Cloud Firestore.npm install firebase@10.14.0 --save
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:
- Choose the Firestore library.
- When finished, Xcode will automatically begin resolving and downloading your dependencies in the background.
https://github.com/firebase/firebase-ios-sdk
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
orapp/build.gradle
).dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.4.0")) // 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:25.1.0") }
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
'sfirebase_sdk_version.rb
file. If you're not using the latest version offirebase_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:
-
Using Gradle:
compile 'com.google.firebase:firebase-admin:1.32.0'
-
Using Maven:
<dependency> <groupId>com.google.firebase</groupId> <artifactId>firebase-admin</artifactId> <version>1.32.0</version> </dependency>
-
Using Gradle:
- 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.
- 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.
-
You must minify the build to avoid the message Error while merging dex archives
.
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.
-
To authenticate from your development environment, set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable to point to a JSON service account key file. You can create a key file on the API Console Credentials page.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- In your production environment, you do not need to authenticate if you run your application on App Engine or Compute Engine, using the same project that you use for Cloud Firestore. Otherwise, set up a service account.
-
To authenticate from your development environment, set the
- 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.
-
To authenticate from your development environment, set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable to point to a JSON service account key file. You can create a key file on the API Console Credentials page.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- In your production environment, you do not need to authenticate if you run your application on App Engine or Compute Engine, using the same project that you use for Cloud Firestore. Otherwise, set up a service account.
-
To authenticate from your development environment, set the
-
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.
-
To authenticate from your development environment, set the
GOOGLE_APPLICATION_CREDENTIALS
environment variable to point to a JSON service account key file. You can create a key file on the API Console Credentials page.export GOOGLE_APPLICATION_CREDENTIALS="path/to/your/keyfile.json"
- In your production environment, you do not need to authenticate if you run your application on App Engine or Compute Engine, using the same project that you use for Cloud Firestore. Otherwise, set up a service account.
-
To authenticate from your development environment, set the
-
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
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
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
import FirebaseCore import FirebaseFirestore
FirebaseApp.configure() let db = Firestore.firestore()
Objective-C
@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.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();
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.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()
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.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()
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.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()
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()
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Unity
using Firebase.Firestore; using Firebase.Extensions;
FirebaseFirestore db = FirebaseFirestore.DefaultInstance;
C#
C#
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Ruby
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
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
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
// 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
// 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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
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."); });
C#
Ruby
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
// 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
// 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
// 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
// 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}'));
Java
Python
Python
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; } });
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
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."); });
C#
Ruby
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
import { collection, getDocs } from "firebase/firestore"; const querySnapshot = await getDocs(collection(db, "users")); querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); });
Web
db.collection("users").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { console.log(`${doc.id} => ${doc.data()}`); }); });
Swift
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
[[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()}"); } });
Java
Python
users_ref = db.collection("users") docs = users_ref.stream() for doc in docs: print(f"{doc.id} => {doc.to_dict()}")
Python
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; } });
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
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."); });
C#
Ruby
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:
Web
iOS+
Android
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.