在 Cloud Firestore 中执行简单查询和复合查询

Cloud Firestore 提供了强大的查询功能，您可使用此功能指定要从集合中检索的具体文档。这些查询也可以与 get() 或 addSnapshotListener() 配合使用，具体请参阅获取数据和获取实时更新中的说明。

示例数据

首先，请编写一些关于城市的数据，以便我们确定读回这些数据的不同方式：

网页
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
Swift
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
Objective-C
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
Android
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
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
Python
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
Node.js
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
Go
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
PHP
$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

简单查询

以下查询会返回 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
Swift
// 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
Objective-C
// 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
Android
// 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
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
Python
# 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
Node.js
// 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
Go
query := client.Collection("cities").Where("state", "==", "CA")
query.go
PHP
$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

以下查询会返回所有首都：

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

var query = citiesRef.where("capital", "==", true);
test.firestore.js
Swift
let capitalCities = db.collection("cities").whereField("capital", isEqualTo: true)
ViewController.swift
Objective-C
FIRQuery *capitalCities =
    [[self.db collectionWithPath:@"cities"] queryWhereField:@"capital" isEqualTo:@YES];
ViewController.m
Android
Query capitalCities = db.collection("cities").whereEqualTo("capital", true);
DocSnippets.java
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
Python
cities_ref = db.collection(u'cities')

query = cities_ref.where(u'capital', u'==', True)
snippets.py
Node.js
// 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
Go
query := client.Collection("cities").Where("capital", "==", true)
query.go
PHP
$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

where() 方法会传递三个参数：作为过滤依据的字段、比较运算符和值。比较运算符可以是 <、<=、==、> 或 >=。对于 iOS、Android 和 Java，比较运算符会在方法中明确指定。

下面是一些示例过滤条件：

网页
citiesRef.where("state", "==", "CA")
citiesRef.where("population", "<", 100000)
citiesRef.where("name", ">=", "San Francisco")
test.firestore.js
Swift
citiesRef.whereField("state", isEqualTo: "CA")
citiesRef.whereField("population", isLessThan: 100000)
citiesRef.whereField("name", isGreaterThanOrEqualTo: "San Francisco")
ViewController.swift
Objective-C
[citiesRef queryWhereField:@"state" isEqualTo:@"CA"];
[citiesRef queryWhereField:@"population" isLessThan:@100000];
[citiesRef queryWhereField:@"name" isGreaterThanOrEqualTo:@"San Francisco"];
ViewController.m
Android
citiesRef.whereEqualTo("state", "CA");
citiesRef.whereLessThan("population", 100000);
citiesRef.whereGreaterThanOrEqualTo("name", "San Francisco");
DocSnippets.java
Java
Query countryQuery = cities.whereEqualTo("state", "CA");
Query populationQuery = cities.whereLessThan("population", 1000000L);
Query cityQuery = cities.whereGreaterThanOrEqualTo("name", "San Francisco");
QueryDataSnippets.java
Python
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
Node.js
var brazilCities = citiesRef.where('state', '==', 'CA');
var smallCities = citiesRef.where('population', '<', 1000000);
var afterParis = citiesRef.where('name', '>=', 'San Francisco');
index.js
Go
countryQuery := cities.Where("state", "==", "CA")
popQuery := cities.Where("population", "<", 1000000)
cityQuery := cities.Where("name", ">=", "San Francisco")
query.go
PHP
$stateQuery = $citiesRef->where('state', '=', 'CA');
$populationQuery = $citiesRef->where('population', '>', 1000000);
$nameQuery = $citiesRef->where('name', '>=', 'San Francisco');
simple_queries.php

复合查询

您还可以链接多个 where() 方法来创建更具体的查询（逻辑 AND）。不过，要将等式运算符 (==) 与范围比较运算符（<、<=、> 或 >=）组合使用，请务必创建一个自定义索引。

网页
citiesRef.where("state", "==", "CO").where("name", "==", "Denver")
citiesRef.where("state", "==", "CA").where("population", "<", 1000000)
test.firestore.js
Swift
citiesRef
    .whereField("state", isEqualTo: "CO")
    .whereField("name", isEqualTo: "Denver")
citiesRef
    .whereField("state", isEqualTo: "CA")
    .whereField("population", isLessThan: 1000000)
ViewController.swift
Objective-C
[[citiesRef queryWhereField:@"state" isEqualTo:@"CO"]
    queryWhereField:@"name" isGreaterThanOrEqualTo:@"Denver"];
[[citiesRef queryWhereField:@"state" isEqualTo:@"CA"]
    queryWhereField:@"population" isLessThan:@1000000];
ViewController.m
Android
citiesRef.whereEqualTo("state", "CO").whereEqualTo("name", "Denver");
citiesRef.whereEqualTo("state", "CA").whereLessThan("population", 1000000);
DocSnippets.java
Java
Query chainedQuery1 = cities.whereEqualTo("state", "CO")
    .whereEqualTo("name", "Denver");
