创建查询筛选器

Overview

在本指南中，您可以学习；了解如何使用MongoDB .NET/ C#驱动程序创建查询过滤。查询过滤是一个表达式，用于指定要在增删改查操作中读取、更新或删除的文档。您可以使用 Builders<TDocument>.Filter静态属性中提供的构建器方法来创建查询筛选器并向其添加操作。

注意

方法重载

此页面上的许多方法都有多个重载。本指南中的示例仅显示每种方法的一个定义。有关可用重载的更多信息，请参阅 API文档。

样本数据

本指南中的示例使用名为 guitars 的集合中的以下文档：

{ "_id": 1, "make": "Fender", "models": ["Stratocaster", "Telecaster"], "establishedYear": 1946, "rating": 9 }
{ "_id": 2, "make": "Gibson", "models": ["Les Paul", "SG", "Explorer"], "establishedYear": 1902, "rating": 8 }
{ "_id": 3, "make": "PRS", "models": ["Silver Sky", "SE", "Custom"], "establishedYear": 1985, "rating": 9 }
{ "_id": 4, "make": "Kiesel", "models": ["Ares", "Vader", "Solo"], "establishedYear": 2015 }
{ "_id": 5, "make": "Ibanez", "models": ["RG", "AZ"], "establishedYear": 1957, "rating": 7 }
{ "_id": 6, "make": "Strandberg", "models": ["Boden", "Salen"], "establishedYear": 1982 }

以下 Guitar 类对此集合中的文档进行建模：

public class Guitar
{
    public int Id { get; set; }
    public string Make { get; set; }
    public List<string> Models { get; set; }
    public int EstablishedYear { get; set; }
    public int? Rating { get; set; }
}

要运行此页面上的代码示例，您必须获取对 guitars集合的引用，如以下示例所示：

var client = new MongoClient("localhost://27017");
var guitarCollection = client.GetDatabase("example").GetCollection<Guitar>("guitars");

注意

guitars 集合中的文档使用驼峰命名约定。本指南中的示例使用 ConventionPack 将集合中的字段反序列化为 Pascal 语句，然后映射到 Guitar 类中的属性。

要学习；了解创建和序列化自定义类的更多信息，请参阅以下页面：

查找所有文档

空查询过滤匹配集合中的所有文档。以下示例展示了如何创建空查询过滤：

var filter = Builders<Guitar>.Filter.Empty;

比较操作符。

比较操作符将查询值与指定字段中的值进行比较。其中一些方法具有替代语法，您可以使用它们来代替该方法，如以下示例所示：

var filter = Builders<Guitar>.Filter.Eq(g => g.Make, "Fender");
var results = guitarCollection.Find(filter).ToList();
// Alternative syntax
var results = guitarCollection.Find(g => g.Make == "Fender").ToList();;

下表列出了用于比较操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	替代语法	说明	MongoDB Server Operator
`Eq()`	`==`	匹配指定字段的值等于查询值的文档。	$eq
`Gt()`	`>`	匹配指定字段的值大于查询值的文档。	$gt
`Gte()`	`>=`	匹配指定大量字段中的任何元素大于或等于查询值的文档。	$gte
`In()`	不适用	匹配指定大量字段中的任意元素与查询大量中的任意值匹配的文档。	$in
`Lt()`	`<`	匹配指定大量字段中的任意元素小于查询值的文档。	$lt
`Lte()`	`<=`	匹配指定大量字段中的任何元素小于或等于查询值的文档。	$lte
`Ne()`	`!=`	匹配指定大量字段中任何元素不等于查询值的文档。	$ne
`Nin()`	不适用	匹配满足以下条件之一的文档：指定大量字段中的任何元素都不与查询大量中的任何值匹配。指定的字段不存在。	$nin
`StringIn()`	不适用	匹配指定字段的字符串值与查询大量中的任何字符串值匹配的文档。	$in
`StringNin()`	不适用	匹配指定字段的字符串值与查询大量中的任何字符串值都不匹配的文档。	$in

以下示例调用 Find() 方法并传递 lambda过滤，驾驶员会将其转换为查询过滤。该查询匹配 establishedYear字段大于 1985 的所有文档。

// Finds all documents with an "establishedYear" value greater than 1985
var results = guitarCollection.Find(g => g.EstablishedYear > 1985).ToList();
foreach (var doc in results)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }

以下示例使用构建器创建一个查询筛选器，该筛选器匹配的文档与前面的示例相同：

