Getting data (original) (raw)

Skip to main content

There are three ways to retrieve data stored in Firestore. Any of these methods can be used with documents, collections of documents, or the results of queries:

When you set a listener, Firestore sends your listener an initial snapshot of the data, and then another snapshot each time the document changes.

Before you begin

Follow one of the Firestore quickstartsto create a Firestore database.

Initialize Firestore

Initialize an instance of Firestore:

Mobile and web SDKs

Web version 9

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 Firestore and get a reference to the service const db = getFirestore(app);

Replace FIREBASE_CONFIGURATION with your web app'sfirebaseConfig.

To persist data when the device loses its connection, see the Enable Offline Data documentation.

Web version 8

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 Firestore and get a reference to the service const db = firebase.firestore();

Replace FIREBASE_CONFIGURATION with your web app'sfirebaseConfig.

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

Android

// Access a Firestore instance from your Activity

val db = Firebase.firestore

Java

Android

// Access a Firestore instance from your Activity

FirebaseFirestore db = FirebaseFirestore.getInstance();

Dart

db = FirebaseFirestore.instance;

C++

// Make sure the call to Create() happens some time before you call Firestore::GetInstance(). App::Create(); Firestore* db = Firestore::GetInstance();

Unity

using Firebase.Firestore; using Firebase.Extensions;

FirebaseFirestore db = FirebaseFirestore.DefaultInstance;

Server client libraries

Java

import com.google.cloud.firestore.Firestore; import com.google.cloud.firestore.FirestoreOptions;

Python

from google.cloud import firestore

The project parameter is optional and represents which project the client

will act on behalf of. If not supplied, the client falls back to the default

project inferred from the environment.

db = firestore.Client(project="my-project-id")

Python

(Async)

from google.cloud import firestore

The project parameter is optional and represents which project the client

will act on behalf of. If not supplied, the client falls back to the default

project inferred from the environment.

db = firestore.AsyncClient(project="my-project-id")

Node.js

const Firestore = require('@google-cloud/firestore');

const db = new Firestore({ projectId: 'YOUR_PROJECT_ID', keyFilename: '/path/to/keyfile.json', });

Go
PHP

PHP

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

C#

C#

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Ruby

Example data

To get started, write some data about cities so we can look at different ways to read it back:

Web version 9

import { collection, doc, setDoc } from "firebase/firestore";

const citiesRef = collection(db, "cities");

await setDoc(doc(citiesRef, "SF"), { name: "San Francisco", state: "CA", country: "USA", capital: false, population: 860000, regions: ["west_coast", "norcal"] }); await setDoc(doc(citiesRef, "LA"), { name: "Los Angeles", state: "CA", country: "USA", capital: false, population: 3900000, regions: ["west_coast", "socal"] }); await setDoc(doc(citiesRef, "DC"), { name: "Washington, D.C.", state: null, country: "USA", capital: true, population: 680000, regions: ["east_coast"] }); await setDoc(doc(citiesRef, "TOK"), { name: "Tokyo", state: null, country: "Japan", capital: true, population: 9000000, regions: ["kanto", "honshu"] }); await setDoc(doc(citiesRef, "BJ"), { name: "Beijing", state: null, country: "China", capital: true, population: 21500000, regions: ["jingjinji", "hebei"] });

Web version 8

var citiesRef = db.collection("cities");

citiesRef.doc("SF").set({ name: "San Francisco", state: "CA", country: "USA", capital: false, population: 860000, regions: ["west_coast", "norcal"] }); citiesRef.doc("LA").set({ name: "Los Angeles", state: "CA", country: "USA", capital: false, population: 3900000, regions: ["west_coast", "socal"] }); citiesRef.doc("DC").set({ name: "Washington, D.C.", state: null, country: "USA", capital: true, population: 680000, regions: ["east_coast"] }); citiesRef.doc("TOK").set({ name: "Tokyo", state: null, country: "Japan", capital: true, population: 9000000, regions: ["kanto", "honshu"] }); citiesRef.doc("BJ").set({ name: "Beijing", state: null, country: "China", capital: true, population: 21500000, regions: ["jingjinji", "hebei"] });

Swift

Note: This product is not available on watchOS and App Clip targets.

let citiesRef = db.collection("cities")

