Ordenar e limitar dados com o Cloud Firestore

O Cloud Firestore oferece uma poderosa funcionalidade de consulta para especificar quais documentos você quer recuperar em uma coleção. Essas consultas também podem ser usadas com get() ou addSnapshotListener(), conforme descrito em Receber dados.

Ordenar e limitar dados

Por padrão, uma consulta recupera todos os documentos que atendem a ela em ordem crescente por ID. Use orderBy() para especificar a ordem de classificação dos dados e limit() para limitar o número de documentos recuperados. Se você especificar um limit(), o valor precisará ser maior ou igual a zero.

Por exemplo, para consultar as três primeiras cidades em ordem alfabética, use:

API modular da Web

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

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

API com namespace da Web

citiesRef.orderBy("name").limit(3);
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
citiesRef.order(by: "name").limit(to: 3)
Objective-C
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
[[citiesRef queryOrderedByField:@"name"] queryLimitedTo:3];

Kotlin+KTX

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

Java

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

Dart

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

Python

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

PHP

Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

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

Para ver as três últimas cidades, classifique em ordem decrescente:

API modular da Web

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

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

API com namespace da Web

citiesRef.orderBy("name", "desc").limit(3);
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
citiesRef.order(by: "name", descending: true).limit(to: 3)
Objective-C
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
[[citiesRef queryOrderedByField:@"name" descending:YES] queryLimitedTo:3];

Kotlin+KTX

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
Query query = cities.orderBy("name", Direction.DESCENDING).limit(3);
Python
cities_ref = db.collection("cities")
query = cities_ref.order_by("name", direction=firestore.Query.DESCENDING).limit(3)
results = query.stream()

Python

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

PHP

Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

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

Além disso, também é possível ordenar por vários campos. Por exemplo, se você quiser ordenar por estado e, dentro de cada estado ordenar por população em ordem decrescente:

API modular da Web

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

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

API com namespace da Web

citiesRef.orderBy("state").orderBy("population", "desc");
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
citiesRef
  .order(by: "state")
  .order(by: "population", descending: true)
Objective-C
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
[[citiesRef queryOrderedByField:@"state"] queryOrderedByField:@"population" descending:YES];

Kotlin+KTX

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
Query query = cities.orderBy("state").orderBy("population", Direction.DESCENDING);
Python
cities_ref = db.collection("cities")
cities_ref.order_by("state").order_by(
    "population", direction=firestore.Query.DESCENDING
)

Python

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

PHP

Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

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

É possível combinar filtros where() com orderBy() e limit(). No exemplo a seguir, as consultas definem um limite para população, ordenam por esse valor em ordem crescente e retornam apenas os primeiros resultados que excedem o limite:

API modular da Web

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

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

API com namespace da Web

citiesRef.where("population", ">", 100000).orderBy("population").limit(2);
Swift
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
citiesRef
  .whereField("population", isGreaterThan: 100000)
  .order(by: "population")
  .limit(to: 2)
