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

For example, you could query for the first 3 cities alphabetically with:

Web

citiesRef.orderBy("name").limit(3);test.firestore.js

Swift

citiesRef.order(by: "name").limit(to: 3)ViewController.swift

Objective-C

[[citiesRef queryOrderedByField:@"name"] queryLimitedTo:3];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.orderBy("name").limit(3);
Query query = cities.orderBy("name").limitToLast(3);QueryDataSnippets.java

Python

db.collection(u'cities').order_by(u'name').limit(3).stream()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.go

PHP

$query = $citiesRef->orderBy('name')->limit(3);order_by_name_limit_query.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

citiesRef.orderBy("name", "desc").limit(3);test.firestore.js

Swift

citiesRef.order(by: "name", descending: true).limit(to: 3)ViewController.swift

Objective-C

[[citiesRef queryOrderedByField:@"name" descending:YES] queryLimitedTo:3];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.orderBy("name", Direction.DESCENDING).limit(3);QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
query = cities_ref.order_by(
    u'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

$query = $citiesRef->orderBy('name', 'DESC')->limit(3);order_by_name_desc_limit_query.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

citiesRef.orderBy("state").orderBy("population", "desc");test.firestore.js

Swift

citiesRef
    .order(by: "state")
    .order(by: "population", descending: true)ViewController.swift

Objective-C

[[citiesRef queryOrderedByField:@"state"] queryOrderedByField:@"population" descending:YES];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.orderBy("state").orderBy("population", Direction.DESCENDING);QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
cities_ref.order_by(u'state').order_by(
    u'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

$query = $citiesRef->orderBy('state')->orderBy('population', 'DESC');order_by_state_and_population_query.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

citiesRef.where("population", ">", 100000).orderBy("population").limit(2);test.firestore.js

Swift

citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "population")
    .limit(to: 2)ViewController.swift

Objective-C

[[[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"]
    queryLimitedTo:2];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.whereGreaterThan("population", 2500000L).orderBy("population").limit(2);QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
query = cities_ref.where(
    u'population', u'>', 2500000).order_by(u'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

$query = $citiesRef
    ->where('population', '>', 2500000)
    ->orderBy('population')
    ->limit(2);where_order_by_limit_query.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 restrictions 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.

If you include a filter with a range comparison (<, <=, >, >=), your first ordering must be on the same field:

Valid: Range filter and orderBy on the same field

Web

citiesRef.where("population", ">", 100000).orderBy("population");test.firestore.js

Swift

citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "population")ViewController.swift

Objective-C

[[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.whereGreaterThan("population", 2500000L).orderBy("population");QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
query = cities_ref.where(
    u'population', u'>', 2500000).order_by(u'population')
results = query.stream()snippets.py

Node.js

citiesRef.where('population', '>', 2500000).orderBy('population');index.js

Go

query := cities.Where("population", ">", 2500000).OrderBy("population", firestore.Asc)query.go

PHP

$query = $citiesRef
    ->where('population', '>', 2500000)
    ->orderBy('population');range_order_by_query.php

Unity

Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Population");

C#

Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Population");Program.cs

Ruby

query = cities_ref.where("population", ">", 2_500_000).order("population")order_limit_data.rb

Invalid: Range filter and first orderBy on different fields

Web

citiesRef.where("population", ">", 100000).orderBy("country");test.firestore.js

Swift

citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "country")ViewController.swift

Objective-C

[[citiesRef queryWhereField:@"population" isGreaterThan:@100000] queryOrderedByField:@"country"];ViewController.m

Java

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

Kotlin+KTX

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

Java

Query query = cities.whereGreaterThan("population", 2500000L).orderBy("country");QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
query = cities_ref.where(u'population', u'>', 2500000).order_by(u'country')
results = query.stream()snippets.py

C++

// BAD EXAMPLE -- will crash the program:
cities_ref.WhereGreaterThan("population", FieldValue::Integer(100000))
    .OrderBy("country");snippets.cpp

Node.js

citiesRef.where('population', '>', 2500000).orderBy('country');index.js

Go

// Note: This is an invalid query. It violates the constraint that range
// and order by are required to be on the same field.
query := cities.Where("population", ">", 2500000).OrderBy("country", firestore.Asc)query.go

PHP

$invalidRangeQuery = $citiesRef
    ->where('population', '>', 2500000)
    ->orderBy('country');invalid_range_order_by_query.php

Unity

Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Country");

C#

Query query = citiesRef
    .WhereGreaterThan("Population", 2500000)
    .OrderBy("Country");Program.cs

Ruby

query = cities_ref.where("population", ">", 2_500_000).order("country")order_limit_data.rb

You cannot order your query by any field included in an equality (=) or in clause.