Como solicitar e limitar dados

O 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 à consulta em ordem crescente por ID do documento. É possível especificar a ordem de classificação dos dados usando orderBy() e limitar o número de documentos recuperados usando limit().

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

Versão 9 para a Web

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

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

Versão 8 para a Web

citiesRef.orderBy("name").limit(3);
test.firestore.js
Swift
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
citiesRef.order(by: "name").limit(to: 3)
ViewController.swift
Objective-C
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
[[citiesRef queryOrderedByField:@"name"] queryLimitedTo:3];
ViewController.m
Java
Android
citiesRef.orderBy("name").limit(3);
DocSnippets.java
Kotlin+KTX
Android
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
cities_ref = db.collection("cities")
query = cities_ref.order_by("name").limit_to_last(2)
results = query.get()
snippets.py
Python
(assíncrono)
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
$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

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

Versão 9 para a Web

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

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

Versão 8 para a Web

citiesRef.orderBy("name", "desc").limit(3);
test.firestore.js
Swift
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
citiesRef.order(by: "name", descending: true).limit(to: 3)
ViewController.swift
Objective-C
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
[[citiesRef queryOrderedByField:@"name" descending:YES] queryLimitedTo:3];
ViewController.m
Java
Android
citiesRef.orderBy("name", Direction.DESCENDING).limit(3);
DocSnippets.java
Kotlin+KTX
Android
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
Python
(assíncrono)
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
$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

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:

Versão 9 para a Web

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

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

Versão 8 para a Web

citiesRef.orderBy("state").orderBy("population", "desc");
test.firestore.js
Swift
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
citiesRef
    .order(by: "state")
    .order(by: "population", descending: true)
ViewController.swift
Objective-C
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
[[citiesRef queryOrderedByField:@"state"] queryOrderedByField:@"population" descending:YES];
ViewController.m
Java
Android
citiesRef.orderBy("state").orderBy("population", Direction.DESCENDING);
DocSnippets.java
Kotlin+KTX
Android
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
Python
(assíncrono)
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
$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

É 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:

Versão 9 para a Web

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

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

Versão 8 para a Web

citiesRef.where("population", ">", 100000).orderBy("population").limit(2);
test.firestore.js
Swift
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "population")
    .limit(to: 2)
ViewController.swift
Objective-C
Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
[[[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"]
    queryLimitedTo:2];
ViewController.m
Java
Android
citiesRef.whereGreaterThan("population", 100000).orderBy("population").limit(2);
DocSnippets.java
Kotlin+KTX
Android
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
Python
(assíncrono)
cities_ref = db.collection("cities")
query = cities_ref.where("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
$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

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 orderBy() limitações 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

    Versão 9 para a Web

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

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

    Versão 8 para a Web

    citiesRef.where("population", ">", 100000).orderBy("population");
    test.firestore.js
    Swift
    Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
    citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "population")
    ViewController.swift
    Objective-C
    Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
    [[citiesRef queryWhereField:@"population" isGreaterThan:@100000]
    queryOrderedByField:@"population"];
    ViewController.m
    Java
    Android
    citiesRef.whereGreaterThan("population", 100000).orderBy("population");
    DocSnippets.java
    Kotlin+KTX
    Android
    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
    Python
    (assíncrono)
    cities_ref = db.collection("cities")
query = cities_ref.where("population", ">", 2500000).order_by("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');
    query_order_with_filter.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

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

    Versão 9 para a Web

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

const q = query(citiesRef, where("population", ">", 100000), orderBy("country"));
    invalid_filter_and_order.js

    Versão 8 para a Web

    citiesRef.where("population", ">", 100000).orderBy("country");
    test.firestore.js
    Swift
    Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
    citiesRef
    .whereField("population", isGreaterThan: 100000)
    .order(by: "country")
    ViewController.swift
    Objective-C
    Observação: este produto não está disponível para watchOS e destinos de clipes de apps. 
    [[citiesRef queryWhereField:@"population" isGreaterThan:@100000] queryOrderedByField:@"country"];
    ViewController.m
    Java
    Android
    citiesRef.whereGreaterThan("population", 100000).orderBy("country");
    DocSnippets.java
    Kotlin+KTX
    Android
    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
    Python
    (assíncrono)
    cities_ref = db.collection("cities")
query = cities_ref.where("population", ">", 2500000).order_by("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');
    query_order_field_invalid.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
  • Não é possível realizar sua consulta por qualquer campo incluído em uma cláusula de igualdade (=) ou in.