Objective-C
Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
[[[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"]
    queryLimitedTo:2];

Kotlin+KTX

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
Query query = cities.whereGreaterThan("population", 2500000L).orderBy("population").limit(2);
Python
cities_ref = db.collection("cities")
query = (
    cities_ref.where(filter=FieldFilter("population", ">", 2500000))
    .order_by("population")
    .limit(2)
)
results = query.stream()

Python

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

PHP

Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

$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);
Ruby
query = cities_ref.where("population", ">", 2_500_000).order("population").limit(2)

No entanto, se você tiver um filtro com uma comparação de intervalos (<, <=, >, >=), sua primeira classificação precisará estar no mesmo campo. Consulte a lista de limitações de orderBy() abaixo.

Limitações

Observe as seguintes restrições para cláusulas orderBy():

  • Uma cláusula orderBy() também filtra a existência dos campos fornecidos. O conjunto de resultados não incluirá documentos que não contenham os campos fornecidos.
  • Se você incluir um filtro com uma comparação de intervalos (<, <=, >, >=), sua primeira classificação precisará estar no mesmo campo:

    Válido: filtro de intervalo e orderBy no mesmo campo

    API modular da Web

    import { query, where, orderBy } from "firebase/firestore";  
    
    const q = query(citiesRef, where("population", ">", 100000), orderBy("population"));

    API com namespace da Web

    citiesRef.where("population", ">", 100000).orderBy("population");
    Swift
    Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
    citiesRef
      .whereField("population", isGreaterThan: 100000)
      .order(by: "population")
    Objective-C
    Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
    [[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
        queryOrderedByField:@"population"];

    Kotlin+KTX

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

    Java

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

    Dart

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

    Python

    cities_ref = db.collection("cities")
    query = cities_ref.where(filter=FieldFilter("population", ">", 2500000)).order_by(
        "population"
    )
    results = query.stream()
    Node.js
    citiesRef.where('population', '>', 2500000).orderBy('population');
    Go
    query := cities.Where("population", ">", 2500000).OrderBy("population", firestore.Asc)
    PHP

    PHP

    Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

    $query = $citiesRef
        ->where('population', '>', 2500000)
        ->orderBy('population');
    Unity
    Query query = citiesRef
        .WhereGreaterThan("Population", 2500000)
        .OrderBy("Population");
    C#
    Query query = citiesRef
        .WhereGreaterThan("Population", 2500000)
        .OrderBy("Population");
    Ruby
    query = cities_ref.where("population", ">", 2_500_000).order("population")

    Inválido: filtro de intervalo e primeiro orderBy em campos diferentes

    API modular da Web

    import { query, where, orderBy } from "firebase/firestore";  
    
    const q = query(citiesRef, where("population", ">", 100000), orderBy("country"));

    API com namespace da Web

    citiesRef.where("population", ">", 100000).orderBy("country");
    Swift
    Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
    citiesRef
      .whereField("population", isGreaterThan: 100000)
      .order(by: "country")
    Objective-C
    Observação: esse produto não está disponível para destinos watchOS e de clipes de apps.
    [[citiesRef queryWhereField:@"population" isGreaterThan:@100000] queryOrderedByField:@"country"];

    Kotlin+KTX

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

    Java

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

    Dart

    final citiesRef = db.collection("cities");
    citiesRef.where("population", isGreaterThan: 100000).orderBy("country");
    Java
    Query query = cities.whereGreaterThan("population", 2500000L).orderBy("country");
    Python
    cities_ref = db.collection("cities")
    query = cities_ref.where(filter=FieldFilter("population", ">", 2500000)).order_by(
        "country"
    )
    results = query.stream()

    Python

    cities_ref = db.collection("cities")
    query = cities_ref.where(filter=FieldFilter("population", ">", 2500000)).order_by(
        "country"
    )
    results = query.stream()
    C++
    // BAD EXAMPLE -- will crash the program:
    cities_ref.WhereGreaterThan("population", FieldValue::Integer(100000))
        .OrderBy("country");
    Node.js
    citiesRef.where('population', '>', 2500000).orderBy('country');
    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)
    PHP

    PHP

    Para mais informações sobre como instalar e criar um cliente do Cloud Firestore, consulte Bibliotecas de cliente do Cloud Firestore.

    $invalidRangeQuery = $citiesRef
        ->where('population', '>', 2500000)
        ->orderBy('country');
    Unity
    Query query = citiesRef
        .WhereGreaterThan("Population", 2500000)
        .OrderBy("Country");
    C#
    Query query = citiesRef
        .WhereGreaterThan("Population", 2500000)
        .OrderBy("Country");
    Ruby
    query = cities_ref.where("population", ">", 2_500_000).order("country")

orderBy e existência

Quando você ordena uma consulta por um determinado campo, ela só pode retornar os documentos em que o campo de ordenação existe.

Por exemplo, a consulta a seguir não retornaria nenhum documento em que o campo population não estivesse definido, mesmo que atendesse aos filtros de consulta.

Java
db.collection("cities").whereEqualTo("country", “USA”).orderBy(“population”);

Um efeito relacionado se aplica a desigualdades. Uma consulta com um filtro de desigualdade em um campo também implica ordenação por esse campo. A consulta a seguir não retorna documentos sem um campo population, mesmo que country = USA nesse documento. Como solução alternativa, você pode executar consultas separadas para cada ordem ou atribuir um valor para todos os campos que ordena.

Java
db.collection(“cities”).where(or(“country”, USA”), greaterThan(“population”, 250000));

A consulta acima inclui uma ordenação implícita sobre a desigualdade e é equivalente ao seguinte:

Java
db.collection(“cities”).where(or(“country”, USA”), greaterThan(“population”, 250000)).orderBy(“population”);