Order and limit data with Cloud Firestore

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));
order_and_limit.js

Web

citiesRef.orderBy("name").limit(3);
test.firestore.js
Swift
Note: This product is not available on watchOS and App Clip targets. 
citiesRef.order(by: "name").limit(to: 3)
ViewController.swift
Objective-C
Note: This product is not available on watchOS and App Clip targets. 
[[citiesRef queryOrderedByField:@"name"] queryLimitedTo:3];
ViewController.m

Kotlin

citiesRef.orderBy("name").limit(3)
DocSnippets.kt

Java

citiesRef.orderBy("name").limit(3);
DocSnippets.java

Dart

final citiesRef = db.collection("cities");
citiesRef.orderBy("name").limit(3);
firestore.dart
Java
Query query = cities.orderBy("name").limit(3);
Query query = cities.orderBy("name").limitToLast(3);
QueryDataSnippets.java
Python
cities_ref = db.collection("cities")
query = cities_ref.order_by("name").limit_to_last(2)
results = query.get()
snippets.py

Python

cities_ref = db.collection("cities")
query = cities_ref.order_by("name").limit_to_last(2)
results = await query.get()
snippets.py
C++
cities_ref.OrderBy("name").Limit(3);
snippets.cpp
Node.js
const firstThreeRes = await citiesRef.orderBy('name').limit(3).get();
index.js
Go
query := cities.OrderBy("name", firestore.Asc).Limit(3)
query := cities.OrderBy("name", firestore.Asc).LimitToLast(3)
query.go
PHP

PHP

For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries. 

$query = $citiesRef->orderBy('name')->limit(3);
query_order_limit.php
Unity
Query query = citiesRef.OrderBy("Name").Limit(3);
C#
Query query = citiesRef.OrderBy("Name").Limit(3);
Program.cs
Ruby
query = cities_ref.order("name").limit(3)
order_limit_data.rb

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));
order_and_limit_desc.js

Web

citiesRef.orderBy("name", "desc").limit(3);
test.firestore.js
Swift
Note: This product is not available on watchOS and App Clip targets. 
citiesRef.order(by: "name", descending: true).limit(to: 3)
ViewController.swift
Objective-C
Note: This product is not available on watchOS and App Clip targets. 
[[citiesRef queryOrderedByField:@"name" descending:YES] queryLimitedTo:3];
ViewController.m

Kotlin

citiesRef.orderBy("name", Query.Direction.DESCENDING).limit(3)
DocSnippets.kt

Java

citiesRef.orderBy("name", Direction.DESCENDING).limit(3);
DocSnippets.java

Dart

final citiesRef = db.collection("cities");
citiesRef.orderBy("name", descending: true).limit(3);
firestore.dart
Java
Query query = cities.orderBy("name", Direction.DESCENDING).limit(3);
QueryDataSnippets.java
Python
cities_ref = db.collection("cities")
query = cities_ref.order_by("name", direction=firestore.Query.DESCENDING).limit(3)
results = query.stream()
snippets.py

Python

cities_ref = db.collection("cities")
query = cities_ref.order_by("name", direction=firestore.Query.DESCENDING).limit(3)
results = query.stream()
snippets.py
C++
cities_ref.OrderBy("name", Query::Direction::kDescending).Limit(3);
snippets.cpp
Node.js
const lastThreeRes = await citiesRef.orderBy('name', 'desc').limit(3).get();
index.js
Go
query := cities.OrderBy("name", firestore.Desc).Limit(3)
query.go
PHP

PHP

For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries. 

$query = $citiesRef->orderBy('name', 'DESC')->limit(3);
query_order_desc_limit.php
Unity
Query query = citiesRef.OrderByDescending("Name").Limit(3);
C#
Query query = citiesRef.OrderByDescending("Name").Limit(3);
Program.cs
Ruby
query = cities_ref.order("name", "desc").limit(3)
order_limit_data.rb

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"));
order_multiple.js

Web

citiesRef.orderBy("state").orderBy("population", "desc");
test.firestore.js
Swift
Note: This product is not available on watchOS and App Clip targets. 
citiesRef
  .order(by: "state")
  .order(by: "population", descending: true)
