你好呀，我的老朋友！我是老寇，欢迎来到老寇IoT云平台！

本文档旨在总结 org.laokou.common.elasticsearch.annotation 包下的所有 Elasticsearch 相关注解，提供详细的说明、介绍、配置和使用示例。

1. @Index

说明

@Index 注解用于标记一个类，表示该类对应一个 Elasticsearch 索引。它允许配置索引的分析器和设置。

介绍

当您需要将一个 Java 对象映射到 Elasticsearch 中的一个索引时，可以使用此注解。它提供了对索引级别设置和分析器配置的入口。

配置

属性	类型	默认值	说明
analysis	Analysis	@Analysis	配置索引的分析器。
setting	Setting	@Setting	配置索引的设置，如分片、副本和刷新间隔。

例子

@Index(analysis = @Analysis(analyzers = {
    @Analyzer(name = "ik_smart", args = @Args(filter = "stop", tokenizer = "ik_smart"))
}), setting = @Setting(shards = 3, replicas = 1, refreshInterval = "30s"))
public class MyDocument {
    // ... 字段
}

@Index(setting = @Setting(refreshInterval = "-1"),
		analysis = @Analysis(
				filters = { @Filter(name = "pinyin_filter",
						options = { @Option(key = "type", value = "pinyin"),
								@Option(key = "keep_full_pinyin", value = "false"),
								@Option(key = "keep_joined_full_pinyin", value = "true"),
								@Option(key = "keep_original", value = "true"),
								@Option(key = "limit_first_letter_length", value = "16"),
								@Option(key = "remove_duplicated_term", value = "true"),
								@Option(key = "none_chinese_pinyin_tokenize", value = "false") }) },
				analyzers = { @Analyzer(name = "ik_pinyin",
						args = @Args(filter = "pinyin_filter", tokenizer = "ik_max_word")) }))
@Data
public class Test1 implements Serializable {

	@JsonSerialize(using = ToStringSerializer.class)
	@Field(type = Type.LONG)
	private Long id;

	@Field(type = Type.TEXT, searchAnalyzer = "ik_smart", analyzer = "ik_pinyin", index = true, subField = @SubField(ignoreAbove = 256))
	private String name;

}

2. @Analysis

说明

@Analysis 注解用于定义 Elasticsearch 索引的分析器和过滤器。

介绍

Elasticsearch 的文本分析是其核心功能之一。@Analysis 允许您在索引级别定义自定义的分析器和过滤器，以满足特定的文本处理需求，例如分词、词干提取、停用词过滤等。

配置

属性	类型	默认值	说明
filters	Filter[]	{}	定义用于文本分析的过滤器数组。
analyzers	Analyzer[]	{}	定义用于文本分析的分析器数组。

例子

@Analysis(
    filters = {
        @Filter(name = "my_stop_filter", options = {
            @Option(key = "type", value = "stop"),
            @Option(key = "stopwords", value = "_chinese_")
        })
    },
    analyzers = {
        @Analyzer(name = "my_custom_analyzer", args = @Args(filter = "my_stop_filter", tokenizer = "ik_max_word"))
    }
)
public @interface MyAnalysisConfig {}

3. @Analyzer

说明

@Analyzer 注解用于定义一个具体的分析器。

介绍

分析器是 Elasticsearch 中用于处理文本的组件，它由一个分词器（tokenizer）和零个或多个过滤器（filter）组成。此注解允许您指定分析器的名称以及其使用的过滤器和分词器。

配置

属性	类型	默认值	说明
name	String		分析器的名称。
args	Args		分析器使用的过滤器和分词器参数。

例子

@Analyzer(name = "ik_smart_analyzer", args = @Args(filter = "stop", tokenizer = "ik_smart"))
public @interface MyAnalyzer {}

4. @Args

说明

@Args 注解用于为 @Analyzer 提供参数，指定分析器使用的过滤器和分词器。

介绍

这是 @Analyzer 注解的辅助注解，用于封装分析器所需的具体配置，例如指定分词器类型和过滤器链。

配置

属性	类型	默认值	说明
filter	String		过滤器名称。
tokenizer	String		分词器名称。

例子

@Args(filter = "standard", tokenizer = "whitespace")
public @interface MyArgs {}

5. @Constants

说明

Constants 类定义了 Elasticsearch 搜索结果高亮显示的前缀和后缀标签。

介绍

这是一个工具类，提供了在 Elasticsearch 搜索结果中用于高亮显示匹配文本的常量。通常用于前端展示。

配置

无。

例子

// 在代码中使用
String preTags = Constants.PRE_TAGS; // "<font color='red'>"
String postTags = Constants.POST_TAGS; // "</font>"

6. @Document (Record)

说明

Document 是一个 Java Record，用于在运行时表示 Elasticsearch 索引的结构和配置。

介绍

这个 Record 提供了在代码中构建 Elasticsearch 索引定义（包括映射、设置和分析）的结构化方式。它不是一个注解，而是一个数据传输对象，用于程序化地创建或更新索引。

配置

属性	类型	说明
name	String	索引名称。
alias	String	索引别名。
mappings	List<Mapping>	字段映射列表。
setting	Setting	索引设置。
analysis	Analysis	索引分析器配置。

Document.Mapping Record

属性	类型	说明
field	String	字段名称。
type	Type	字段类型。
searchAnalyzer	String	搜索时使用的分析器。
analyzer	String	索引时使用的分析器。
eagerGlobalOrdinals	boolean	是否启用 eager global ordinals。
format	String	日期格式。
index	boolean	是否索引该字段。
subField	SubField	子字段配置。

Document.SubField Record

属性	类型	说明
ignoreAbove	Integer	忽略高于此长度的字符串。

