Save the date for Firebase Demo Day 2024. Learn how to build and run modern, AI-powered apps users love. Learn more.

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+KTX

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

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+KTX

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

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+KTX

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

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+KTX

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

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:

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 with Cloud Firestore

Order and limit data

Web

Web

Swift

Objective-C

Kotlin+KTX

Java

Dart

Java

Python

Python

C++

Node.js

Go

PHP

PHP

Unity

C#

Ruby

Web

Web

Swift

Objective-C

Kotlin+KTX

Java

Dart

Java

Python

Python

C++

Node.js

Go

PHP

PHP

Unity

C#

Ruby

Web

Web

Swift

Objective-C

Kotlin+KTX

Java

Dart

Java

Python

Python

C++

Node.js

Go

PHP

PHP

Unity

C#

Ruby

Web

Web

Swift

Objective-C

Kotlin+KTX

Java

Dart

Java

Python

Python

C++

Node.js

Go

PHP

PHP

Unity

C#

Ruby

Limitations

orderBy and existence

Java

Java

Java

`orderBy` and existence