Paginar dados com cursores de consulta

Com os cursores de consulta no Cloud Firestore, você pode dividir os dados retornados por uma consulta em lotes de acordo com os parâmetros definidos.

Os cursores de consulta definem os pontos inicial e final de uma consulta, permitindo que você:

retorne um subconjunto dos dados;
execute a paginação dos resultados da consulta.

No entanto, para definir um intervalo específico para uma consulta, use o método where() descrito em Consultas simples.

Adicionar um cursor simples a uma consulta

Use os métodos startAt() ou startAfter() para definir o ponto inicial de uma consulta. O método startAt() inclui o ponto de início, enquanto o método startAfter() o exclui.

Por exemplo, se você usar startAt(A) em uma consulta, ela retornará o alfabeto inteiro. Se você usar startAfter(A), ela retornará B-Z.

Web

citiesRef.orderBy("population").startAt(1000000)test.firestore.js

Swift

// Get all cities with population over one million, ordered by population.
db.collection("cities")
    .order(by: "population")
    .start(at: [1000000])ViewController.swift

Objective-C

// Get all cities with population over one million, ordered by population.
[[[db collectionWithPath:@"cities"]
    queryOrderedByField:@"population"]
    queryStartingAtValues:@[ @1000000 ]];ViewController.m

Android

// Get all cities with a population >= 1,000,000, ordered by population,
db.collection("cities")
        .orderBy("population")
        .startAt(1000000);DocSnippets.java

Java

Query query = cities.orderBy("population").startAt(4921000L);QueryDataSnippets.java

Python

// Python snippet missing

Node.js

var startAt = db.collection('cities')
    .orderBy('population')
    .startAt(1000000);index.js

Go

query := client.Collection("cities").OrderBy("population", firestore.Asc).StartAt(1000000)query.go

PHP

$query = $citiesRef
    ->orderBy('population')
    ->startAt([1000000]);start_at_field_query_cursor.php

Da mesma forma, use os métodos endAt() ou endBefore() para definir um ponto final para os resultados da consulta.

Web

citiesRef.orderBy("population").endAt(1000000)test.firestore.js

Swift

// Get all cities with population less than one million, ordered by population.
db.collection("cities")
    .order(by: "population")
    .end(at: [1000000])ViewController.swift

Objective-C

// Get all cities with population less than one million, ordered by population.
[[[db collectionWithPath:@"cities"]
    queryOrderedByField:@"population"]
    queryEndingAtValues:@[ @1000000 ]];ViewController.m

Android

// Get all cities with a population <= 1,000,000, ordered by population,
db.collection("cities")
        .orderBy("population")
        .endAt(1000000);DocSnippets.java

Java

Query query = cities.orderBy("population").endAt(4921000L);QueryDataSnippets.java

Python

cities_ref = db.collection(u'cities')
query_end_at = cities_ref.order_by(u'population').end_at({
    u'population': 1000000
})snippets.py

Node.js

var endAt = db.collection('cities')
    .orderBy('population')
    .endAt(1000000);index.js

Go

query := client.Collection("cities").OrderBy("population", firestore.Asc).EndAt(1000000)query.go

PHP

$query = $citiesRef
    ->orderBy('population')
    ->endAt([1000000]);end_at_field_query_cursor.php

Usar um instantâneo de documento para definir o cursor de consulta

Você também pode passar um instantâneo de documento para a cláusula do cursor como o ponto inicial ou final do cursor de consulta. Os valores no instantâneo do documento servem como valores no cursor de consulta.

Por exemplo, tire um instantâneo de um documento "San Francisco" no seu conjunto de dados de cidades e populações. Em seguida, use esse instantâneo de documento como o ponto inicial para seu cursor de consulta de população. Sua consulta retornará todas as cidades com uma população maior ou igual a de San Francisco, conforme definido no instantâneo do documento.

Web

var citiesRef = db.collection("cities");

return citiesRef.doc("SF").get().then(function(doc) {
    // Get all cities with a population bigger than San Francisco
    var biggerThanSf = citiesRef
        .orderBy("population")
        .startAt(doc);

    // ...
});test.firestore.js

Swift

db.collection("cities")
    .document("SF")
    .addSnapshotListener { (document, error) in
        guard let document = document else {
            print("Error retreving cities: \(error.debugDescription)")
            return
        }

        // Get all cities with a population greater than or equal to San Francisco.
        let sfSizeOrBigger = db.collection("cities")
            .order(by: "population")
            .start(atDocument: document)
}ViewController.swift

Objective-C

[[[db collectionWithPath:@"cities"] documentWithPath:@"SF"]
    addSnapshotListener:^(FIRDocumentSnapshot *snapshot, NSError *error) {
      if (snapshot == nil) {
        NSLog(@"Error retreiving cities: %@", error);
        return;
      }
      // Get all cities with a population greater than or equal to San Francisco.
      FIRQuery *sfSizeOrBigger = [[[db collectionWithPath:@"cities"]
          queryOrderedByField:@"population"]
          queryStartingAtDocument:snapshot];
    }];ViewController.m

