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" 的人，这和之前的例子是一样的，不同的是：

1. 将 size 设为 0 ，因为我们不需要查到的前 10 份文档，我们只对聚合结果感兴趣
2. 指定了一个 terms 聚合，从而将搜索结果按照姓氏分组

termsAggregation 可以用于获取每个桶的文档数量，其中每个桶的键是姓氏。更多信息，请参阅 Writing aggregations