citiesRef.document("SF").setData([ "name": "San Francisco", "state": "CA", "country": "USA", "capital": false, "population": 860000, "regions": ["west_coast", "norcal"] ]) citiesRef.document("LA").setData([ "name": "Los Angeles", "state": "CA", "country": "USA", "capital": false, "population": 3900000, "regions": ["west_coast", "socal"] ]) citiesRef.document("DC").setData([ "name": "Washington D.C.", "country": "USA", "capital": true, "population": 680000, "regions": ["east_coast"] ]) citiesRef.document("TOK").setData([ "name": "Tokyo", "country": "Japan", "capital": true, "population": 9000000, "regions": ["kanto", "honshu"] ]) citiesRef.document("BJ").setData([ "name": "Beijing", "country": "China", "capital": true, "population": 21500000, "regions": ["jingjinji", "hebei"] ])

Objective-C

Note: This product is not available on watchOS and App Clip targets.

FIRCollectionReference *citiesRef = [self.db collectionWithPath:@"cities"]; [[citiesRef documentWithPath:@"SF"] setData:@{ @"name": @"San Francisco", @"state": @"CA", @"country": @"USA", @"capital": @(NO), @"population": @860000, @"regions": @[@"west_coast", @"norcal"] }]; [[citiesRef documentWithPath:@"LA"] setData:@{ @"name": @"Los Angeles", @"state": @"CA", @"country": @"USA", @"capital": @(NO), @"population": @3900000, @"regions": @[@"west_coast", @"socal"] }]; [[citiesRef documentWithPath:@"DC"] setData:@{ @"name": @"Washington D.C.", @"country": @"USA", @"capital": @(YES), @"population": @680000, @"regions": @[@"east_coast"] }]; [[citiesRef documentWithPath:@"TOK"] setData:@{ @"name": @"Tokyo", @"country": @"Japan", @"capital": @(YES), @"population": @9000000, @"regions": @[@"kanto", @"honshu"] }]; [[citiesRef documentWithPath:@"BJ"] setData:@{ @"name": @"Beijing", @"country": @"China", @"capital": @(YES), @"population": @21500000, @"regions": @[@"jingjinji", @"hebei"] }];

Kotlin

Android

val cities = db.collection("cities")

val data1 = hashMapOf( "name" to "San Francisco", "state" to "CA", "country" to "USA", "capital" to false, "population" to 860000, "regions" to listOf("west_coast", "norcal"), ) cities.document("SF").set(data1)

val data2 = hashMapOf( "name" to "Los Angeles", "state" to "CA", "country" to "USA", "capital" to false, "population" to 3900000, "regions" to listOf("west_coast", "socal"), ) cities.document("LA").set(data2)

val data3 = hashMapOf( "name" to "Washington D.C.", "state" to null, "country" to "USA", "capital" to true, "population" to 680000, "regions" to listOf("east_coast"), ) cities.document("DC").set(data3)

val data4 = hashMapOf( "name" to "Tokyo", "state" to null, "country" to "Japan", "capital" to true, "population" to 9000000, "regions" to listOf("kanto", "honshu"), ) cities.document("TOK").set(data4)

val data5 = hashMapOf( "name" to "Beijing", "state" to null, "country" to "China", "capital" to true, "population" to 21500000, "regions" to listOf("jingjinji", "hebei"), ) cities.document("BJ").set(data5)

Java

Android

CollectionReference cities = db.collection("cities");

Map<String, Object> data1 = new HashMap<>(); data1.put("name", "San Francisco"); data1.put("state", "CA"); data1.put("country", "USA"); data1.put("capital", false); data1.put("population", 860000); data1.put("regions", Arrays.asList("west_coast", "norcal")); cities.document("SF").set(data1);

Map<String, Object> data2 = new HashMap<>(); data2.put("name", "Los Angeles"); data2.put("state", "CA"); data2.put("country", "USA"); data2.put("capital", false); data2.put("population", 3900000); data2.put("regions", Arrays.asList("west_coast", "socal")); cities.document("LA").set(data2);

Map<String, Object> data3 = new HashMap<>(); data3.put("name", "Washington D.C."); data3.put("state", null); data3.put("country", "USA"); data3.put("capital", true); data3.put("population", 680000); data3.put("regions", Arrays.asList("east_coast")); cities.document("DC").set(data3);

Map<String, Object> data4 = new HashMap<>(); data4.put("name", "Tokyo"); data4.put("state", null); data4.put("country", "Japan"); data4.put("capital", true); data4.put("population", 9000000); data4.put("regions", Arrays.asList("kanto", "honshu")); cities.document("TOK").set(data4);

Map<String, Object> data5 = new HashMap<>(); data5.put("name", "Beijing"); data5.put("state", null); data5.put("country", "China"); data5.put("capital", true); data5.put("population", 21500000); data5.put("regions", Arrays.asList("jingjinji", "hebei")); cities.document("BJ").set(data5);

Dart