Android

// Get the data for "San Francisco"
db.collection("cities").document("SF")
        .get()
        .addOnSuccessListener(new OnSuccessListener<DocumentSnapshot>() {
            @Override
            public void onSuccess(DocumentSnapshot documentSnapshot) {
                // Get all cities with a population bigger than San Francisco.
                Query biggerThanSf = db.collection("cities")
                        .orderBy("population")
                        .startAt(documentSnapshot);

                // ...
            }
        });DocSnippets.java

Java

// Not supported in Java SDK

Python

# Not supported in Python SDK

Node.js

// Not supported in Node.js SDK

Go

// Not supported in Go SDK

PHP

// Not supported in PHP SDK

Paginar uma consulta

Para paginar as consultas, combine cursores de consulta com o método limit(). Por exemplo, use o último documento em um lote como o início de um cursor para o próximo lote.

Web

var first = db.collection("cities")
        .orderBy("population")
        .limit(25);

return first.get().then(function (documentSnapshots) {
  // Get the last visible document
  var lastVisible = documentSnapshots.docs[documentSnapshots.docs.length-1];
  console.log("last", lastVisible);

  // Construct a new query starting at this document,
  // get the next 25 cities.
  var next = db.collection("cities")
          .orderBy("population")
          .startAfter(lastVisible)
          .limit(25);
});test.firestore.js

Swift

// Construct query for first 25 cities, ordered by population
let first = db.collection("cities")
    .order(by: "population")
    .limit(to: 25)

first.addSnapshotListener { (snapshot, error) in
    guard let snapshot = snapshot else {
        print("Error retreving cities: \(error.debugDescription)")
        return
    }

    guard let lastSnapshot = snapshot.documents.last else {
        // The collection is empty.
        return
    }

    // Construct a new query starting after this document,
    // retrieving the next 25 cities.
    let next = db.collection("cities")
        .order(by: "population")
        .start(afterDocument: lastSnapshot)

    // Use the query for pagination.
    // ...
}ViewController.swift

Objective-C

FIRQuery *first = [[[db collectionWithPath:@"cities"]
    queryOrderedByField:@"population"]
    queryLimitedTo:25];
[first addSnapshotListener:^(FIRQuerySnapshot *snapshot, NSError *error) {
  if (snapshot == nil) {
    NSLog(@"Error retreiving cities: %@", error);
    return;
  }
  if (snapshot.documents.count == 0) { return; }
  FIRDocumentSnapshot *lastSnapshot = snapshot.documents.lastObject;

  // Construct a new query starting after this document,
  // retreiving the next 25 cities.
  FIRQuery *next = [[[db collectionWithPath:@"cities"]
      queryOrderedByField:@"population"]
      queryStartingAfterDocument:lastSnapshot];
  // Use the query for pagination.
  // ...
}];ViewController.m

Android

// Construct query for first 25 cities, ordered by population
Query first = db.collection("cities")
        .orderBy("population")
        .limit(25);

first.get()
    .addOnSuccessListener(new OnSuccessListener<QuerySnapshot>() {
        @Override
        public void onSuccess(QuerySnapshot documentSnapshots) {
            // ...

            // Get the last visible document
            DocumentSnapshot lastVisible = documentSnapshots.getDocuments()
                    .get(documentSnapshots.size() -1);

            // Construct a new query starting at this document,
            // get the next 25 cities.
            Query next = db.collection("cities")
                    .orderBy("population")
                    .startAfter(lastVisible)
                    .limit(25);

            // Use the query for pagination
            // ...
        }
    });DocSnippets.java

Java

// Not supported in Java SDK

Python

cities_ref = db.collection(u'cities')
first_query = cities_ref.order_by(u'population').limit(3)

# Get the last document from the results
docs = first_query.get()
last_doc = list(docs)[-1]

# Construct a new query starting at this document
# Note: this will not have the desired effect if
# multiple cities have the exact same population value
last_pop = last_doc.to_dict()[u'population']

next_query = (
    cities_ref
    .order_by(u'population')
    .start_after({
        u'population': last_pop
    })
    .limit(3)
)
# Use the query for pagination
# ...snippets.py

Node.js

var first = db.collection('cities')
    .orderBy('population')
    .limit(3);

var paginate = first.get()
    .then((snapshot) => {
      // ...

      // Get the last document
      var last = snapshot.docs[snapshot.docs.length - 1];

      // Construct a new query starting at this document.
      // Note: this will not have the desired effect if multiple
      // cities have the exact same population value.
      var next = db.collection('cities')
          .orderBy('population')
          .startAfter(last.data().population)
          .limit(3);

      // Use the query for pagination
      // ...
    });index.js

Go

cities := client.Collection("cities")

// Get the first 25 cities, ordered by population.
firstPage := cities.OrderBy("population", firestore.Asc).Limit(25).Documents(ctx)
docs, err := firstPage.GetAll()
if err != nil {
	return err
}

