Order and limit data

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 version 9

import { query, orderBy, limit } from "firebase/firestore";  

const q = query(citiesRef, orderBy("name"), limit(3));order_and_limit.js

Web version 8

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
Android

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

Java
Android

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
(Async)

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

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

$query = $citiesRef->orderBy('name')->limit(3);

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 version 9

import { query, orderBy, limit } from "firebase/firestore";  

const q = query(citiesRef, orderBy("name", "desc"), limit(3));order_and_limit_desc.js

Web version 8

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
Android

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

Java
Android

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
(Async)

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

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

$query = $citiesRef->orderBy('name', 'DESC')->limit(3);

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 version 9

import { query, orderBy } from "firebase/firestore";  

const q = query(citiesRef, orderBy("state"), orderBy("population", "desc"));order_multiple.js

Web version 8

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
Android

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

Java
Android

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
(Async)

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

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

$query = $citiesRef->orderBy('state')->orderBy('population', 'DESC');

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 version 9

import { query, where, orderBy, limit } from "firebase/firestore";  

const q = query(citiesRef, where("population", ">", 100000), orderBy("population"), limit(2));filter_and_order.js

Web version 8

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
Android

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

Java
Android

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
(Async)

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

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

$query = $citiesRef
    ->where('population', '>', 2500000)
    ->orderBy('population')
    ->limit(2);

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:

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

Order and limit data