Como executar consultas simples e compostas no Cloud Firestore

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

Dados de exemplo

Para começar, escreva alguns dados sobre cidades para demonstrarmos diversas formas de leitura:

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

citiesRef.doc("SF").set({
    name: "San Francisco", state: "CA", country: "USA",
    capital: false, population: 860000 });
citiesRef.doc("LA").set({
    name: "Los Angeles", state: "CA", country: "USA",
    capital: false, population: 3900000 });
citiesRef.doc("DC").set({
    name: "Washington, D.C.", state: null, country: "USA",
    capital: true, population: 680000 });
citiesRef.doc("TOK").set({
    name: "Tokyo", state: null, country: "Japan",
    capital: true, population: 9000000 });
citiesRef.doc("BJ").set({
    name: "Beijing", state: null, country: "China",
    capital: true, population: 21500000 });
test.firestore.js

let citiesRef = db.collection("cities")

citiesRef.document("SF").setData([
    "name": "San Francisco",
    "state": "CA",
    "country": "USA",
    "capital": false,
    "population": 860000
    ])
citiesRef.document("LA").setData([
    "name": "Los Angeles",
    "state": "CA",
    "country": "USA",
    "capital": false,
    "population": 3900000
    ])
citiesRef.document("DC").setData([
    "name": "Washington D.C.",
    "country": "USA",
    "capital": true,
    "population": 680000
    ])
citiesRef.document("TOK").setData([
    "name": "Tokyo",
    "country": "Japan",
    "capital": true,
    "population": 9000000
    ])
citiesRef.document("BJ").setData([
    "name": "Beijing",
    "country": "China",
    "capital": true,
    "population": 21500000
    ])
ViewController.swift

FIRCollectionReference *citiesRef = [self.db collectionWithPath:@"cities"];
[[citiesRef documentWithPath:@"SF"] setData:@{
  @"name": @"San Francisco",
  @"state": @"CA",
  @"country": @"USA",
  @"capital": @(NO),
  @"population": @860000
}];
[[citiesRef documentWithPath:@"LA"] setData:@{
  @"name": @"Los Angeles",
  @"state": @"CA",
  @"country": @"USA",
  @"capital": @(NO),
  @"population": @3900000
}];
[[citiesRef documentWithPath:@"DC"] setData:@{
  @"name": @"Washington D.C.",
  @"country": @"USA",
  @"capital": @(YES),
  @"population": @680000
}];
[[citiesRef documentWithPath:@"TOK"] setData:@{
  @"name": @"Tokyo",
  @"country": @"Japan",
  @"capital": @(YES),
  @"population": @9000000
}];
[[citiesRef documentWithPath:@"BJ"] setData:@{
  @"name": @"Beijing",
  @"country": @"China",
  @"capital": @(YES),
  @"population": @21500000
}];
ViewController.m
  

CollectionReference cities = db.collection("cities");

Map<String, Object> data1 = new HashMap<>();
data1.put("name", "San Francisco");
data1.put("state", "CA");
data1.put("country", "USA");
data1.put("capital", false);
data1.put("population", 860000);
cities.document("SF").set(data1);

Map<String, Object> data2 = new HashMap<>();
data2.put("name", "Los Angeles");
data2.put("state", "CA");
data2.put("country", "USA");
data2.put("capital", false);
data2.put("population", 3900000);
cities.document("LA").set(data2);

Map<String, Object> data3 = new HashMap<>();
data3.put("name", "Washington D.C.");
data3.put("state", null);
data3.put("country", "USA");
data3.put("capital", true);
data3.put("population", 680000);
cities.document("DC").set(data3);

Map<String, Object> data4 = new HashMap<>();
data4.put("name", "Tokyo");
data4.put("state", null);
data4.put("country", "Japan");
data4.put("capital", true);
data4.put("population", 9000000);
cities.document("TOK").set(data4);

Map<String, Object> data5 = new HashMap<>();
data5.put("name", "Beijing");
data5.put("state", null);
data5.put("country", "China");
data5.put("capital", true);
data5.put("population", 21500000);
cities.document("BJ").set(data5);
DocSnippets.java