Query chainedQuery2 = cities.whereEqualTo("state", "CA")
    .whereLessThan("population", 1000000L);
QueryDataSnippets.java
Python
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
Node.js
citiesRef.where('state', '==', 'CO').where('name', '==', 'Denver');
citiesRef.where('state', '==', 'CA').where('population', '<', 1000000);
index.js
Go
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
PHP
$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

此外，您只能在单个字段上执行范围比较（<、<=、>、>=）：

有效：范围过滤器仅针对一个字段

网页
citiesRef.where("state", ">=", "CA").where("state", "<=", "IN")
citiesRef.where("state", "==", "CA").where("population", ">", 1000000)
test.firestore.js
Swift
citiesRef
    .whereField("state", isGreaterThanOrEqualTo: "CA")
    .whereField("state", isLessThanOrEqualTo: "IN")
citiesRef
    .whereField("state", isEqualTo: "CA")
    .whereField("population", isGreaterThan: 1000000)
ViewController.swift
Objective-C
[[citiesRef queryWhereField:@"state" isGreaterThanOrEqualTo:@"CA"]
    queryWhereField:@"state" isLessThanOrEqualTo:@"IN"];
[[citiesRef queryWhereField:@"state" isEqualTo:@"CA"]
    queryWhereField:@"population" isGreaterThan:@1000000];
ViewController.m
Android
citiesRef.whereGreaterThanOrEqualTo("state", "CA")
        .whereLessThanOrEqualTo("state", "IN");
citiesRef.whereEqualTo("state", "CA")
        .whereGreaterThan("population", 1000000);
DocSnippets.java
Java
Query validQuery1 = cities.whereGreaterThanOrEqualTo("state", "CA")
    .whereLessThanOrEqualTo("state", "IN");
Query validQuery2 = cities.whereEqualTo("state", "CA")
    .whereGreaterThan("population", 1000000);
QueryDataSnippets.java
Python
cities_ref = db.collection(u'cities')
cities_ref.where(u'state', u'>=', u'CA').where(u'state', u'<=', u'IN')
snippets.py
Node.js
citiesRef.where('state', '>=', 'CA').where('state', '<=', 'IN');
citiesRef.where('state', '==', 'CA').where('population', '>', 1000000);
index.js
Go
stateQuery := cities.Where("state", ">=", "CA").Where("state", "<", "IN")
populationQuery := cities.Where("state", "==", "CA").Where("population", ">", 1000000)
query.go
PHP
$rangeQuery = $citiesRef
    ->where('state', '>=', 'CA')
    ->where('state', '<=', 'IN');
range_query.php

无效：范围过滤条件针对的是不同字段

网页
citiesRef.where("state", ">=", "CA").where("population", ">", 100000)
test.firestore.js
Swift
citiesRef
    .whereField("state", isGreaterThanOrEqualTo: "CA")
    .whereField("population", isGreaterThan: 1000000)
ViewController.swift
Objective-C
[[citiesRef queryWhereField:@"state" isGreaterThanOrEqualTo:@"CA"]
    queryWhereField:@"population" isGreaterThan:@1000000];
ViewController.m
Android
citiesRef.whereGreaterThanOrEqualTo("state", "CA").whereGreaterThan("population", 100000);
DocSnippets.java
Java
Query invalidRangeQuery = cities.whereGreaterThanOrEqualTo("state", "CA")
    .whereGreaterThan("population", 100000);
QueryDataSnippets.java
Python
cities_ref = db.collection(u'cities')
cities_ref.where(
    u'state', u'>=', u'CA').where(u'population', u'>=', 1000000)
snippets.py
Node.js
citiesRef.where('state', '>=', 'CA').where('population', '>', 1000000);
index.js
Go
query := cities.Where("state", ">=", "CA").Where("population", ">", 1000000)
query.go
PHP
$invalidRangeQuery = $citiesRef
    ->where('state', '>=', 'CA')
    ->where('population', '>', 1000000);
invalid_range_query.php

查询限制

Cloud Firestore 不支持以下类型的查询：

  • 范围过滤条件针对的是不同字段的查询（如上一部分中所述）。
  • 跨多个集合或子集合的单个查询。每个查询都应针对文档的单一集合来执行。如需详细了解数据结构对查询的影响，请参阅选择数据结构。
  • 查询个别数组成员。但是，您可以使用使用数组、列表和集中介绍的技术对类似数组的数据进行建模和查询。
  • 逻辑 OR 查询。在这种情况下，您应该为每个 OR 条件创建一个单独的查询，并在应用中合并查询结果。
  • 使用 != 子句进行的查询。在这种情况下，您应该将查询拆分为一个“大于”查询和一个“小于”查询。例如，虽然查询子句 where("age", "!=", "30") 不受支持，但您可以通过将两个查询（分别使用子句 where("age", "<", "30") 和 where("age", ">", 30)）合并在一起来获得同样的结果集。

发送以下问题的反馈：

此网页
文档反馈
Firebase
Firebase
产品反馈
需要帮助？请访问我们的支持页面。