HMENetCore.Elasticsearch.V2 8.0.19

HMENetCore.Elasticsearch.V2

简介

HMENetCore.Elasticsearch.V2 是一个基于 Elastic.Clients.Elasticsearch (Elasticsearch 8.0) 的封装库，提供了对 Elasticsearch 的常用操作封装，包括索引管理、文档增删改查、批量操作、分页查询、滚动查询、SQL查询等功能.

功能特性

• 完整的CRUD操作封装
• 支持批量操作（插入、更新、删除）
• 丰富的查询方式（精确匹配、模糊匹配、分页查询等）
• 支持SQL查询
• 支持滚动查询（Scroll API）
• 支持聚合查询（Aggregations）
• 索引管理功能
• 依赖注入友好设计
• 线程安全

.NET支持

• 跨平台支持: Supports .NET Standard 2.1, .NET 6, .NET 8, and .NET 9.

安装

dotnet add package HMENetCore.Elasticsearch.V2 --version 8.0.12

配置数据库连接

添加配置到 appsettings.json：

{
  "ElasticSearchConfig": {
    "Uris ": ["http://server1:9200","http://server2:9200"],
    "UserName": "user",
    "PassWord": "pwd",
    "DefaultIndex": "default_index",
    "EnableTls": false
  }
}

服务注册

builder.Services.Configure<ElasticSearchConfig>(builder.Configuration.GetSection("ElasticSearchConfig"));
builder.Services.AddElasticSearchSetup(builder.Configuration.Get<ElasticSearchConfig>()!);

使用案例：

1.定义实体

[Table("person_index")]
public class Person
{
    public string Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
    public string Description { get; set; }
    public DateTime CreateTime { get; set; }
}

2.创建仓储

public class PersonRepository : BaseElasticSearchRepository<Person>
{
    public PersonRepository(IElasticSearchContext context) : base(context)
    {
    }
}

3.业务服务

public class PersonService : BaseElasticSearchService<Person>
{
    public PersonService(IElasticSearchCRUD<Person> repostory) : base(repostory)
    {
    }
}

4. 索引操作

// 创建索引
var success = await _personService.CreateIndexAsync(numberOfReplicas: 1, numberOfShards: 3);

// 判断索引是否存在
var exists = await _personService.IndexExistsAsync("person_index");

// 删除索引
var deleted = await _personService.DeleteIndexAsync("person_index");

// 清空索引数据
var cleared = await _personService.ClearIndexAsync("person_index");

文档CRUD案例

1. 插入文档

// 单条插入
var person = new Person { Id = "1", Name = "张三", Age = 25 };
var response = await _personService.InsertAsync(person);

// 批量插入
var persons = new List<Person> 
{
    new Person { Id = "2", Name = "李四", Age = 30 },
    new Person { Id = "3", Name = "王五", Age = 28 }
};
var bulkResponse = await _personService.InsertBulkAsync(persons);

2. 更新文档

// 单条更新
person.Age = 26;
var updateResponse = await _personService.UpdateAsync(person.Id, person);

// 批量更新
persons.ForEach(p => p.Age += 1);
var bulkUpdateResponse = await _personService.UpdateBulkAsync(persons);

