NEST 之旅 · 开启
NEST 之旅 · 开启
Version:5.x
英文原文地址:Getting started
说实话,这篇文章翻译的很糟糕。但是我的能力有限,目前只有这个水平,还望各位多指导。
NEST 是 Elasticsearch 的一个高层级的 .NET 客户端,但是它仍然非常接近原始的 Elasticsearch API 。NEST 中所有的请求和响应都是通过类型公开的,这使得它可以快速地启动和运行。
在美丽的外表之下,NEST 有着一个强大的低层级的核心 - Elasticsearch.Net 。有了这个核心,NEST 才得以(向 Elasticsearch 本体服务程序)发送请求和接收响应。这个过程中,NEST 使用和扩展了 Elasticsearch.NET 的许多类型。另外,NEST 公开了这个低级客户端,你可以通过 .LowLevel 属性来访问。
Connecting
连接位于 http://localhost:9200
的本地 Elasticsearch 是非常简单的,你只需要实例化一个客户端的实例即可。
var client = new ElasticClient();
通常情况下,你会需要向客户端传递一些额外的配置选项。比如:你的 Elasticsearch 在远程服务器上运行,那你就需要传递它的具体地址。 ConnectionSettings
参数就是来接收这些配置信息的,有了它你就可以根据不同的配置实例化出相应的客户端。
var settings = new ConnectionSettings(new Uri("http://example.com:9200"))
.DefaultIndex("people");
var client = new ElasticClient(settings);
仔细看上面这个例子,我们设置了一个默认索引。如果请求中没有明确提供其他索引,并且无法从 POCO 泛型参数中推断出索引,就会使用这个默认索引。ConnectionSettings
继承自 ConnnectionConfiguraion
,Elasticsearch.NET (那个低层级的客户端)通过这个对象来接收额外的配置选项。了解更多的配置选项,请访问 Configuration options 。
注意,如果没有配置默认索引,而 NEST 又无法从请求中推断出索引,那它就会抛出一个异常。
ConnectionSettings
没有严格要求只能向 Elasticsearch 传递一个地址。NEST 中还提供了几种不同类型的连接池用来配置客户端。下面的栗子使用了一个 SniffingConnectionPool
,它包含了集群中 3 个 Elasticsearch 节点的地址。客户端将使用这种连接池来维护一个集群中可用节点的列表,这样便可以用循环的方式发送请求。
var uris = new[]
{
new Uri("http://localhost:9200"),
new Uri("http://localhost:9201"),
new Uri("http://localhost:9202"),
};
var connectionPool = new SniffingConnectionPool(uris);
var settings = new ConnectionSettings(connectionPool)
.DefaultIndex("people");
var client = new ElasticClient(settings);
Indexing
将客户端配置好并连接上 Elasticsearch 之后,我们需要往集群里存储一些数据。
假设我们有如下简单传统CLR对象(Plain Old CLR Object)
public class Person
{
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
}
使用同步或者异步的方式索引一个 POCO 实例
var person = new Person
{
Id = 1,
FirstName = "Martijn",
LastName = "Laarman"
};
var indexResponse = client.Index(person); (1)
var asyncIndexResponse = await client.IndexAsync(person); (2)
(1) 同步方法返回一个 IIndexResponse
对象
(2) 异步方法返回一个可等待的 Task<IIndexResponse>
对象
注意:NEST 中所有的方法都提供了同步和异步两种版本,异步方法使用 *Async 后缀命名
上述代码会将文档索引到 /people/person/1
。NEST 很聪明,它会根据 Person 的 CLR 类型来推断 type
,并根据 POCO 的 Id
属性来推断文档的 id
。了解 NEST 中推断文档 id
的其他方式,请参阅 Ids inference 。ConnectionSettings
中配置的默认索引会被用来当作请求的索引名。
警告:NEST 会将 POCO 序列化为 JSON 文档发送给 Elasticsearch。默认情况下,在执行序列化时,NEST 将 POCO 的属性名转换成驼峰式字符串。你可以使用
ConnectionSettings
的.DefaultFieldNameInferrer(Func<string,string>)
方法来改变这一行为。
Searching
我们已经索引了一些文档,接下来就可以开始查询了。
var searchResponse = client.Search<Person>(s => s
.From(0)
.Size(10)
.Query(q => q
.Match(m => m
.Field(f => f.FirstName)
.Query("Martijn")
)
)
);
var people = searchResponse.Documents;
people
变量现在保存着名字里包含 Martijn 的前十个人的文档。这个查询的搜索终端是 /people/person/_search
,其中索引名由 ConnectionSettings
中的默认索引确定,类型名由搜索时传递的泛型参数 Person
确定。
使用 .AllTypes()
可以搜索索引内的全部类型
var searchResponse = client.Search<Person>(s => s
.AllTypes()
.From(0)
.Size(10)
.Query(q => q
.Match(m => m
.Field(f => f.FirstName)
.Query("Martijn")
)
)
);
请求中可以提供单个或者多个索引和类型名,了解更多请分别参阅 Indices paths 和 Document paths 。
到目前为止,所有的搜索示例都使用了 NEST 的 Fluent API ,它使用 lambda 表达式构造结构化的查询,这一点模仿了 Elasticsearch 中的 Query DSL 的查询结构。
NEST 还公开了一个对象初始值设定语法,对于那些不热衷于深层嵌套子表达式的开发者,可以用这种方式来构造查询(布局是关键 ~)
这里有个和之前的栗子相同的查询,不过改成了使用对象初始值设定语法来构造查询
var searchRequest = new SearchRequest<Person>(Nest.Indices.All, Types.All) (1)
{
From = 0,
Size = 10,
Query = new MatchQuery
{
Field = Infer.Field<Person>(f => f.FirstName),
Query = "Martijn"
}
};
var searchResponse = await client.SearchAsync<Person>(searchRequest);
(1) 所有的索引和类型,都在构造函数中指定
笔记:本文开始的时候提到过,高层客户端通过
.LowLevel
属性公开了Elasticsearch.NET
的低层客户端。有些情况下,低层客户端会更合适。例如:你已经有了一个 JSON 对象,想直接发送给服务器,而不希望再把它转换成 Fluent API 或者 Object Initializer 语法。又或者说,高层客户端有一个 bug,让你不得不选择低层客户端。使用低层客户端,可以通过发送字符串或者匿名类型的请求来完成工作。通过
.LowLevel
来使用低层客户端,你可以使用 NEST 中所有的强类型和序列化功能这里有个示例:
var searchResponse = client.LowLevel.Search<SearchResponse<Person>>("people", "person", new { from = 0, size = 10, query = new { match = new { field = "firstName", query = "Martijn" } } }); var responseJson = searchResponse.Body;
可以看到,请求是一个匿名类型,但是响应体是 NEST 返回的响应类型的具体实现。
Aggregations
除了结构化和非结构化的查询,Elasticsearch 还支持聚合数据
var searchResponse = await client.SearchAsync<Person>(s => s
.Size(0)
.Query(q => q
.Match(m => m
.Field(f => f.FirstName)
.Query("Martijn")
)
)
.Aggregations(a => a
.Terms("last_names", ta => ta
.Field(f => f.LastName)
)
)
);
var termsAggregation = searchResponse.Aggs.Terms("last_names");
这个例子里,match
查询搜索出了名字里有 "Martijn" 的人,这和之前的例子是一样的,不同的是:
- 将 size 设为
0
,因为我们不需要查到的前 10 份文档,我们只对聚合结果感兴趣 - 指定了一个
terms
聚合,从而将搜索结果按照姓氏分组
termsAggregation
可以用于获取每个桶的文档数量,其中每个桶的键是姓氏。更多信息,请参阅 Writing aggregations
上一篇: .net Core学习笔记2 实现列表的条件筛选,排序,分页
下一篇: 介绍几种swf文件的加密方法