CollectionReference cities = db.collection("cities");
List<ApiFuture<WriteResult>> futures = new ArrayList<>();
futures.add(cities.document("SF").set(new City("San Francisco", "CA", "USA", false, 860000L)));
futures.add(cities.document("LA").set(new City("Los Angeles", "CA", "USA", false, 3900000L)));
futures.add(cities.document("DC").set(new City("Washington D.C.", null, "USA", true, 680000L)));
futures.add(cities.document("TOK").set(new City("Tokyo", null, "Japan", true, 9000000L)));
futures.add(cities.document("BJ").set(new City("Beijing", null, "China", true, 21500000L)));
// (optional) block on documents successfully added
ApiFutures.allAsList(futures).get();
QueryDataSnippets.java

class City(object):
    def __init__(self, name, state, country, capital=False, population=0):
        self.name = name
        self.state = state
        self.country = country
        self.capital = capital
        self.population = population

    @staticmethod
    def from_dict(source):
        # ...

    def to_dict(self):
        # ...

    def __repr__(self):
        return u'City(name={}, country={}, population={}, capital={})'.format(
            self.name, self.country, self.population, self.capital)
cities_ref = db.collection(u'cities')
cities_ref.document(u'SF').set(
    City(u'San Francisco', u'CA', u'USA', False, 860000).to_dict())
cities_ref.document(u'LA').set(
    City(u'Los Angeles', u'CA', u'USA', False, 3900000).to_dict())
cities_ref.document(u'DC').set(
    City(u'Washington D.C.', None, u'USA', True, 680000).to_dict())
cities_ref.document(u'TOK').set(
    City(u'Tokyo', None, u'Japan', True, 9000000).to_dict())
cities_ref.document(u'BJ').set(
    City(u'Beijing', None, u'China', True, 21500000).to_dict())
snippets.py

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

var setSf = citiesRef.doc('SF').set({
    name: 'San Francisco', state: 'CA', country: 'USA',
    capital: false, population: 860000 });
var setLa = citiesRef.doc('LA').set({
    name: 'Los Angeles', state: 'CA', country: 'USA',
    capital: false, population: 3900000 });
var setDc = citiesRef.doc('DC').set({
    name: 'Washington, D.C.', state: null, country: 'USA',
    capital: true, population: 680000 });
var setTok = citiesRef.doc('TOK').set({
    name: 'Tokyo', state: null, country: 'Japan',
    capital: true, population: 9000000 });
var setBj = citiesRef.doc('BJ').set({
    name: 'Beijing', state: null, country: 'China',
    capital: true, population: 21500000 });
index.js

cities := []struct {
	id string
	c  City
}{
	{id: "SF", c: City{Name: "San Francisco", State: "CA", Country: "USA", Capital: false, Population: 860000}},
	{id: "LA", c: City{Name: "Los Angeles", State: "CA", Country: "USA", Capital: false, Population: 3900000}},
	{id: "DC", c: City{Name: "Washington D.C.", Country: "USA", Capital: false, Population: 680000}},
	{id: "TOK", c: City{Name: "Tokyo", Country: "Japan", Capital: true, Population: 9000000}},
	{id: "BJ", c: City{Name: "Beijing", Country: "China", Capital: true, Population: 21500000}},
}
for _, c := range cities {
	if _, err := client.Collection("cities").Doc(c.id).Set(ctx, c.c); err != nil {
		return err
	}
}
query.go

$citiesRef = $db->collection('cities');
$citiesRef->document('SF')->set([
    'name' => 'San Francisco',
    'state' => 'CA',
    'country' => 'USA',
    'capital' => false,
    'population' => 860000
]);
$citiesRef->document('LA')->set([
    'name' => 'Los Angeles',
    'state' => 'CA',
    'country' => 'USA',
    'capital' => false,
    'population' => 3900000
]);
$citiesRef->document('DC')->set([
    'name' => 'Washington D.C.',
    'state' => null,
    'country' => 'USA',
    'capital' => true,
    'population' => 680000
]);
$citiesRef->document('TOK')->set([
    'name' => 'Tokyo',
    'state' => null,
    'country' => 'Japan',
    'capital' => true,
    'population' => 9000000
]);
$citiesRef->document('BJ')->set([
    'name' => 'Beijing',
    'state' => null,
    'country' => 'China',
    'capital' => true,
    'population' => 21500000
]);
printf('Added example cities data to the cities collection.' . PHP_EOL);
query_create_examples.php

