HMENetCore.Elasticsearch 8.1.17

HMENetCore.Elasticsearch 8.0

简介

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

功能特性

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

.NET支持

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

安装

dotnet add package HMENetCore.Elasticsearch 

配置数据库连接

添加配置到 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 8.x 和 9.x 版本