// Creates a filter for all documents with an "establishedYear" value greater
// than 1985
var filter = Builders<Guitar>.Filter.Gt(g => g.EstablishedYear, 1985);
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }

以下示例调用 Find() 方法并传递 lambda表达式，驾驶员会将其转换为查询过滤。该查询匹配 make字段等于“Fender”的所有文档。

// Finds all documents with a "make" value of "Fender"
var results = guitarCollection.Find(g => g.Make == "Fender").ToList();
foreach (var doc in results)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }

以下示例使用构建器创建一个查询筛选器，该筛选器匹配的文档与前面的示例相同：

// Creates a filter for all documents with a "make" value of "Fender"
var filter = Builders<Guitar>.Filter.Eq(g => g.Make, "Fender");
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }

逻辑操作符

逻辑运算符可组合两个或多个表达式，并根据这些表达式的结果返回结果。这些方法具有替代语法，您可以使用这些语法来代替该方法，如以下示例所示：

var builder = Builders<Guitar>.Filter;
var filter = builder.And(
   builder.Gte(g => g.EstablishedYear, 1985),
   builder.Ne(r => r.Make, "Kiesel"));
var results = guitarCollection.Find(filter).ToList();
// Alternative syntax
var results = guitarCollection.Find(
   g => g.EstablishedYear >= 1985
   && g.Make != "Kiesel")
.ToList();

下表列出了用于逻辑操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	替代语法	说明	MongoDB Server Operator
`And()`	`&&`	匹配所有表达式的计算结果均为 true 的文档。	$and
`Or()`	`\|\|`	匹配一个或多个表达式计算结果为 true 的文档。	$or

以下示例调用 Find() 方法并传递 lambda表达式，驾驶员会将其转换为查询过滤。该查询匹配 establishedYear字段大于或等于 1985 且 make字段不等于 "Kiesel" 的所有文档。

// Finds all documents with an "establishedYear" value greater than 1985
// and a "make" value that is not equal to "Kiesel"
var results = guitarCollection.Find(g => g.EstablishedYear >= 1985 && r.Make != "Kiesel").ToList();
foreach (var doc in results)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }

以下示例使用构建器创建一个查询筛选器，该筛选器匹配的文档与前面的示例相同：

// Creates a filter for all documents with an "establishedYear" value greater
// than 1985 and a "make" value that does not equal "Kiesel"
var builder = Builders<Guitar>.Filter;
var filter = builder.And(builder.Gte(g => g.EstablishedYear, 1985), builder.Ne(r => r.Make, "Kiesel"));
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }

数组操作符

数组操作符根据大量字段中元素的值或数量来匹配文档。下表列出了大量操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	说明	MongoDB Server Operator
`All()`	匹配指定大量字段中的值与所有查询值均匹配的文档。	$all
`AnyEq()`	匹配指定大量字段中的任何元素与查询值匹配的文档。	$elemMatch
`AnyGt()`	匹配指定大量字段中的任何元素大于查询值的文档。	$elemMatch
`AnyGte()`	匹配指定大量字段中的任何元素大于或等于查询值的文档。	$elemMatch
`AnyIn()`	匹配指定大量字段中的任意元素与查询大量中的任意值匹配的文档。	$elemMatch
`AnyLt()`	匹配指定大量字段中的任意元素小于查询值的文档。	$elemMatch
`AnyLte()`	匹配指定大量字段中的任何元素小于或等于查询值的文档。	$elemMatch
`AnyNe()`	匹配指定大量字段中任何元素不等于查询值的文档。	$elemMatch
`AnyNin()`	匹配满足以下条件之一的文档：指定大量字段中的任何元素都不在查询大量中。指定的字段不存在。	$elemMatch
`AnyStringIn()`	匹配指定大量字段中任何字符串元素与查询大量中任何字符串值相匹配的文档。	$elemMatch
`AnyStringNin()`	匹配满足以下条件之一的文档：指定大量字段中的任何字符串元素都不在查询大量中。指定的字段不存在。	$elemMatch
`ElemMatch()`	匹配指定大量字段中的任何元素与查询条件匹配的文档。	$elemMatch
`Size()`	匹配指定大量字段为指定大小的文档。	$size
`SizeGt()`	匹配指定大量字段大于指定大小的文档。	$size
`SizeGte()`	匹配指定大量字段大于或等于指定大小的文档。	$size
`SizeLt()`	匹配指定大量字段小于指定大小的文档。	$size
`SizeLte()`	匹配指定大量字段小于或等于指定大小的文档。	$size