ViewController.swift
Objective-C
Note: This product is not available on watchOS and App Clip targets. 
[[citiesRef queryOrderedByField:@"state"] queryOrderedByField:@"population" descending:YES];
ViewController.m

Kotlin

citiesRef.orderBy("state").orderBy("population", Query.Direction.DESCENDING)
DocSnippets.kt

Java

citiesRef.orderBy("state").orderBy("population", Direction.DESCENDING);
DocSnippets.java

Dart

final citiesRef = db.collection("cities");
citiesRef.orderBy("state").orderBy("population", descending: true);
firestore.dart
Java
Query query = cities.orderBy("state").orderBy("population", Direction.DESCENDING);
QueryDataSnippets.java
Python
cities_ref = db.collection("cities")
ordered_city_ref = cities_ref.order_by("state").order_by(
    "population", direction=firestore.Query.DESCENDING
)
snippets.py

Python

cities_ref = db.collection("cities")
cities_ref.order_by("state").order_by(
    "population", direction=firestore.Query.DESCENDING
)
snippets.py
C++
cities_ref.OrderBy("state").OrderBy("name", Query::Direction::kDescending);
snippets.cpp
Node.js
const byStateByPopRes = await citiesRef.orderBy('state').orderBy('population', 'desc').get();
index.js
Go
query := client.Collection("cities").OrderBy("state", firestore.Asc).OrderBy("population", firestore.Desc)
query.go
PHP

PHP

For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries. 

$query = $citiesRef->orderBy('state')->orderBy('population', 'DESC');
query_order_multi.php
Unity
Query query = citiesRef.OrderBy("State").OrderByDescending("Population");
C#
Query query = citiesRef.OrderBy("State").OrderByDescending("Population");
Program.cs
Ruby
query = cities_ref.order("state").order("population", "desc")
order_limit_data.rb

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));
filter_and_order.js

Web

citiesRef.where("population", ">", 100000).orderBy("population").limit(2);
test.firestore.js
Swift
Note: This product is not available on watchOS and App Clip targets. 
citiesRef
  .whereField("population", isGreaterThan: 100000)
  .order(by: "population")
  .limit(to: 2)
ViewController.swift
Objective-C
Note: This product is not available on watchOS and App Clip targets. 
[[[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"]
    queryLimitedTo:2];
ViewController.m

Kotlin

citiesRef.whereGreaterThan("population", 100000).orderBy("population").limit(2)
DocSnippets.kt

Java

citiesRef.whereGreaterThan("population", 100000).orderBy("population").limit(2);
DocSnippets.java

Dart

final citiesRef = db.collection("cities");
citiesRef
    .where("population", isGreaterThan: 100000)
    .orderBy("population")
    .limit(2);
firestore.dart
Java
Query query = cities.whereGreaterThan("population", 2500000L).orderBy("population").limit(2);
QueryDataSnippets.java
Python
cities_ref = db.collection("cities")
query = (
    cities_ref.where(filter=FieldFilter("population", ">", 2500000))
    .order_by("population")
    .limit(2)
)
results = query.stream()
snippets.py

Python

cities_ref = db.collection("cities")
query = (
    cities_ref.where(filter=FieldFilter("population", ">", 2500000))
    .order_by("population")
    .limit(2)
)
results = query.stream()
snippets.py
C++
cities_ref.WhereGreaterThan("population", FieldValue::Integer(100000))
    .OrderBy("population")
    .Limit(2);
snippets.cpp
Node.js
const biggestRes = await citiesRef.where('population', '>', 2500000)
  .orderBy('population').limit(2).get();
index.js
Go
query := cities.Where("population", ">", 2500000).OrderBy("population", firestore.Desc).Limit(2)
query.go
PHP

PHP

For more on installing and creating a Cloud Firestore client, refer to Cloud Firestore Client Libraries. 

$query = $citiesRef
    ->where('population', '>', 2500000)
    ->orderBy('population')
    ->limit(2);
query_order_limit_field_valid.php
Unity
Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Population")
    .Limit(2);
C#
Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Population")
    .Limit(2);
Program.cs
Ruby
query = cities_ref.where("population", ">", 2_500_000).order("population").limit(2)
order_limit_data.rb

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:

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”);