final cities = db.collection("cities"); final data1 = <String, dynamic>{ "name": "San Francisco", "state": "CA", "country": "USA", "capital": false, "population": 860000, "regions": ["west_coast", "norcal"] }; cities.doc("SF").set(data1);

final data2 = <String, dynamic>{ "name": "Los Angeles", "state": "CA", "country": "USA", "capital": false, "population": 3900000, "regions": ["west_coast", "socal"], }; cities.doc("LA").set(data2);

final data3 = <String, dynamic>{ "name": "Washington D.C.", "state": null, "country": "USA", "capital": true, "population": 680000, "regions": ["east_coast"] }; cities.doc("DC").set(data3);

final data4 = <String, dynamic>{ "name": "Tokyo", "state": null, "country": "Japan", "capital": true, "population": 9000000, "regions": ["kanto", "honshu"] }; cities.doc("TOK").set(data4);

final data5 = <String, dynamic>{ "name": "Beijing", "state": null, "country": "China", "capital": true, "population": 21500000, "regions": ["jingjinji", "hebei"], }; cities.doc("BJ").set(data5);

Java
Python

class City: def init(self, name, state, country, capital=False, population=0, regions=[]): self.name = name self.state = state self.country = country self.capital = capital self.population = population self.regions = regions

@staticmethod
def from_dict(source):
    # ...

def to_dict(self):
    # ...

def __repr__(self):
    return f"City(\
            name={self.name}, \
            country={self.country}, \
            population={self.population}, \
            capital={self.capital}, \
            regions={self.regions}\
        )"

cities_ref = db.collection("cities") cities_ref.document("BJ").set( City("Beijing", None, "China", True, 21500000, ["hebei"]).to_dict() ) cities_ref.document("SF").set( City( "San Francisco", "CA", "USA", False, 860000, ["west_coast", "norcal"] ).to_dict() ) cities_ref.document("LA").set( City( "Los Angeles", "CA", "USA", False, 3900000, ["west_coast", "socal"] ).to_dict() ) cities_ref.document("DC").set( City("Washington D.C.", None, "USA", True, 680000, ["east_coast"]).to_dict() ) cities_ref.document("TOK").set( City("Tokyo", None, "Japan", True, 9000000, ["kanto", "honshu"]).to_dict() )

Python

(Async)

C++

CollectionReference cities = db->Collection("cities");

cities.Document("SF").Set({ {"name", FieldValue::String("San Francisco")}, {"state", FieldValue::String("CA")}, {"country", FieldValue::String("USA")}, {"capital", FieldValue::Boolean(false)}, {"population", FieldValue::Integer(860000)}, {"regions", FieldValue::Array({FieldValue::String("west_coast"), FieldValue::String("norcal")})}, });

cities.Document("LA").Set({ {"name", FieldValue::String("Los Angeles")}, {"state", FieldValue::String("CA")}, {"country", FieldValue::String("USA")}, {"capital", FieldValue::Boolean(false)}, {"population", FieldValue::Integer(3900000)}, {"regions", FieldValue::Array({FieldValue::String("west_coast"), FieldValue::String("socal")})}, });

cities.Document("DC").Set({ {"name", FieldValue::String("Washington D.C.")}, {"state", FieldValue::Null()}, {"country", FieldValue::String("USA")}, {"capital", FieldValue::Boolean(true)}, {"population", FieldValue::Integer(680000)}, {"regions", FieldValue::Array({FieldValue::String("east_coast")})}, });

cities.Document("TOK").Set({ {"name", FieldValue::String("Tokyo")}, {"state", FieldValue::Null()}, {"country", FieldValue::String("Japan")}, {"capital", FieldValue::Boolean(true)}, {"population", FieldValue::Integer(9000000)}, {"regions", FieldValue::Array({FieldValue::String("kanto"), FieldValue::String("honshu")})}, });

cities.Document("BJ").Set({ {"name", FieldValue::String("Beijing")}, {"state", FieldValue::Null()}, {"country", FieldValue::String("China")}, {"capital", FieldValue::Boolean(true)}, {"population", FieldValue::Integer(21500000)}, {"regions", FieldValue::Array({FieldValue::String("jingjinji"), FieldValue::String("hebei")})}, });

Node.js
Go
PHP

PHP

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