Document.Setting Record

属性	类型	说明
shards	short	分片数量。
replicas	short	副本数量。
refreshInterval	String	刷新间隔。

Document.Analysis Record

属性	类型	说明
filters	List<Filter>	过滤器列表。
analyzers	List<Analyzer>	分析器列表。

Document.Filter Record

属性	类型	说明
name	String	过滤器名称。
options	List<Option>	过滤器选项。

Document.Args Record

属性	类型	说明
filter	String	过滤器名称。
tokenizer	String	分词器名称。

Document.Option Record

属性	类型	说明
key	String	选项键。
value	String	选项值。

Document.Analyzer Record

属性	类型	说明
name	String	分析器名称。
args	Args	分析器参数。

例子

// 示例：构建一个 Document 对象
Document myDoc = new Document(
    "my_index",
    "my_alias",
    List.of(
        new Document.Mapping("title", Type.TEXT, "ik_smart", "ik_smart", false, "", true, new Document.SubField(256)),
        new Document.Mapping("description", Type.KEYWORD, "", "", false, "", true, new Document.SubField(256))
    ),
    new Document.Setting((short) 1, (short) 1, "1s"),
    new Document.Analysis(
        List.of(new Document.Filter("stop_filter", List.of(new Document.Option("type", "stop")))),
        List.of(new Document.Analyzer("custom_analyzer", new Document.Args("stop_filter", "standard")))
    )
);

7. @Field

说明

@Field 注解用于标记一个类的字段，表示该字段对应 Elasticsearch 索引中的一个文档字段。

介绍

此注解允许您在 Java 对象的字段上直接定义其在 Elasticsearch 中的映射属性，例如字段类型、分析器、是否索引等。

配置

属性	类型	默认值	说明
value	String	""	字段名称，默认为 Java 字段名。
type	Type		字段类型。
searchAnalyzer	String	""	搜索时使用的分析器。
analyzer	String	""	索引时使用的分析器。
eagerGlobalOrdinals	boolean	false	是否启用 eager global ordinals。
format	String	""	日期格式。
index	boolean	false	是否索引该字段。
subField	SubField	@SubField(ignoreAbove = 256)	子字段配置。

例子

public class Product {
    @Field(type = Type.KEYWORD)
    private String id;

    @Field(type = Type.TEXT, analyzer = "ik_smart", searchAnalyzer = "ik_smart")
    private String name;

    @Field(type = Type.DATE, format = "yyyy-MM-dd HH:mm:ss")
    private Date createTime;
}

8. @Filter

说明

@Filter 注解用于定义一个 Elasticsearch 过滤器。

介绍

过滤器是分析器的一部分，用于对分词后的词元进行进一步处理，例如转换为小写、移除停用词、同义词处理等。

配置

属性	类型	默认值	说明
name	String		过滤器的名称。
options	Option[]		过滤器的选项。

例子

@Filter(name = "lowercase_filter", options = {
    @Option(key = "type", value = "lowercase")
})
public @interface MyFilter {}

9. @Option

说明

@Option 注解用于为 @Filter 或其他配置提供键值对选项。

介绍

这是一个通用的辅助注解，用于为 Elasticsearch 的各种配置提供灵活的键值对参数。

配置

属性	类型	默认值	说明
key	String		选项的键。
value	String		选项的值。

例子

@Option(key = "stopwords", value = "a,an,the")
public @interface MyOption {}

10. @Setting

说明

@Setting 注解用于定义 Elasticsearch 索引的设置。

介绍

此注解允许您配置索引级别的参数，例如分片数量、副本数量和刷新间隔，这些参数会影响索引的性能和可用性。

配置

属性	类型	默认值	说明
shards	short	1	索引的主分片数量。
replicas	short	1	每个主分片的副本数量。
refreshInterval	String	"1s"	索引刷新间隔，例如 "1s", "-1" (禁用)。

例子

@Setting(shards = 5, replicas = 2, refreshInterval = "5s")
public @interface MySetting {}

11. @SubField

说明

@SubField 注解用于配置 Elasticsearch 字段的子字段属性。

介绍

子字段允许您以不同的方式索引同一个字段。例如，一个 text 字段可以有一个 keyword 类型的子字段，用于精确匹配和聚合。此注解主要用于配置 keyword 子字段的 ignore_above 属性。

配置

属性	类型	默认值	说明
ignoreAbove	int		忽略长度超过此值的字符串。

例子

@Field(type = Type.TEXT, subField = @SubField(ignoreAbove = 100))
private String longText;

12. Type (Enum)

说明

Type 枚举定义了 Elasticsearch 支持的各种字段类型。

介绍

此枚举提供了在 @Field 注解中指定字段类型的选项，并包含了将这些类型映射到 Elasticsearch 客户端 API 的逻辑。

配置

枚举值	说明
AUTO	自动检测字段类型。
TEXT	文本字段，用于全文搜索。
KEYWORD	关键词字段，用于精确匹配和聚合。
LONG	长整型。
INTEGER	整型。
SHORT	短整型。
BYTE	字节型。
DOUBLE	双精度浮点型。
FLOAT	浮点型。
DATE	日期类型。
BOOLEAN	布尔型。
BINARY	二进制类型。
INTEGER_RANGE	整型范围。
FLOAT_RANGE	浮点型范围。
LONG_RANGE	长整型范围。
DOUBLE_RANGE	双精度浮点型范围。
DATE_RANGE	日期范围。
OBJECT	对象类型。
IP	IP 地址类型。

例子

@Field(type = Type.TEXT)
private String title;

@Field(type = Type.KEYWORD)
private String category;

@Field(type = Type.LONG)
private Long views;

我是老寇，我们下次再见啦！