// Get the last document.
lastDoc := docs[len(docs)-1]

// Construct a new query to get the next 25 cities.
secondPage := cities.OrderBy("population", firestore.Asc).
	StartAfter(lastDoc.Data()["population"]).
	Limit(25)

// ...query.go

PHP

$citiesRef = $db->collection('cities');
$firstQuery = $citiesRef->orderBy('population')->limit(3);

# Get the last document from the results
$documents = $firstQuery->documents();
$lastPopulation = 0;
foreach ($documents as $document) {
    $lastPopulation = $document['population'];
}

# Construct a new query starting at this document
# Note: this will not have the desired effect if multiple cities have the exact same population value
$nextQuery = $citiesRef->orderBy('population')->startAfter([$lastPopulation]);
$snapshot = $nextQuery->documents();paginated_query_cursor.php

Definir várias condições de cursor

Para adicionar mais granularidade ao ponto inicial ou final do cursor, você pode especificar várias condições na cláusula do cursor. Isso é particularmente útil se o seu conjunto de dados incluir campos onde a primeira condição em uma cláusula de cursor retornaria vários resultados. Use várias condições para especificar melhor o ponto inicial ou final e reduzir a ambiguidade.

Por exemplo, em um conjunto de dados contendo todas as cidades chamadas "Springfield" nos Estados Unidos, haveria vários pontos de partida para um conjunto de consultas iniciado em "Springfield":

Cidades
Nome	Estado
Springfield	Massachusetts
Springfield	Missouri
Springfield	Wisconsin

Para começar em uma Springfield específica, você pode adicionar o estado como uma condição secundária na sua cláusula de cursor.

Web

// Will return all Springfields
db.collection("cities")
   .orderBy("name")
   .orderBy("state")
   .startAt("Springfield")

// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
db.collection("cities")
   .orderBy("name")
   .orderBy("state")
   .startAt("Springfield", "Missouri")test.firestore.js

Swift

// Will return all Springfields
db.collection("cities")
    .order(by: "name")
    .order(by: "state")
    .start(at: ["Springfield"])

// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
db.collection("cities")
    .order(by: "name")
    .order(by: "state")
    .start(at: ["Springfield", "Missouri"])ViewController.swift

Objective-C

// Will return all Springfields
[[[[db collectionWithPath:@"cities"]
    queryOrderedByField:@"name"]
    queryOrderedByField:@"state"]
    queryStartingAtValues:@[ @"Springfield" ]];
// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
[[[[db collectionWithPath:@"cities"]
   queryOrderedByField:@"name"]
   queryOrderedByField:@"state"]
   queryStartingAtValues:@[ @"Springfield", @"Missouri" ]];ViewController.m

Android

// Will return all Springfields
db.collection("cities")
        .orderBy("name")
        .orderBy("state")
        .startAt("Springfield");

// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
db.collection("cities")
        .orderBy("name")
        .orderBy("state")
        .startAt("Springfield", "Missouri");DocSnippets.java

Java

// Will return all Springfields
Query query1 = db.collection("cities")
    .orderBy("name")
    .orderBy("state")
    .startAt("Springfield");

// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
Query query2 = db.collection("cities")
    .orderBy("name")
    .orderBy("state")
    .startAt("Springfield", "Missouri");QueryDataSnippets.java

Python

start_at_name = (
    db.collection(u'cities')
    .order_by(u'name')
    .order_by(u'state')
    .start_at({
        u'name': u'Springfield'
    })
)

start_at_name_and_state = (
    db.collection(u'cities')
    .order_by(u'name')
    .order_by(u'state')
    .start_at({
        u'name': u'Springfield',
        u'state': u'Missouri'
    })
)snippets.py

Node.js

// Will return all Springfields
var startAtName = db.collection('cities')
    .orderBy('name')
    .orderBy('state')
    .startAt('Springfield');index.js
// Will return 'Springfield, Missouri' and 'Springfield, Wisconsin'
var startAtNameAndState = db.collection('cities')
    .orderBy('name')
    .orderBy('state')
    .startAt('Springfield', 'Missouri');index.js

Go

// Will return all Springfields.
client.Collection("cities").
	OrderBy("name", firestore.Asc).
	OrderBy("state", firestore.Asc).
	StartAt("Springfield")

// Will return Springfields where state comes after Wisconsin.
client.Collection("cities").
	OrderBy("name", firestore.Asc).
	OrderBy("state", firestore.Asc).
	StartAt("Springfield", "Wisconsin")query.go

PHP

// Will return all Springfields
$query1 = $db
    ->collection('cities')
    ->orderBy('name')
    ->orderBy('state')
    ->startAt(['Springfield']);

// Will return "Springfield, Missouri" and "Springfield, Wisconsin"
$query2 = $db
    ->collection('cities')
    ->orderBy('name')
    ->orderBy('state')
    ->startAt(['Springfield', 'Missouri']);multiple_cursor_conditions.php