Consultas simples

A seguinte consulta mostra todas as cidades do estado CA:

// Create a reference to the cities collection
var citiesRef = db.collection("cities");

// Create a query against the collection.
var query = citiesRef.where("state", "==", "CA");
test.firestore.js

// Create a reference to the cities collection
let citiesRef = db.collection("cities")

// Create a query against the collection.
let query = citiesRef.whereField("state", isEqualTo: "CA")
ViewController.swift

// Create a reference to the cities collection
FIRCollectionReference *citiesRef = [self.db collectionWithPath:@"cities"];
// Create a query against the collection.
FIRQuery *query = [citiesRef queryWhereField:@"state" isEqualTo:@"CA"];
ViewController.m
  

// Create a reference to the cities collection
CollectionReference citiesRef = db.collection("cities");

// Create a query against the collection.
Query query = citiesRef.whereEqualTo("state", "CA");
DocSnippets.java

// Create a reference to the cities collection
CollectionReference cities = db.collection("cities");
// Create a query against the collection.
Query query = cities.whereEqualTo("state", "CA");
// retrieve  query results asynchronously using query.get()
ApiFuture<QuerySnapshot> querySnapshot = query.get();

for (DocumentSnapshot document : querySnapshot.get().getDocuments()) {
  System.out.println(document.getId());
}
QueryDataSnippets.java

# Create a reference to the cities collection
cities_ref = db.collection(u'cities')

# Create a query against the collection
query_ref = cities_ref.where(u'state', u'==', u'CA')
snippets.py

// Create a reference to the cities collection
var citiesRef = db.collection('cities');

// Create a query against the collection
var queryRef = citiesRef.where('state', '==', 'CA');
index.js

query := client.Collection("cities").Where("state", "==", "CA")
query.go

$citiesRef = $db->collection('cities');
$query = $citiesRef->where('state', '=', 'CA');
$snapshot = $query->documents();
foreach ($snapshot as $document) {
    printf('Document %s returned by query state=CA' . PHP_EOL, $document->id());
}
create_query_state.php

A consulta a seguir retorna todas as capitais:

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

var query = citiesRef.where("capital", "==", true);
test.firestore.js

let capitalCities = db.collection("cities").whereField("capital", isEqualTo: true)
ViewController.swift

FIRQuery *capitalCities =
    [[self.db collectionWithPath:@"cities"] queryWhereField:@"capital" isEqualTo:@YES];
ViewController.m
  

Query capitalCities = db.collection("cities").whereEqualTo("capital", true);
DocSnippets.java

// Create a reference to the cities collection
CollectionReference cities = db.collection("cities");
// Create a query against the collection.
Query query = cities.whereEqualTo("capital", true);
// retrieve  query results asynchronously using query.get()
ApiFuture<QuerySnapshot> querySnapshot = query.get();

for (DocumentSnapshot document : querySnapshot.get().getDocuments()) {
  System.out.println(document.getId());
}
QueryDataSnippets.java

cities_ref = db.collection(u'cities')

query = cities_ref.where(u'capital', u'==', True)
snippets.py

// Create a reference to the cities collection
var citiesRef = db.collection('cities');

// Create a query against the collection
var queryRef = citiesRef.where('capital', '==', true);
index.js

query := client.Collection("cities").Where("capital", "==", true)
query.go

$citiesRef = $db->collection('cities');
$query = $citiesRef->where('capital', '=', true);
$snapshot = $query->documents();
foreach ($snapshot as $document) {
    printf('Document %s returned by query capital=true' . PHP_EOL, $document->id());
}
create_query_capital.php

O método where() usa três parâmetros: um campo de filtro, uma operação de comparação e um valor. A comparação pode ser <, <=, ==, > ou >=. Para iOS, Android e Java, o operador de comparação é explicitamente nomeado no método.

Alguns exemplos de filtros:

citiesRef.where("state", "==", "CA")
citiesRef.where("population", "<", 100000)
citiesRef.where("name", ">=", "San Francisco")
test.firestore.js

citiesRef.whereField("state", isEqualTo: "CA")
citiesRef.whereField("population", isLessThan: 100000)
citiesRef.whereField("name", isGreaterThanOrEqualTo: "San Francisco")
ViewController.swift

