This quickstart shows you how to set up Firestore Enterprise edition, add data, then use either Core operations or Pipeline operations to query the data you just added in the Firebase console.
Cloud Firestore supports mobile or web SDKs and server client libraries:
-
Cloud Firestore supports SDKs for Android, iOS, and web and more. Combined with Cloud Firestore Security Rules and Firebase Authentication , the mobile and web SDKs support serverless app architectures where clients connect directly to your Cloud Firestore database.
-
Cloud Firestore supports server client librariesfor Java, Node.js, and Python. Use these client libraries to set up privileged server environments with full access to your database. Learn more about these libraries in the Quickstart for server client libraries .
Create a Firestore Enterprise edition 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 Google Cloud project.
-
Open your project in the Firebase console. In the left panel, expand Buildand then select Firestore database .
-
Click Create database.
-
Select Enterprisefor the database mode.
-
Select Firestore in Native Modefor the operation mode, which supports Core and Pipeline operations.
-
Select a location for your database.
-
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.
- Production mode
-
Denies all reads and writes from mobile and web clients. Your authenticated application servers (Python) can still access your database.
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.
-
Click Create.
When you enable Firestore Enterprise edition, 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 .
- The Cloud Firestore
SDK is available as an npm package.
npm install firebase @12.10.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.ktsorapp/build.gradle).dependencies { // Import the BoM for the Firebase platform implementation ( platform ( "com.google.firebase:firebase-bom:34.10.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:26.1.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 ).
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 ); // When initializing Firestore , remember to use the name of the database you created earlier : const db = initializeFirestore ( app , {}, 'your-new-enterprise-database' );
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 () // When initializing Firestore , remember to use the name of the database you created earlier : let db = Firestore . firestore ( database : "your-new-enterprise-database" )
Kotlin
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: val firestore = FirebaseFirestore . getInstance ( "your-new-enterprise-database" )
Java
// Access a Cloud Firestore instance from your Activity // When initializing Firestore, remember to use the name of the database you created earlier: FirebaseFirestore firestore = FirebaseFirestore . getInstance ( "your-new-enterprise-database" );
Add data using Core operations
In order to explore Core operations and Pipeline operations for querying data, add data to your database using Core operations.
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 don't 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 ) " ) }
Kotlin
// 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 ); } });
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 ) " ) }
Kotlin
// 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 ); } });
Read data using Core operations
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 ) " ) }
Kotlin
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 ()); } } });
Read data using Pipeline operations
Now you can compare the Pipeline query experience with the Core query experience.
Web
// The import/require of "firebase/firestore/pipelines" has a side-effect // of extending the Firestore class with the `.pipeline()` method. // Without this import/require, you will not be able to create a Pipeline. // import { execute } from "firebase/firestore/pipelines"; const readDataPipeline = db . pipeline () . collection ( "users" ); // Execute the pipeline and handle the result try { const querySnapshot = await execute ( readDataPipeline ); querySnapshot . results . forEach (( result ) = > { console . log ( ` ${ result . id } => ${ result . data () } ` ); }); } catch ( error ) { console . error ( "Error getting documents: " , error ); }
Swift
do { // Initialize a Firestore Pipeline instance and specify the "users" collection as the // input stage. let snapshot = try await db . pipeline () . collection ( "users" ) . execute () // Execute the pipeline to retrieve documents. // Iterate through the documents in the pipeline results, similar to a regular query // snapshot. for result in snapshot . results { print ( " \( result . id ?? "no ID" ) => \( result . data ) " ) } } catch { print ( "Error getting documents with pipeline: \( error ) " ) }
Kotlin
val readDataPipeline = db . pipeline () . collection ( "users" ) // Execute the pipeline and handle the result readDataPipeline . execute () . addOnSuccessListener { result - > for ( document in result ) { println ( " ${ document . getId () } => ${ document . getData () } " ) } } . addOnFailureListener { exception - > println ( "Error getting documents: $ exception " ) }
Java
Pipeline readDataPipeline = db . pipeline () . collection ( "users" ); readDataPipeline . execute () . addOnSuccessListener ( new OnSuccessListener < Pipeline . Snapshot > () { @Override public void onSuccess ( Pipeline . Snapshot snapshot ) { for ( PipelineResult result : snapshot . getResults ()) { System . out . println ( result . getId () + " => " + result . getData ()); } } }) . addOnFailureListener ( new OnFailureListener () { @Override public void onFailure ( @NonNull Exception e ) { System . out . println ( "Error getting documents: " + e ); } });
Secure your data for mobile and web SDKs
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
;
}
}
}
Production 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 .
Next steps
Deepen your knowledge of Core and Pipeline operations with the following topics:
- Learn more about querying with Core operations
- Learn more about querying with Pipeline operations .