CollectionReference citiesRef = db.Collection("cities"); citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){ { "Name", "San Francisco" }, { "State", "CA" }, { "Country", "USA" }, { "Capital", false }, { "Population", 860000 } }).ContinueWithOnMainThread(task => citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){ { "Name", "Los Angeles" }, { "State", "CA" }, { "Country", "USA" }, { "Capital", false }, { "Population", 3900000 } }) ).ContinueWithOnMainThread(task => citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){ { "Name", "Washington D.C." }, { "State", null }, { "Country", "USA" }, { "Capital", true }, { "Population", 680000 } }) ).ContinueWithOnMainThread(task => citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){ { "Name", "Tokyo" }, { "State", null }, { "Country", "Japan" }, { "Capital", true }, { "Population", 9000000 } }) ).ContinueWithOnMainThread(task => citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){ { "Name", "Beijing" }, { "State", null }, { "Country", "China" }, { "Capital", true }, { "Population", 21500000 } }) );

C#
Ruby

Get a document

The following example shows how to retrieve the contents of a single document using get():

Web version 9

import { doc, getDoc } from "firebase/firestore";

const docRef = doc(db, "cities", "SF"); const docSnap = await getDoc(docRef);

if (docSnap.exists()) { console.log("Document data:", docSnap.data()); } else { // docSnap.data() will be undefined in this case console.log("No such document!"); }

Web version 8

var docRef = db.collection("cities").doc("SF");

docRef.get().then((doc) => { if (doc.exists) { console.log("Document data:", doc.data()); } else { // doc.data() will be undefined in this case console.log("No such document!"); } }).catch((error) => { console.log("Error getting document:", error); });

Swift

Note: This product is not available on watchOS and App Clip targets.

let docRef = db.collection("cities").document("SF")

do { let document = try await docRef.getDocument() if document.exists { let dataDescription = document.data().map(String.init(describing:)) ?? "nil" print("Document data: (dataDescription)") } else { print("Document does not exist") } } catch { print("Error getting document: (error)") }

Objective-C

Note: This product is not available on watchOS and App Clip targets.

FIRDocumentReference *docRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"]; [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) { if (snapshot.exists) { // Document data may be nil if the document exists but has no keys or values. NSLog(@"Document data: %@", snapshot.data); } else { NSLog(@"Document does not exist"); } }];

Kotlin

Android

val docRef = db.collection("cities").document("SF") docRef.get() .addOnSuccessListener { document -> if (document != null) { Log.d(TAG, "DocumentSnapshot data: ${document.data}") } else { Log.d(TAG, "No such document") } } .addOnFailureListener { exception -> Log.d(TAG, "get failed with ", exception) }

Java

Android

DocumentReference docRef = db.collection("cities").document("SF"); docRef.get().addOnCompleteListener(new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { DocumentSnapshot document = task.getResult(); if (document.exists()) { Log.d(TAG, "DocumentSnapshot data: " + document.getData()); } else { Log.d(TAG, "No such document"); } } else { Log.d(TAG, "get failed with ", task.getException()); } } });

Dart

final docRef = db.collection("cities").doc("SF"); docRef.get().then( (DocumentSnapshot doc) { final data = doc.data() as Map<String, dynamic>; // ... }, onError: (e) => print("Error getting document: $e"), );

Java
Python
Python

(Async)

C++

DocumentReference doc_ref = db->Collection("cities").Document("SF"); doc_ref.Get().OnCompletion([](const Future& future) { if (future.error() == Error::kErrorOk) { const DocumentSnapshot& document = *future.result(); if (document.exists()) { std::cout << "DocumentSnapshot id: " << document.id() << std::endl; } else { std::cout << "no such document" << std::endl; } } else { std::cout << "Get failed with: " << future.error_message() << std::endl; } });

Node.js
Go
PHP

PHP

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

DocumentReference docRef = db.Collection("cities").Document("SF"); docRef.GetSnapshotAsync().ContinueWithOnMainThread(task => { DocumentSnapshot snapshot = task.Result; if (snapshot.Exists) { Debug.Log(String.Format("Document data for {0} document:", snapshot.Id)); Dictionary<string, object> city = snapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value)); } } else { Debug.Log(String.Format("Document {0} does not exist!", snapshot.Id)); } });

C#
Ruby

Source Options

For platforms with offline support, you can set the source option to control how a get call uses the offline cache.

By default, a get call will attempt to fetch the latest document snapshot from your database. On platforms with offline support, the client library will use the offline cache if the network is unavailable or if the request times out.

You can specify the source option in a get() call to change the default behavior. You can fetch from only the database and ignore the offline cache, or you can fetch from only the offline cache. For example:

Web version 9

import { doc, getDocFromCache } from "firebase/firestore";

const docRef = doc(db, "cities", "SF");

// Get a document, forcing the SDK to fetch from the offline cache. try { const doc = await getDocFromCache(docRef);

// Document was found in the cache. If no cached document exists, // an error will be returned to the 'catch' block below. console.log("Cached document data:", doc.data()); } catch (e) { console.log("Error getting cached document:", e); }

Web version 8

var docRef = db.collection("cities").doc("SF");

// Valid options for source are 'server', 'cache', or // 'default'. See https://firebase.google.com/docs/reference/js/v8/firebase.firestore.GetOptions // for more information. var getOptions = { source: 'cache' };

// Get a document, forcing the SDK to fetch from the offline cache. docRef.get(getOptions).then((doc) => { // Document was found in the cache. If no cached document exists, // an error will be returned to the 'catch' block below. console.log("Cached document data:", doc.data()); }).catch((error) => { console.log("Error getting cached document:", error); });

Swift

Note: This product is not available on watchOS and App Clip targets.

let docRef = db.collection("cities").document("SF")

do { // Force the SDK to fetch the document from the cache. Could also specify // FirestoreSource.server or FirestoreSource.default. let document = try await docRef.getDocument(source: .cache) if document.exists { let dataDescription = document.data().map(String.init(describing:)) ?? "nil" print("Cached document data: (dataDescription)") } else { print("Document does not exist in cache") } } catch { print("Error getting document: (error)") }

Objective-C

Note: This product is not available on watchOS and App Clip targets.

FIRDocumentReference *docRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"SF"];

// Force the SDK to fetch the document from the cache. Could also specify // FIRFirestoreSourceServer or FIRFirestoreSourceDefault. [docRef getDocumentWithSource:FIRFirestoreSourceCache completion:^(FIRDocumentSnapshot *snapshot, NSError *error) { if (snapshot != NULL) { // The document data was found in the cache. NSLog(@"Cached document data: %@", snapshot.data); } else { // The document data was not found in the cache. NSLog(@"Document does not exist in cache: %@", error); } }];

Kotlin

Android

val docRef = db.collection("cities").document("SF")

// Source can be CACHE, SERVER, or DEFAULT. val source = Source.CACHE

// Get the document, forcing the SDK to use the offline cache docRef.get(source).addOnCompleteListener { task -> if (task.isSuccessful) { // Document found in the offline cache val document = task.result Log.d(TAG, "Cached document data: ${document?.data}") } else { Log.d(TAG, "Cached get failed: ", task.exception) } }

Java

Android

DocumentReference docRef = db.collection("cities").document("SF");

// Source can be CACHE, SERVER, or DEFAULT. Source source = Source.CACHE;

// Get the document, forcing the SDK to use the offline cache docRef.get(source).addOnCompleteListener(new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { // Document found in the offline cache DocumentSnapshot document = task.getResult(); Log.d(TAG, "Cached document data: " + document.getData()); } else { Log.d(TAG, "Cached get failed: ", task.getException()); } } });

Dart

final docRef = db.collection("cities").doc("SF");

// Source can be CACHE, SERVER, or DEFAULT. const source = Source.cache;

docRef.get(const GetOptions(source: source)).then( (res) => print("Successfully completed"), onError: (e) => print("Error completing: $e"), );

Java

Not supported in the Java SDK.

Python

Not supported in the Python SDK.

C++

DocumentReference doc_ref = db->Collection("cities").Document("SF"); Source source = Source::kCache; doc_ref.Get(source).OnCompletion([](const Future& future) { if (future.error() == Error::kErrorOk) { const DocumentSnapshot& document = *future.result(); if (document.exists()) { std::cout << "Cached document id: " << document.id() << std::endl; } else { } } else { std::cout << "Cached get failed: " << future.error_message() << std::endl; } });

Node.js

Not supported in the Node.js SDK.

Go

Not supported in the Go SDK.

PHP

Not supported in the PHP SDK.

Unity

Not supported in the Unity SDK.

C#

Not supported in the C# SDK.

Ruby

Not supported in the Ruby SDK.

Custom objects

The previous example retrieved the contents of the document as a map, but in some languages it's often more convenient to use a custom object type. In Add Data, you defined a City class that you used to define each city. You can turn your document back into a Cityobject:

To use custom objects, you must define aFirestoreDataConverterfunction for your class. For example:

Web version 9

class City { constructor (name, state, country ) { this.name = name; this.state = state; this.country = country; } toString() { return this.name + ', ' + this.state + ', ' + this.country; } }

// Firestore data converter const cityConverter = { toFirestore: (city) => { return { name: city.name, state: city.state, country: city.country }; }, fromFirestore: (snapshot, options) => { const data = snapshot.data(options); return new City(data.name, data.state, data.country); } };

To use custom objects, you must define aFirestoreDataConverterfunction for your class. For example:

Web version 8

class City { constructor (name, state, country ) { this.name = name; this.state = state; this.country = country; } toString() { return this.name + ', ' + this.state + ', ' + this.country; } }

// Firestore data converter var cityConverter = { toFirestore: function(city) { return { name: city.name, state: city.state, country: city.country }; }, fromFirestore: function(snapshot, options){ const data = snapshot.data(options); return new City(data.name, data.state, data.country); } };

Call your data converter with your read operations. After conversion, you can access custom object methods:

Web version 9

import { doc, getDoc} from "firebase/firestore";

const ref = doc(db, "cities", "LA").withConverter(cityConverter); const docSnap = await getDoc(ref); if (docSnap.exists()) { // Convert to City object const city = docSnap.data(); // Use a City instance method console.log(city.toString()); } else { console.log("No such document!"); }

Call your data converter with your read operations. After conversion, you can access custom object methods:

Web version 8

db.collection("cities").doc("LA") .withConverter(cityConverter) .get().then((doc) => { if (doc.exists){ // Convert to City object var city = doc.data(); // Use a City instance method console.log(city.toString()); } else { console.log("No such document!"); }}).catch((error) => { console.log("Error getting document:", error); });

Swift

Note: This product is not available on watchOS and App Clip targets.

To support automatic type serialization in Swift, your type must conform to theCodable protocol.

let docRef = db.collection("cities").document("BJ")

do { let city = try await docRef.getDocument(as: City.self) print("City: (city)") } catch { print("Error decoding city: (error)") }

Objective-C

Note: This product is not available on watchOS and App Clip targets.

In Objective-C you must do this manually.

FIRDocumentReference *docRef = [[self.db collectionWithPath:@"cities"] documentWithPath:@"BJ"]; [docRef getDocumentWithCompletion:^(FIRDocumentSnapshot *snapshot, NSError *error) { FSTCity *city = [[FSTCity alloc] initWithDictionary:snapshot.data]; if (city != nil) { NSLog(@"City: %@", city); } else { NSLog(@"Document does not exist"); } }];

Kotlin

Android

val docRef = db.collection("cities").document("BJ") docRef.get().addOnSuccessListener { documentSnapshot -> val city = documentSnapshot.toObject() }

Java

Android

Important: Each custom class must have a public constructor that takes no arguments. In addition, the class must include a public getter for each property.

DocumentReference docRef = db.collection("cities").document("BJ"); docRef.get().addOnSuccessListener(new OnSuccessListener() { @Override public void onSuccess(DocumentSnapshot documentSnapshot) { City city = documentSnapshot.toObject(City.class); } });

Dart

To use custom objects, you must define Firestore data conversion functions for your class. For example:

class City { final String? name; final String? state; final String? country; final bool? capital; final int? population; final List? regions;

City({ this.name, this.state, this.country, this.capital, this.population, this.regions, });

factory City.fromFirestore( DocumentSnapshot<Map<String, dynamic>> snapshot, SnapshotOptions? options, ) { final data = snapshot.data(); return City( name: data?['name'], state: data?['state'], country: data?['country'], capital: data?['capital'], population: data?['population'], regions: data?['regions'] is Iterable ? List.from(data?['regions']) : null, ); }

Map<String, dynamic> toFirestore() { return { if (name != null) "name": name, if (state != null) "state": state, if (country != null) "country": country, if (capital != null) "capital": capital, if (population != null) "population": population, if (regions != null) "regions": regions, }; } }

Then, create a document reference with your data conversion functions. Any read operations you perform using this reference will return instances of your custom class:

final ref = db.collection("cities").doc("LA").withConverter( fromFirestore: City.fromFirestore, toFirestore: (City city, _) => city.toFirestore(), ); final docSnap = await ref.get(); final city = docSnap.data(); // Convert to City object if (city != null) { print(city); } else { print("No such document."); }

Java

Each custom class must have a public constructor that takes no arguments. In addition, the class must include a public getter for each property.

Python
Python

(Async)

C++

// This is not yet supported.

Node.js

Node.js uses JavaScript objects.

Go
PHP

PHP

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

DocumentReference docRef = db.Collection("cities").Document("BJ");

docRef.GetSnapshotAsync().ContinueWith((task) => { var snapshot = task.Result; if (snapshot.Exists) { Debug.Log(String.Format("Document data for {0} document:", snapshot.Id)); City city = snapshot.ConvertTo(); Debug.Log(String.Format("Name: {0}", city.Name)); Debug.Log(String.Format("State: {0}", city.State)); Debug.Log(String.Format("Country: {0}", city.Country)); Debug.Log(String.Format("Capital: {0}", city.Capital)); Debug.Log(String.Format("Population: {0}", city.Population)); } else { Debug.Log(String.Format("Document {0} does not exist!", snapshot.Id)); } });

C#
Ruby

Not applicable for Ruby.

Get multiple documents from a collection

You can also retrieve multiple documents with one request by querying documents in a collection. For example, you can use where() to query for all of the documents that meet a certain condition, then use get() to retrieve the results:

Web version 9

import { collection, query, where, getDocs } from "firebase/firestore";

const q = query(collection(db, "cities"), where("capital", "==", true));

const querySnapshot = await getDocs(q); querySnapshot.forEach((doc) => { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); });

Web version 8

db.collection("cities").where("capital", "==", true) .get() .then((querySnapshot) => { querySnapshot.forEach((doc) => { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); }); }) .catch((error) => { console.log("Error getting documents: ", error); });

Swift

Note: This product is not available on watchOS and App Clip targets.

do { let querySnapshot = try await db.collection("cities").whereField("capital", isEqualTo: true) .getDocuments() for document in querySnapshot.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:@"cities"] queryWhereField:@"capital" isEqualTo:@(YES)] getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) { if (error != nil) { NSLog(@"Error getting documents: %@", error); } else { for (FIRDocumentSnapshot *document in snapshot.documents) { NSLog(@"%@ => %@", document.documentID, document.data); } } }];

