There are two ways to retrieve data stored in Cloud Firestore. Either of these methods can be used with documents, collections of documents, or the results of queries:
- Call a method to get the data.
- Set a listener to receive data-change events.
When you set a listener, Cloud Firestore sends your listener an initial snapshot of the data, and then another snapshot each time the document changes.
Example data
To get started, write some data about cities so we can look at different ways to read it back:
Web
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
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
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"] }];
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);
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
CollectionReference cities = db.collection("cities"); List<ApiFuture<WriteResult>> futures = new ArrayList<>(); futures.add(cities.document("SF").set(new City("San Francisco", "CA", "USA", false, 860000L, Arrays.asList("west_coast", "norcal")))); futures.add(cities.document("LA").set(new City("Los Angeles", "CA", "USA", false, 3900000L, Arrays.asList("west_coast", "socal")))); futures.add(cities.document("DC").set(new City("Washington D.C.", null, "USA", true, 680000L, Arrays.asList("east_coast")))); futures.add(cities.document("TOK").set(new City("Tokyo", null, "Japan", true, 9000000L, Arrays.asList("kanto", "honshu")))); futures.add(cities.document("BJ").set(new City("Beijing", null, "China", true, 21500000L, Arrays.asList("jingjinji", "hebei")))); // (optional) block on operation ApiFutures.allAsList(futures).get();
Python
class City(object): 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( u'City(name={}, country={}, population={}, capital={}, regions={})' .format(self.name, self.country, self.population, self.capital, self.regions)) cities_ref = db.collection(u'cities') cities_ref.document(u'SF').set( City(u'San Francisco', u'CA', u'USA', False, 860000, [u'west_coast', u'norcal']).to_dict()) cities_ref.document(u'LA').set( City(u'Los Angeles', u'CA', u'USA', False, 3900000, [u'west_coast', u'socal']).to_dict()) cities_ref.document(u'DC').set( City(u'Washington D.C.', None, u'USA', True, 680000, [u'east_coast']).to_dict()) cities_ref.document(u'TOK').set( City(u'Tokyo', None, u'Japan', True, 9000000, [u'kanto', u'honshu']).to_dict()) cities_ref.document(u'BJ').set( City(u'Beijing', None, u'China', True, 21500000, [u'hebei']).to_dict())
Node.js
const citiesRef = db.collection('cities'); let setSf = citiesRef.doc('SF').set({ name: 'San Francisco', state: 'CA', country: 'USA', capital: false, population: 860000 }); let setLa = citiesRef.doc('LA').set({ name: 'Los Angeles', state: 'CA', country: 'USA', capital: false, population: 3900000 }); let setDc = citiesRef.doc('DC').set({ name: 'Washington, D.C.', state: null, country: 'USA', capital: true, population: 680000 }); let setTok = citiesRef.doc('TOK').set({ name: 'Tokyo', state: null, country: 'Japan', capital: true, population: 9000000 }); let setBj = citiesRef.doc('BJ').set({ name: 'Beijing', state: null, country: 'China', capital: true, population: 21500000 });
Go
cities := []struct { id string c City }{ {id: "SF", c: City{Name: "San Francisco", State: "CA", Country: "USA", Capital: false, Population: 860000}}, {id: "LA", c: City{Name: "Los Angeles", State: "CA", Country: "USA", Capital: false, Population: 3900000}}, {id: "DC", c: City{Name: "Washington D.C.", Country: "USA", Capital: true, Population: 680000}}, {id: "TOK", c: City{Name: "Tokyo", Country: "Japan", Capital: true, Population: 9000000}}, {id: "BJ", c: City{Name: "Beijing", Country: "China", Capital: true, Population: 21500000}}, } for _, c := range cities { _, err := client.Collection("cities").Doc(c.id).Set(ctx, c.c) if err != nil { return err } }
PHP
$citiesRef = $db->collection('cities'); $citiesRef->document('SF')->set([ 'name' => 'San Francisco', 'state' => 'CA', 'country' => 'USA', 'capital' => false, 'population' => 860000 ]); $citiesRef->document('LA')->set([ 'name' => 'Los Angeles', 'state' => 'CA', 'country' => 'USA', 'capital' => false, 'population' => 3900000 ]); $citiesRef->document('DC')->set([ 'name' => 'Washington D.C.', 'state' => null, 'country' => 'USA', 'capital' => true, 'population' => 680000 ]); $citiesRef->document('TOK')->set([ 'name' => 'Tokyo', 'state' => null, 'country' => 'Japan', 'capital' => true, 'population' => 9000000 ]); $citiesRef->document('BJ')->set([ 'name' => 'Beijing', 'state' => null, 'country' => 'China', 'capital' => true, 'population' => 21500000 ]); printf('Added example cities data to the cities collection.' . PHP_EOL);
C#
CollectionReference citiesRef = db.Collection("cities"); await citiesRef.Document("SF").SetAsync(new Dictionary<string, object>(){ { "Name", "San Francisco" }, { "State", "CA" }, { "Country", "USA" }, { "Capital", false }, { "Population", 860000 } }); await citiesRef.Document("LA").SetAsync(new Dictionary<string, object>(){ { "Name", "Los Angeles" }, { "State", "CA" }, { "Country", "USA" }, { "Capital", false }, { "Population", 3900000 } }); await citiesRef.Document("DC").SetAsync(new Dictionary<string, object>(){ { "Name", "Washington D.C." }, { "State", null }, { "Country", "USA" }, { "Capital", true }, { "Population", 680000 } }); await citiesRef.Document("TOK").SetAsync(new Dictionary<string, object>(){ { "Name", "Tokyo" }, { "State", null }, { "Country", "Japan" }, { "Capital", true }, { "Population", 9000000 } }); await citiesRef.Document("BJ").SetAsync(new Dictionary<string, object>(){ { "Name", "Beijing" }, { "State", null }, { "Country", "China" }, { "Capital", true }, { "Population", 21500000 } }); Console.WriteLine("Added example cities data to the cities collection.");
Ruby
cities_ref = firestore.col "cities" cities_ref.doc("SF").set( name: "San Francisco", state: "CA", country: "USA", capital: false, population: 860_000 ) cities_ref.doc("LA").set( name: "Los Angeles", state: "CA", country: "USA", capital: false, population: 3_900_000 ) cities_ref.doc("DC").set( name: "Washington D.C.", state: nil, country: "USA", capital: true, population: 680_000 ) cities_ref.doc("TOK").set( name: "Tokyo", state: nil, country: "Japan", capital: true, population: 9_000_000 ) cities_ref.doc("BJ").set( name: "Beijing", state: nil, country: "China", capital: true, population: 21_500_000 )
Get a document
The following example shows how to retrieve the contents of a single document
using get()
:
Web
var docRef = db.collection("cities").doc("SF"); docRef.get().then(function(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(function(error) { console.log("Error getting document:", error); });
Swift
let docRef = db.collection("cities").document("SF") docRef.getDocument { (document, error) in if let document = document, document.exists { let dataDescription = document.data().map(String.init(describing:)) ?? "nil" print("Document data: \(dataDescription)") } else { print("Document does not exist") } }
Objective-C
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"); } }];
Java
Android
DocumentReference docRef = db.collection("cities").document("SF"); docRef.get().addOnCompleteListener(new OnCompleteListener<DocumentSnapshot>() { @Override public void onComplete(@NonNull Task<DocumentSnapshot> 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()); } } });
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
DocumentReference docRef = db.collection("cities").document("SF"); // asynchronously retrieve the document ApiFuture<DocumentSnapshot> future = docRef.get(); // ... // future.get() blocks on response DocumentSnapshot document = future.get(); if (document.exists()) { System.out.println("Document data: " + document.getData()); } else { System.out.println("No such document!"); }
Python
doc_ref = db.collection(u'cities').document(u'SF') try: doc = doc_ref.get() print(u'Document data: {}'.format(doc.to_dict())) except google.cloud.exceptions.NotFound: print(u'No such document!')
Node.js
let cityRef = db.collection('cities').doc('SF'); let getDoc = cityRef.get() .then(doc => { if (!doc.exists) { console.log('No such document!'); } else { console.log('Document data:', doc.data()); } }) .catch(err => { console.log('Error getting document', err); });
Go
dsnap, err := client.Collection("cities").Doc("SF").Get(ctx) if err != nil { return nil, err } m := dsnap.Data() fmt.Printf("Document data: %#v\n", m)
PHP
$docRef = $db->collection('cities')->document('SF'); $snapshot = $docRef->snapshot(); if ($snapshot->exists()) { printf('Document data:' . PHP_EOL); print_r($snapshot->data()); } else { printf('Document %s does not exist!' . PHP_EOL, $snapshot->id()); }
C#
DocumentReference docRef = db.Collection("cities").Document("SF"); DocumentSnapshot snapshot = await docRef.GetSnapshotAsync(); if (snapshot.Exists) { Console.WriteLine("Document data for {0} document:", snapshot.Id); Dictionary<string, object> city = snapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Console.WriteLine("{0}: {1}", pair.Key, pair.Value); } } else { Console.WriteLine("Document {0} does not exist!", snapshot.Id); }
Ruby
doc_ref = firestore.doc "cities/SF" snapshot = doc_ref.get if snapshot.exists? puts "#{snapshot.document_id} data: #{snapshot.data}." else puts "Document #{snapshot.document_id} does not exist!" end
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
var docRef = db.collection("cities").doc("SF"); // Valid options for source are 'server', 'cache', or // 'default'. See https://firebase.google.com/docs/reference/js/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(function(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(function(error) { console.log("Error getting cached document:", error); });
Swift
let docRef = db.collection("cities").document("SF") // Force the SDK to fetch the document from the cache. Could also specify // FirestoreSource.server or FirestoreSource.default. docRef.getDocument(source: .cache) { (document, error) in if let document = document { let dataDescription = document.data().map(String.init(describing:)) ?? "nil" print("Cached document data: \(dataDescription)") } else { print("Document does not exist in cache") } }
Objective-C
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); } }];
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<DocumentSnapshot>() { @Override public void onComplete(@NonNull Task<DocumentSnapshot> 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()); } } });
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
// Not supported in the Java SDK.
Python
# Not supported in the Python SDK.
Node.js
// Not supported in the Node.js SDK.
Go
// Not supported in the Go SDK.
PHP
// Not supported in the PHP 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 City
object:
Web
// Web uses JavaScript objects
Swift
let docRef = db.collection("cities").document("BJ") docRef.getDocument { (document, error) in if let city = document.flatMap({ $0.data().flatMap({ (data) in return City(dictionary: data) }) }) { print("City: \(city)") } else { print("Document does not exist") } }
Objective-C
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"); } }];
Java
Android
DocumentReference docRef = db.collection("cities").document("BJ"); docRef.get().addOnSuccessListener(new OnSuccessListener<DocumentSnapshot>() { @Override public void onSuccess(DocumentSnapshot documentSnapshot) { City city = documentSnapshot.toObject(City.class); } });
Kotlin
Android
val docRef = db.collection("cities").document("BJ") docRef.get().addOnSuccessListener { documentSnapshot -> val city = documentSnapshot.toObject(City::class.java) }
Java
DocumentReference docRef = db.collection("cities").document("BJ"); // asynchronously retrieve the document ApiFuture<DocumentSnapshot> future = docRef.get(); // block on response DocumentSnapshot document = future.get(); City city = null; if (document.exists()) { // convert document to POJO city = document.toObject(City.class); System.out.println(city); } else { System.out.println("No such document!"); }
Python
doc_ref = db.collection(u'cities').document(u'BJ') doc = doc_ref.get() city = City.from_dict(doc.to_dict()) print(city)
Node.js
// Node.js uses JavaScript objects
Go
dsnap, err := client.Collection("cities").Doc("BJ").Get(ctx) if err != nil { return nil, err } var c City dsnap.DataTo(&c) fmt.Printf("Document data: %#v\n", c)
PHP
// Not applicable for PHP
C#
DocumentReference docRef = db.Collection("cities").Document("BJ"); DocumentSnapshot snapshot = await docRef.GetSnapshotAsync(); if (snapshot.Exists) { Console.WriteLine("Document data for {0} document:", snapshot.Id); City city = snapshot.ConvertTo<City>(); Console.WriteLine("Name: {0}", city.Name); Console.WriteLine("State: {0}", city.State); Console.WriteLine("Country: {0}", city.Country); Console.WriteLine("Capital: {0}", city.Capital); Console.WriteLine("Population: {0}", city.Population); } else { Console.WriteLine("Document {0} does not exist!", snapshot.Id); }
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
db.collection("cities").where("capital", "==", true) .get() .then(function(querySnapshot) { querySnapshot.forEach(function(doc) { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); }); }) .catch(function(error) { console.log("Error getting documents: ", error); });
Swift
db.collection("cities").whereField("capital", isEqualTo: true) .getDocuments() { (querySnapshot, err) in if let err = err { print("Error getting documents: \(err)") } else { for document in querySnapshot!.documents { print("\(document.documentID) => \(document.data())") } } }
Objective-C
[[[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); } } }];
Java
Android
db.collection("cities") .whereEqualTo("capital", true) .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.d(TAG, "Error getting documents: ", task.getException()); } } });
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
//asynchronously retrieve multiple documents ApiFuture<QuerySnapshot> future = db.collection("cities").whereEqualTo("capital", true).get(); // future.get() blocks on response List<QueryDocumentSnapshot> documents = future.get().getDocuments(); for (DocumentSnapshot document : documents) { System.out.println(document.getId() + " => " + document.toObject(City.class)); }
Python
docs = db.collection(u'cities').where(u'capital', u'==', True).stream() for doc in docs: print(u'{} => {}'.format(doc.id, doc.to_dict()))
Node.js
let citiesRef = db.collection('cities'); let query = citiesRef.where('capital', '==', true).get() .then(snapshot => { if (snapshot.empty) { console.log('No matching documents.'); return; } snapshot.forEach(doc => { console.log(doc.id, '=>', doc.data()); }); }) .catch(err => { console.log('Error getting documents', err); });
Go
fmt.Println("All capital cities:") iter := client.Collection("cities").Where("capital", "==", true).Documents(ctx) for { doc, err := iter.Next() if err == iterator.Done { break } if err != nil { return err } fmt.Println(doc.Data()) }
PHP
$citiesRef = $db->collection('cities'); $query = $citiesRef->where('capital', '=', true); $documents = $query->documents(); foreach ($documents as $document) { if ($document->exists()) { printf('Document data for document %s:' . PHP_EOL, $document->id()); print_r($document->data()); printf(PHP_EOL); } else { printf('Document %s does not exist!' . PHP_EOL, $snapshot->id()); } }
C#
Query capitalQuery = db.Collection("cities").WhereEqualTo("Capital", true); QuerySnapshot capitalQuerySnapshot = await capitalQuery.GetSnapshotAsync(); foreach (DocumentSnapshot documentSnapshot in capitalQuerySnapshot.Documents) { Console.WriteLine("Document data for {0} document:", documentSnapshot.Id); Dictionary<string, object> city = documentSnapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Console.WriteLine("{0}: {1}", pair.Key, pair.Value); } Console.WriteLine(""); }
Ruby
cities_ref = firestore.col "cities" query = cities_ref.where "capital", "=", true query.get do |city| puts "#{city.document_id} data: #{city.data}." end
By default, Cloud 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 the
where()
filter entirely:
Web
db.collection("cities").get().then(function(querySnapshot) { querySnapshot.forEach(function(doc) { // doc.data() is never undefined for query doc snapshots console.log(doc.id, " => ", doc.data()); }); });
Swift
db.collection("cities").getDocuments() { (querySnapshot, err) in if let err = err { print("Error getting documents: \(err)") } else { for document in querySnapshot!.documents { print("\(document.documentID) => \(document.data())") } } }
Objective-C
[[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); } } }];
Java
Android
db.collection("cities") .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.d(TAG, "Error getting documents: ", task.getException()); } } });
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
//asynchronously retrieve all documents ApiFuture<QuerySnapshot> future = db.collection("cities").get(); // future.get() blocks on response List<QueryDocumentSnapshot> documents = future.get().getDocuments(); for (QueryDocumentSnapshot document : documents) { System.out.println(document.getId() + " => " + document.toObject(City.class)); }
Python
docs = db.collection(u'cities').stream() for doc in docs: print(u'{} => {}'.format(doc.id, doc.to_dict()))
Node.js
let citiesRef = db.collection('cities'); let allCities = citiesRef.get() .then(snapshot => { snapshot.forEach(doc => { console.log(doc.id, '=>', doc.data()); }); }) .catch(err => { console.log('Error getting documents', err); });
Go
fmt.Println("All cities:") iter := client.Collection("cities").Documents(ctx) for { doc, err := iter.Next() if err == iterator.Done { break } if err != nil { return err } fmt.Println(doc.Data()) }
PHP
$citiesRef = $db->collection('cities'); $documents = $citiesRef->documents(); foreach ($documents as $document) { if ($document->exists()) { printf('Document data for document %s:' . PHP_EOL, $document->id()); print_r($document->data()); printf(PHP_EOL); } else { printf('Document %s does not exist!' . PHP_EOL, $snapshot->id()); } }
C#
Query allCitiesQuery = db.Collection("cities"); QuerySnapshot allCitiesQuerySnapshot = await allCitiesQuery.GetSnapshotAsync(); foreach (DocumentSnapshot documentSnapshot in allCitiesQuerySnapshot.Documents) { Console.WriteLine("Document data for {0} document:", documentSnapshot.Id); Dictionary<string, object> city = documentSnapshot.ToDictionary(); foreach (KeyValuePair<string, object> pair in city) { Console.WriteLine("{0}: {1}", pair.Key, pair.Value); } Console.WriteLine(""); }
Ruby
cities_ref = firestore.col "cities" cities_ref.get do |city| puts "#{city.document_id} data: #{city.data}." end
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 called
landmarks
, 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 getCollections()
method of the Cloud 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 iOS client library.
Objective-C
// Not available in the Objective-C client library.
Java
Android
// Not available in the Android client library.
Kotlin
Android
// Not available in the Android client library.
Java
Iterable<CollectionReference> collections = db.collection("cities").document("SF").getCollections(); for (CollectionReference collRef : collections) { System.out.println("Found subcollection with id: " + collRef.getId()); }
Python
// Not available in the Python client library
Node.js
let sfRef = db.collection('cities').doc('SF'); sfRef.listCollections().then(collections => { collections.forEach(collection => { console.log('Found subcollection with id:', collection.id); }); });
Go
iter := client.Collection("cities").Doc("SF").Collections(ctx) for { collRef, err := iter.Next() if err == iterator.Done { break } if err != nil { return err } fmt.Printf("Found collection with id: %s\n", collRef.ID) }
PHP
$cityRef = $db->collection('cities')->document('SF'); $collections = $cityRef->collections(); foreach ($collections as $collection) { printf('Found subcollection with id: %s' . PHP_EOL, $collection->id()); }
C#
DocumentReference cityRef = db.Collection("cities").Document("SF"); IList<CollectionReference> subcollections = await cityRef.ListCollectionsAsync().ToList(); foreach (CollectionReference subcollectionRef in subcollections) { Console.WriteLine("Found subcollection with ID: {0}", subcollectionRef.Id); }
Ruby
city_ref = firestore.doc "cities/SF" city_ref.cols do |col| puts col.collection_id end
Learn more about different types of queries.