// 条件更新
var updateByQueryResponse = await _personService.UpdateByQueryAsync(
    q => q.Query(q => q.Term(t => t.Field(f => f.Age).Value(30)),
    "person_index");

3. 删除文档

// 按ID删除
var deleteResponse = await _personService.DeleteAsync("1");

// 按实体删除
var deleteResponse = await _personService.DeleteAsync(person);

// 批量删除
var ids = persons.Select(p => new Id(p.Id)).ToList();
var bulkDeleteResponse = await _personService.DeleteBulkAsync(ids);

// 条件删除
var deleteByQueryResponse = await _personService.DeleteByQueryAsync(
    q => q.Query(q => q.Range(r => r.Field(f => f.Age).GreaterThan(30))),
    "person_index");

4. 查询文档

// 按ID查询
var person = await _personService.GetByIdAsync("1");

// 批量按ID查询
var persons = await _personService.GetByIdAsync(new List<Id> { "1", "2" });

// 判断文档是否存在
var exists = await _personService.ExistsAsync("1");

// 查询所有
var allPersons = await _personService.GetByListAsync(q => q.MatchAll());

// 条件查询
var results = await _personService.GetByListAsync(
    q => q.Bool(b => b.Must(
        m => m.Term(t => t.Field(f => f.Name).Value("张三"),
        m => m.Range(r => r.Field(f => f.Age).GreaterThan(20)
    )),
    sort: s => s.Field(f => f.Age, SortOrder.Desc),
    size: 100
);

5. 分页查询

// 简单分页
var pageResult = await _personService.GetByPageAsync(
    "张*", 
    pageIndex: 1, 
    pageSize: 10,
    fields: p => p.Name
);

// 高级分页
var advancedPageResult = await _personService.GetByPageAsync(
    q => q.Bool(b => b.Must(
        m => m.Wildcard(w => w.Field(f => f.Name).Value("张*")),
        m => m.Range(r => r.Field(f => f.Age).GreaterThan(20))
    )),
    pageIndex: 1,
    pageSize: 10,
    sort: s => s.Field(f => f.Age, SortOrder.Desc)
);

6. 滚动查询

// 获取初始scrollId
var scrollId = await _personService.SearchScrollByIdAsync(
    q => q.MatchAll(),
    size: 100,
    times: "1m"
);

// 使用scrollId获取数据
var scrollResponse = await _personService.SearchScrollAsync(scrollId, "1m");

// 清除scroll
var cleared = await _personService.ClearScrollAsync(scrollId);

7. 多条件组合查询

var results = await _personService.SearchAsync(s => s
    .Indices("person_index")
    .Query(q => q
        .Bool(b => b
            .Must(m => m.Term(t => t.Field("name").Value("张三")))
            .MustNot(m => m.Range(r => r.Field("age").LessThan(18)))
            .Should(s => s
                .Match(m => m.Field("description").Query("工程师")),
                s => s.Match(m => m.Field("description").Query("经理"))
            )
            .Filter(f => f.DateRange(r => r.Field("createTime").GreaterThan("2023-01-01")))
        )
    )
    .Sort(s => s.Field(f => f.Age, SortOrder.Desc))
    .From(0)
    .Size(10)
    .Source(src => src
        .Includes(i => i.Fields("id", "name", "age"))
        .Excludes(e => e.Field("description"))
    )
);

8. 聚合查询

var response = await _personService.SearchAsync(s => s
    .Indices("person_index")
    .Size(0)
    .Aggregations(a => a
        .Terms("age_groups", t => t
            .Field(f => f.Age)
            .Size(10)
        )
        .Average("avg_age", avg => avg
            .Field(f => f.Age)
        )
    )
);

var ageGroups = response.Aggregations.GetTerms("age_groups");
var avgAge = response.Aggregations.GetAverage("avg_age");

9. SQL查询

// 使用SQL查询
var sqlResponse = await _personService.SqlQueryAsync("SELECT * FROM person_index WHERE age > 25 LIMIT 10");

// 使用SQL参数化查询
var sqlResponse = await _personService.SqlQueryAsync(q => q
    .Query("SELECT * FROM person_index WHERE age > @age LIMIT @limit")
    .Parameters(p => p
        .Add("age", 25)
        .Add("limit", 10)
    )
);

核心组件

1. IElasticSearchContext

提供对 ElasticSearchContext 的基本操作接口。

2. BaseElasticSearchRepository

仓储层基类，实现了 IElasticSearchCRUD 接口，提供对特定实体的 CRUD 操作。

3. BaseElasticSearchService

服务层基类，封装了仓储层的操作，可以在此基础上添加业务逻辑。

版本兼容性

基于 Elastic.Clients.Elasticsearch v8.x 兼容 .NET 6.0 及以上版本 兼容 Elasticsearch 7.x 和 8.x 版本