Kotlin

Android

db.collection("cities") .whereEqualTo("capital", true) .get() .addOnSuccessListener { documents -> for (document in documents) { Log.d(TAG, "${document.id} => ${document.data}") } } .addOnFailureListener { exception -> Log.w(TAG, "Error getting documents: ", exception) }

Java

Android

db.collection("cities") .whereEqualTo("capital", true) .get() .addOnCompleteListener(new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { for (QueryDocumentSnapshot document : task.getResult()) { Log.d(TAG, document.getId() + " => " + document.getData()); } } else { Log.d(TAG, "Error getting documents: ", task.getException()); } } });

Dart

db.collection("cities").where("capital", isEqualTo: true).get().then( (querySnapshot) { print("Successfully completed"); for (var docSnapshot in querySnapshot.docs) { print('${docSnapshot.id} => ${docSnapshot.data()}'); } }, onError: (e) => print("Error completing: $e"), );

Java
Python
Python

(Async)

C++

db->Collection("cities") .WhereEqualTo("capital", FieldValue::Boolean(true)) .Get() .OnCompletion([](const Future& 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

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

Query capitalQuery = db.Collection("cities").WhereEqualTo("Capital", true); capitalQuery.GetSnapshotAsync().ContinueWithOnMainThread(task => { QuerySnapshot capitalQuerySnapshot = task.Result; foreach (DocumentSnapshot documentSnapshot in capitalQuerySnapshot.Documents) { Debug.Log(String.Format("Document data for {0} document:", documentSnapshot.Id)); Dictionary<string, object> city = documentSnapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value)); }

// Newline to separate entries
Debug.Log("");

}; });