[citiesRef queryWhereField:@"state" isEqualTo:@"CA"];
[citiesRef queryWhereField:@"population" isLessThan:@100000];
[citiesRef queryWhereField:@"name" isGreaterThanOrEqualTo:@"San Francisco"];
ViewController.m
  

citiesRef.whereEqualTo("state", "CA");
citiesRef.whereLessThan("population", 100000);
citiesRef.whereGreaterThanOrEqualTo("name", "San Francisco");
DocSnippets.java

Query countryQuery = cities.whereEqualTo("state", "CA");
Query populationQuery = cities.whereLessThan("population", 1000000L);
Query cityQuery = cities.whereGreaterThanOrEqualTo("name", "San Francisco");
QueryDataSnippets.java

cities_ref = db.collection(u'cities')

cities_ref.where(u'state', u'==', u'CA')
cities_ref.where(u'population', u'<', 1000000)
cities_ref.where(u'name', u'>=', u'San Francisco')
snippets.py

var brazilCities = citiesRef.where('state', '==', 'CA');
var smallCities = citiesRef.where('population', '<', 1000000);
var afterParis = citiesRef.where('name', '>=', 'San Francisco');
index.js

countryQuery := cities.Where("state", "==", "CA")
popQuery := cities.Where("population", "<", 1000000)
cityQuery := cities.Where("name", ">=", "San Francisco")
query.go

$stateQuery = $citiesRef->where('state', '=', 'CA');
$populationQuery = $citiesRef->where('population', '>', 1000000);
$nameQuery = $citiesRef->where('name', '>=', 'San Francisco');
simple_queries.php

Consultas compostas

Você também pode encadear diversos métodos where() para criar consultas mais específicas (AND lógico). No entanto, para combinar o operador de igualdade (==) com uma comparação de intervalo (<, <=, > ou >=), crie um índice personalizado.

citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("state", "==", "CA").where("population", "<", 1000000)
test.firestore.js

citiesRef
    .whereField("state", isEqualTo: "CO")
    .whereField("name", isEqualTo: "Denver")
citiesRef
    .whereField("state", isEqualTo: "CA")
    .whereField("population", isLessThan: 1000000)
ViewController.swift

[[citiesRef queryWhereField:@"state" isEqualTo:@"CO"]
    queryWhereField:@"name" isGreaterThanOrEqualTo:@"Denver"];
[[citiesRef queryWhereField:@"state" isEqualTo:@"CA"]
    queryWhereField:@"population" isLessThan:@1000000];
ViewController.m
  

citiesRef.whereEqualTo("state", "CO").whereEqualTo("name", "Denver");
citiesRef.whereEqualTo("state", "CA").whereLessThan("population", 1000000);
DocSnippets.java

Query chainedQuery1 = cities.whereEqualTo("state", "CO")
    .whereEqualTo("name", "Denver");Query chainedQuery2 = cities.whereEqualTo("state", "CA")
    .whereLessThan("population", 1000000L);
QueryDataSnippets.java

cities_ref = db.collection(u'cities')

sydney_query = cities_ref.where(
    u'state', u'==', u'CO').where(u'name', u'==', u'Denver')
large_us_cities_query = cities_ref.where(
    u'state', u'==', u'CA').where(u'population', u'>', 1000000)
snippets.py

citiesRef.where('state', '==', 'CO').where('name', '==', 'Denver');citiesRef.where('state', '==', 'CA').where('population', '<', 1000000);
index.js

denverQuery := cities.Where("name", "==", "Denver").Where("state", "==", "CO")
caliQuery := cities.Where("state", "==", "CA").Where("population", "<=", 1000000)query := cities.Where("country", "==", "USA").Where("population", ">", 5000000)
query.go

$chainedQuery = $citiesRef
    ->where('state', '=', 'CA')
    ->where('name', '=', 'San Francisco');
chained_query.php
$chainedQuery = $citiesRef
    ->where('state', '=', 'CA')
    ->where('population', '<', 1000000);
composite_index_chained_query.php

Além disso, só é possível realizar comparações de intervalo (<, <=, >, >=) em um único campo:

Válido: filtros de intervalo em apenas um campo

citiesRef.where("state", ">=", "CA").where("state", "<=", "IN")
citiesRef.where("state", "==", "CA").where("population", ">", 1000000)
test.firestore.js

