Cloud Firestore provides powerful query functionality for specifying which documents you want to retrieve from a collection. These queries can also be used with either get() or addSnapshotListener(), as described in Get Data.
Order and limit data
By default, a query retrieves all documents that satisfy the query in ascending order by document ID. You can specify the sort order for your data using orderBy(), and you can limit the number of documents retrieved using limit(). If you specify a limit(), the value must be greater than or equal to zero.
For example, you could query for the first 3 cities alphabetically with:
Web
import { query, orderBy, limit } from "firebase/firestore"; const q = query(citiesRef, orderBy("name"), limit(3));
Web
citiesRef.orderBy("name").limit(3);
Swift
citiesRef.order(by: "name").limit(to: 3)
Objective-C
[[citiesRef queryOrderedByField:@"name"] queryLimitedTo:3];
Kotlin
citiesRef.orderBy("name").limit(3)
Java
citiesRef.orderBy("name").limit(3);
Dart
final citiesRef = db.collection("cities"); citiesRef.orderBy("name").limit(3);
Java
Python
Python
C++
cities_ref.OrderBy("name").Limit(3);
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Unity
Query query = citiesRef.OrderBy("Name").Limit(3);
C#
Ruby
You could also sort in descending order to get the last 3 cities:
Web
import { query, orderBy, limit } from "firebase/firestore"; const q = query(citiesRef, orderBy("name", "desc"), limit(3));
Web
citiesRef.orderBy("name", "desc").limit(3);
Swift
citiesRef.order(by: "name", descending: true).limit(to: 3)
Objective-C
[[citiesRef queryOrderedByField:@"name" descending:YES] queryLimitedTo:3];
Kotlin
citiesRef.orderBy("name", Query.Direction.DESCENDING).limit(3)
Java
citiesRef.orderBy("name", Direction.DESCENDING).limit(3);
Dart
final citiesRef = db.collection("cities"); citiesRef.orderBy("name", descending: true).limit(3);
Java
Python
Python
C++
cities_ref.OrderBy("name", Query::Direction::kDescending).Limit(3);
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Unity
Query query = citiesRef.OrderByDescending("Name").Limit(3);
C#
Ruby
You can also order by multiple fields. For example, if you wanted to order by state, and within each state order by population in descending order:
Web
import { query, orderBy } from "firebase/firestore"; const q = query(citiesRef, orderBy("state"), orderBy("population", "desc"));
Web
citiesRef.orderBy("state").orderBy("population", "desc");
Swift
citiesRef .order(by: "state") .order(by: "population", descending: true)
Objective-C
[[citiesRef queryOrderedByField:@"state"] queryOrderedByField:@"population" descending:YES];
Kotlin
citiesRef.orderBy("state").orderBy("population", Query.Direction.DESCENDING)
Java
citiesRef.orderBy("state").orderBy("population", Direction.DESCENDING);
Dart
final citiesRef = db.collection("cities"); citiesRef.orderBy("state").orderBy("population", descending: true);
Java
Python
Python
C++
cities_ref.OrderBy("state").OrderBy("name", Query::Direction::kDescending);
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Unity
Query query = citiesRef.OrderBy("State").OrderByDescending("Population");
C#
Ruby
You can combine where() filters with orderBy() and limit(). In the following example, the queries define a population threshold, sort by population in ascending order, and return only the first few results that exceed the threshold:
Web
import { query, where, orderBy, limit } from "firebase/firestore"; const q = query(citiesRef, where("population", ">", 100000), orderBy("population"), limit(2));
Web
citiesRef.where("population", ">", 100000).orderBy("population").limit(2);
Swift
citiesRef .whereField("population", isGreaterThan: 100000) .order(by: "population") .limit(to: 2)
Objective-C
[[[citiesRef queryWhereField:@"population" isGreaterThan:@100000] queryOrderedByField:@"population"] queryLimitedTo:2];
Kotlin
citiesRef.whereGreaterThan("population", 100000).orderBy("population").limit(2)
Java
citiesRef.whereGreaterThan("population", 100000).orderBy("population").limit(2);
Dart
final citiesRef = db.collection("cities"); citiesRef .where("population", isGreaterThan: 100000) .orderBy("population") .limit(2);
Java
Python
Python
C++
cities_ref.WhereGreaterThan("population", FieldValue::Integer(100000)) .OrderBy("population") .Limit(2);
Node.js
Go
PHP
PHP
For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries.
Unity
Query query = citiesRef .WhereGreaterThan("Population", 2500000) .OrderBy("Population") .Limit(2);
C#
Ruby
However, if you have a filter with a range comparison (<, <=, >, >=), your first ordering must be on the same field, see the list of orderBy() limitations below.
Limitations
Note the following restriction for orderBy() clauses:
- An
orderBy()clause also filters for existence of the given fields. The result set will not include documents that do not contain the given fields.
orderBy and existence
When you order a query by a given field, the query can return only the documents where the order-by field exists.
For example, the following query would not return any documents where the population field is not set, even if they otherwise meet the query filters.
Java
db.collection("cities").whereEqualTo("country", “USA”).orderBy(“population”);
A related effect applies to inequalities. A query with an inequality filter on a field also implies ordering by that field. The following query does not return documents without a population field even if country = USA in that document . As a workaround, you can execute separate queries for each ordering or you can assign a value for all fields that you order by.
Java
db.collection(“cities”).where(or(“country”, USA”), greaterThan(“population”, 250000));
The query above includes an implied order-by on the inequality and is equivalent to the following:
Java
db.collection(“cities”).where(or(“country”, USA”), greaterThan(“population”, 250000)).orderBy(“population”);