C#
Ruby

By default, Firestore retrieves all documents that satisfy the query in ascending order by document ID, but you can order and limit the data returned.

Get all documents in a collection

In addition, you can retrieve all documents in a collection by omitting thewhere() filter entirely:

Web version 9

import { collection, getDocs } from "firebase/firestore";

const querySnapshot = await getDocs(collection(db, "cities")); querySnapshot.forEach((doc) => { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); });

Web version 8

db.collection("cities").get().then((querySnapshot) => { querySnapshot.forEach((doc) => { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); }); });

Swift

Note: This product is not available on watchOS and App Clip targets.

do { let querySnapshot = try await db.collection("cities").getDocuments() for document in querySnapshot.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:@"cities"] getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) { if (error != nil) { NSLog(@"Error getting documents: %@", error); } else { for (FIRDocumentSnapshot *document in snapshot.documents) { NSLog(@"%@ => %@", document.documentID, document.data); } } }];

Kotlin

Android

db.collection("cities") .get() .addOnSuccessListener { result -> for (document in result) { Log.d(TAG, "${document.id} => ${document.data}") } } .addOnFailureListener { exception -> Log.d(TAG, "Error getting documents: ", exception) }

Java

Android

db.collection("cities") .get() .addOnCompleteListener(new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { for (QueryDocumentSnapshot document : task.getResult()) { Log.d(TAG, document.getId() + " => " + document.getData()); } } else { Log.d(TAG, "Error getting documents: ", task.getException()); } } });