citiesRef
    .whereField("state", isGreaterThanOrEqualTo: "CA")
    .whereField("state", isLessThanOrEqualTo: "IN")
citiesRef
    .whereField("state", isEqualTo: "CA")
    .whereField("population", isGreaterThan: 1000000)
ViewController.swift

[[citiesRef queryWhereField:@"state" isGreaterThanOrEqualTo:@"CA"]
    queryWhereField:@"state" isLessThanOrEqualTo:@"IN"];
[[citiesRef queryWhereField:@"state" isEqualTo:@"CA"]
    queryWhereField:@"population" isGreaterThan:@1000000];
ViewController.m
  

citiesRef.whereGreaterThanOrEqualTo("state", "CA")
        .whereLessThanOrEqualTo("state", "IN");
citiesRef.whereEqualTo("state", "CA")
        .whereGreaterThan("population", 1000000);
DocSnippets.java

Query validQuery1 = cities.whereGreaterThanOrEqualTo("state", "CA")
    .whereLessThanOrEqualTo("state", "IN");
Query validQuery2 = cities.whereEqualTo("state", "CA")
    .whereGreaterThan("population", 1000000);
QueryDataSnippets.java

cities_ref = db.collection(u'cities')
cities_ref.where(u'state', u'>=', u'CA').where(u'state', u'<=', u'IN')
snippets.py

citiesRef.where('state', '>=', 'CA').where('state', '<=', 'IN');
citiesRef.where('state', '==', 'CA').where('population', '>', 1000000);
index.js

stateQuery := cities.Where("state", ">=", "CA").Where("state", "<", "IN")
populationQuery := cities.Where("state", "==", "CA").Where("population", ">", 1000000)
query.go

$rangeQuery = $citiesRef
    ->where('state', '>=', 'CA')
    ->where('state', '<=', 'IN');
range_query.php

Inválido: filtros de intervalo em campos diferentes

citiesRef.where("state", ">=", "CA").where("population", ">", 100000)
test.firestore.js

citiesRef
    .whereField("state", isGreaterThanOrEqualTo: "CA")
    .whereField("population", isGreaterThan: 1000000)
ViewController.swift

[[citiesRef queryWhereField:@"state" isGreaterThanOrEqualTo:@"CA"]
    queryWhereField:@"population" isGreaterThan:@1000000];
ViewController.m
  

citiesRef.whereGreaterThanOrEqualTo("state", "CA").whereGreaterThan("population", 100000);
DocSnippets.java

Query invalidRangeQuery = cities.whereGreaterThanOrEqualTo("state", "CA")
    .whereGreaterThan("population", 100000);
QueryDataSnippets.java

cities_ref = db.collection(u'cities')
cities_ref.where(
    u'state', u'>=', u'CA').where(u'population', u'>=', 1000000)
snippets.py

citiesRef.where('state', '>=', 'CA').where('population', '>', 1000000);
index.js

query := cities.Where("state", ">=", "CA").Where("population", ">", 1000000)
query.go

$invalidRangeQuery = $citiesRef
    ->where('state', '>=', 'CA')
    ->where('population', '>', 1000000);
invalid_range_query.php

Limitações de consulta

O Cloud Firestore não aceita os tipos de consultas a seguir:

• Consultas com filtros de intervalo em campos diferentes, conforme descrito na seção anterior.
• Consultas simples em várias coleções ou subcoleções. Cada consulta é executada em uma única coleção de documentos. Para saber mais sobre como a estrutura de dados afeta as consultas, consulte Escolher uma estrutura de dados.
• Consultas de membros de matrizes individuais. Mas você pode modelar e consultar dados semelhantes a uma matriz usando as técnicas descritas em Como trabalhar com matrizes, listas e conjuntos.
• Consultas com operador lógico OR. Nesse caso, crie uma consulta separada para cada condição OR e mescle os resultados da consulta no seu app.
• Consultas com uma cláusula !=. Nesse caso, divida a consulta em duas: uma do tipo “maior que” e outra do tipo “menor que”. Por exemplo, a cláusula de consulta where("age", "!=", "30") não é aceita, mas você poderá conseguir o mesmo conjunto de resultados se combinar duas consultas, uma com a cláusula where("age", "<", "30") e outra com a cláusula where("age", ">", 30).