以下示例使用构建者创建一个查询过滤，该筛选器匹配在 models字段中恰好包含三个元素的所有文档：

// Creates a filter for all documents with 3 elements in the "models" field
var filter = Builders<Guitar>.Filter.Size(g => g.Models, 3);
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }
{ "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }
{ "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }

元素操作符

元素操作符根据字段的存在或类型匹配文档查询数据。下表列出了元素操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	说明	MongoDB Server Operator
`Exists()`	匹配包含或不包含指定字段的文档，包括字段值为 `null` 的文档。	$exists
`Type()`	匹配指定字段的值为指定BSON 类型实例的文档。	$type

以下示例使用构建器创建一个查询筛选器，该筛选器匹配具有 rating 字段的所有文档：

// Creates a filter for all documents with a populated "ratings" field
var filter = Builders<Guitar>.Filter.Exists(g => g.Rating);
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }
{ "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }
{ "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }
{ "_id" : 5, "make" : "Ibanez", "models" : ["RG", "AZ"], "establishedYear" : 1957, "rating" : 7 }

评估操作符

评估操作符分析单个字段中的数据或集合中的所有文档。下表列出了用于评估操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	说明	MongoDB Server Operator
`JsonSchema()`	匹配满足指定JSON schema的文档。	$jsonSchema
`Mod()`	匹配指定字段的值除以除数后具有指定余数（模数）的文档。	$mod
`RegEx()`	匹配指定字段的值与指定正则表达式匹配的文档。	$regex
`Where()`	用于将包含JavaScript表达式的字符串或完整的JavaScript函数传递给查询系统。	$where

以下示例使用构建器创建一个查询筛选器，该筛选器匹配 make 字段中具有以字母 "G" 开头的值的所有文档：

// Creates a filter for all documents with a populated "ratings" field
var filter = Builders<Guitar>.Filter.Regex(g => g.Make, "^G");
// Finds all documents that match the filter
var result = guitarCollection.Find(filter).ToList();
foreach (var doc in result)
{
    // Prints the documents in bson (json) format
    Console.WriteLine(doc.ToBsonDocument());
}

{ "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }

地理空间操作符

地理空间操作符根据地理空间表达式条件返回数据。下表列出了地理空间操作的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	说明	MongoDB Server Operator
`GeoIntersects()`	匹配地理空间数据与指定 GeoJsonObject 相交的文档。	$geoIntersects
`GeoWithin()`	匹配地理空间数据完全在指定形状内的文档。	$geoWithin
`GeoWithinBox()`	匹配地理空间数据完全在指定框中的文档。	$geoWithin 、 $box
`GeoWithinCenter()`	匹配地理空间数据完全在指定圆圈内的文档。	$geoWithin 、 $center
`GeoWithinCenterSphere()`	匹配地理空间数据完全在指定范围内的文档。	$geoWithin 、 $centerSphere
`GeoWithinPolygon()`	匹配地理空间数据完全在指定多边形内的文档。	$geoWithin , $ 多边形
`Near()`	指定地理空间查询返回从最近到最远的文档的点。	$near
`NearSphere()`	指定一个点，地理空间查询将按球面几何从最近到最远的顺序返回该点的文档。	$nearSphere

按位操作符

按位运算符根据位位置条件匹配文档。下表列出了用于按位运算的.NET/ C#驱动程序方法和等效的MongoDB Server操作符：

.NET/ C#驱动程序程序方法	说明	MongoDB Server Operator
`BitsAllClear()`	匹配指定字段中所有指定位位置均已清除 (`0`) 的文档。	$bitsAllClear
`BitsAllSet()`	匹配在指定字段中所有指定位位置均已设立(`1`) 的文档。	$bitsAllSet
`BitsAnyClear()`	匹配指定字段中任何指定位位置已清除 (`0`) 的文档。	$bitsAnyClear
`BitsAnySet()`	匹配在指定字段中设立了任何指定位位置 (`1`) 的文档。	$bitsAnySet

其他操作符

.NET/ C#驱动程序还提供了以下用于创建过滤定义的方法：

.NET/ C#驱动程序程序方法	说明
`OfType()`	匹配派生自指定类型的文档。您可以使用此方法的重载来指定其他查询条件。
`Text()`	将文档与包含指定字符串的字段进行匹配。