Dart

db.collection("cities").get().then( (querySnapshot) { print("Successfully completed"); for (var docSnapshot in querySnapshot.docs) { print('${docSnapshot.id} => ${docSnapshot.data()}'); } }, onError: (e) => print("Error completing: $e"), );

Java
Python
Python

(Async)

C++

db->Collection("cities").Get().OnCompletion( [](const Future& 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

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

Query allCitiesQuery = db.Collection("cities"); allCitiesQuery.GetSnapshotAsync().ContinueWithOnMainThread(task => { QuerySnapshot allCitiesQuerySnapshot = task.Result; foreach (DocumentSnapshot documentSnapshot in allCitiesQuerySnapshot.Documents) { Debug.Log(String.Format("Document data for {0} document:", documentSnapshot.Id)); Dictionary<string, object> city = documentSnapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Debug.Log(String.Format("{0}: {1}", pair.Key, pair.Value)); }

// Newline to separate entries
Debug.Log("");

} });

C#
Ruby

Get all documents in a subcollection

To retrieve all the documents from a subcollection, create a reference with the complete path to that subcollection:

Web version 9

const { collection, getDocs } = require("firebase/firestore"); // Query a reference to a subcollection const querySnapshot = await getDocs(collection(db, "cities", "SF", "landmarks")); querySnapshot.forEach((doc) => { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); });

Web version 8

// Snippet not available

Swift

do { let querySnapshot = try await db.collection("cities/SF/landmarks").getDocuments() for document in querySnapshot.documents { print("(document.documentID) => (document.data())") } } catch { print("Error getting documents: (error)") }

Objective-C

[[self.db collectionWithPath:@"cities/SF/landmarks"] getDocumentsWithCompletion:^(FIRQuerySnapshot *snapshot, NSError *error) { if (error != nil) { NSLog(@"Error getting documents: %@", error); } else { for (FIRDocumentSnapshot *document in snapshot.documents) { NSLog(@"%@ => %@", document.documentID, document.data); } } }];

Kotlin

Android

db.collection("cities") .document("SF") .collection("landmarks") .get() .addOnSuccessListener { result -> for (document in result) { Log.d(TAG, "${document.id} => ${document.data}") } } .addOnFailureListener { exception -> Log.d(TAG, "Error getting documents: ", exception) }

Java

Android

db.collection("cities") .document("SF") .collection("landmarks") .get() .addOnCompleteListener(new OnCompleteListener() { @Override public void onComplete(@NonNull Task task) { if (task.isSuccessful()) { for (QueryDocumentSnapshot document : task.getResult()) { Log.d(TAG, document.getId() + " => " + document.getData()); } } else { Log.d(TAG, "Error getting documents: ", task.getException()); } } });

Dart

db.collection("cities").doc("SF").collection("landmarks").get().then( (querySnapshot) { print("Successfully completed"); for (var docSnapshot in querySnapshot.docs) { print('${docSnapshot.id} => ${docSnapshot.data()}'); } }, onError: (e) => print("Error completing: $e"), );

Java

// Snippet not available

Python

// Snippet not available

Python

(Async)

// Snippet not available

C++

// Snippet not available

Node.js

// Snippet not available

Go

// Snippet not available

PHP

// Snippet not available

Unity

// Snippet not available

C#

// Snippet not available

Ruby

// Snippet not available

Get multiple documents from a collection group

A collection group consists of all collections with the same ID. For example, if each document in your cities collection has a subcollection calledlandmarks, all of the landmarks subcollections belong to the same collection group. By default, queries retrieve results from a single collection in your database. Use a collection group query to retrieve results from a collection group instead of from a single collection.

List subcollections of a document

The listCollections() method of the Firestore server client libraries lists all subcollections of a document reference.

Retrieving a list of collections is not possible with the mobile/web client libraries. You should only look up collection names as part of administrative tasks in trusted server environments. If you find that you need this capability in the mobile/web client libraries, consider restructuring your data so that subcollection names are predictable.

Web

Not available in the Web client library.

Swift

Not available in the Swift client library.

Objective-C

Not available in the Objective-C client library.

Kotlin

Android

Not available in the Android client library.

Java

Android

Not available in the Android client library.

Dart

Not available in the Flutter client library.

Java
Python
Python

(Async)

C++

Not available in the C++ client library.

Node.js
Go
PHP

PHP

To authenticate to Firestore, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

Unity

// This is not yet supported in the Unity SDK.

C#
Ruby

Learn more about different types of queries.

For more information on error codes and how to resolve latency issues when getting data check out the troubleshooting page.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-18 UTC.