This article will introduce the detailed explanation of the related classes of the Easy-Es annotation package (for more detailed description, please click to view the source code annotation)

Annotation package source code: 👉 easy-es-annotation (opens new window)

@EsMapperScan (opens new window)

• Description: mapper scan annotation, the function is consistent with MP's @MapperScan

• Use location: Springboot startup class

@EsMapperScan("cn.easy-es-mapper")
public class Application{
    // omit other...
}

property	type	must specify	default value	description
value	String	is	""	full path of the package where the custom mapper is located

Tips

Since both EE and MP scan Mapper using Springboot's doScan, and the two systems are independent of each other, there is no way to isolate each other during scanning, so if your project uses both EE and MP, you need to use EE's Mapper Put it in a different package from MP's Mapper, otherwise the project will not start normally.

@IndexName (opens new window)

• Description: Annotation of the index name, which identifies the index corresponding to the entity class and corresponds to the @TableName annotation of the MP,Before v0.9.40 this annotation was @TableName.

• Where to use: Entity class

@IndexName
public class Document {
    // omit other fields
}

property	type	must specify	default value	description
value	String	No	""	Index name, which can be simply understood as MySQL table name
shardsNum	int	No	1	Number of index shards
replicasNum	int	No	1	Number of index replicas
aliasName	String	No	""	Index alias
keepGlobalPrefix	boolean	No	false	Whether to keep using the global tablePrefix value, consistent with MP usage
child	boolean	no	false	is a child document
childClass	Class	No	DefaultChildClass.class	Parent-Child Document-Child Document Class
maxResultWindow	int	No	10000	The maximum amount of data returned in a page

Dynamic index name support If your index name is not fixed, we provide two ways to modify the index name in CRUD

• Call the mapper.setCurrentActiveIndex(String indexName) method. The mapper here is your custom mapper, such as documentMapper. After modifying the index name through this API, it will take effect globally.
• Specify the index of the current operation in the corresponding parameter, such as wrapper.index(String indexName), after modifying the index name through this API, it only acts on the operation corresponding to the wrapper, with the smallest granularity.

Tips

• When you want to directly use the class name as the index name and do not need to configure the index, you can omit this annotation
• The index name specified by the annotation has the highest priority. If the annotation index is specified, the global configuration and automatic generation of the index will not take effect, and the index name specified in the annotation will be used. Priority order: Annotation Index > Global Configuration Index Prefix > Automatic Generation
• keepGlobalPrefix option, (only supported in version 0.9.4+) the default value is false, whether to keep using the global tablePrefix value:
  • This annotation option will only take effect when the global tablePrefix is ​​configured, the @TableName annotation and the value value are specified. If its value is true, the index name finally used by the framework is: global tablePrefix + the value of this annotation, for example: dev_document.
  • The usage of this annotation option is the same as in MP.
• where shardNum is the number of shards, replicasNum is the number of replicas, if not specified, the default value is 1

@IndexId (opens new window)

• Description: ES primary key annotation,Before v0.9.40 this annotation was @TableId.
• Use location: The field used as the ES primary key in the entity class corresponds to the @TableId annotation of MP

public class Document {
    @IndexId
    private String id;
    // omit other fields
}

property	type	must specify	default value	description
value	String	No	"_id"	Primary Key Field Name
type	Enum	No	IdType.NONE	Specify the primary key type

Tips

• When your field is named id and the type is String, and you do not need to use UUID and custom ID type, you can omit this annotation
• Because es has processed the default name of id (underscore+id):_id, EE has blocked this step for you, you do not need to specify it in the annotation, and the framework will automatically complete the mapping for you.
• Id generation type supports the following:
  • IdType.NONE: is automatically generated by ES and is the default configuration, no additional configuration is required. Recommended
  • IdType.UUID: System generates UUID, and then inserts into ES (not recommended)
  • IdType.CUSTOMIZE: is defined by the user, the user sets the id value by himself, if the id specified by the user does not exist in es, a new record will be added when inserting, if the id specified by the user is in If a record already exists in es, the record corresponding to the id is automatically updated.

Priority: Annotation-configured Id generation strategy > Globally configured Id generation strategy

@IndexField (opens new window)

• Description: ES field annotation, corresponding to MP's @TableField annotation,Before v0.9.40 this annotation was @TableField
• Where to use: The field in the entity class that is used as the ES index field
• Examples of usage scenarios:

1. The fields in the entity class are not the actual fields in ES. For example, the entity class is used directly as a DTO, and some irrelevant fields that do not exist in ES are added. At this time, you can mark this field so that the EE framework can skip this. field, this field is not processed.
2. The update strategy of the field, for example, when the update interface is called, the field of the entity class is not updated until it is not Null or a non-empty string. At this time, a field annotation can be added to mark the update strategy for the specified field.
3. When you need to aggregate fields of type text or keyword_tex, you can specify its fieldData=true, otherwise es will report an error.
4. Customize the name of the specified field. For example, the field is called wu-la in es, but it is called ula in the entity model. At this time, you can specify value="wu-la" in value.
5. In the automatic managed index mode, the index tokenizer and index field type can be specified.
6. In the automatic managed index mode, you can specify the format of the date in the index.
7. ...

Example of use:

public class Document {
    // Other fields are omitted here...
        
    // Scenario 1: Mark fields that do not exist in es
    @IndexField(exist = false)
    private String notExistsField;
        
    // Scenario 2: When updating, this field will only be updated if it is not an empty string
    @IndexField(strategy = FieldStrategy.NOT_EMPTY)
    private String creator;
    
    // Scenario 3: specify fieldData
    @IndexField(fieldType = FieldType.TEXT, fieldData = true)
    private String filedData;
    
    // Scenario 4: Custom field name
    @IndexField("wu-la")
    private String ula;

    // Scenario 5: Support the format type of the date field in the es index
    @IndexField(fieldType = FieldType.DATE, dateFormat = "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis")
    private String gmtCreate;

    // Scenario 6: Support the tokenizer type of the specified field in the es index
    @IndexField(fieldType = FieldType.TEXT, analyzer = Analyzer.IK_SMART, searchAnalyzer = Analyzer.IK_MAX_WORD)
    private String content;
}

property	type	must specify	default value	description
value	String	No	""	Field Name
exist	boolean	no	true	Does the field exist
fieldType	Enum	No	FieldType.NONE	The type of the field in the es index
fieldData	boolean	No	false	Whether the text type field supports aggregation
analyzer	String	No	Analyzer.NONE	The tokenizer to use when indexing documents
searchAnalyzer	String	No	Analyzer.NONE	Query tokenizer
strategy	Enum	No	FieldStrategy.DEFAULT	Field Validation Strategy
dateFormat	String	No	""	es The date format in the index, such as yyyy-MM-dd
nestedClass	Class	No	DefaultNestedClass.class	Nested Class
parentName	String	No	""	Parent-Child-Parent-Name
childName	String	No	""	Parent-Child-Child-Name
joinFieldClass	Class	No	JoinField.class	Parent-Child Document-Parent-Child Type Relationship Field Class

Tips

• There are 3 types of update strategies:
  • NOT_NULL: Non-Null judgment, when the field value is not Null, will be updated
  • NOT_EMPTY: non-empty judgment, the field value will only be updated when the field value is not an empty string
  • IGNORE: Ignore the judgment, no matter what the field value is, it will be updated

Scenario 4 and Scenario 5 only take effect in the automatic index hosting mode. If the manual index processing mode is enabled, the user needs to manually call the API provided by me to pass in the corresponding tokenizer and date formatting parameters to create/update the index .

@Score (opens new window)

• Description: Score annotation
• Where to use: Fields in entity classes that are returned as ES query scores
• Example of usage scenarios: For example, when you need to know the score of this matching query, you can add a field of type Float/float to the entity class, and add the @Score annotation to the field. In subsequent queries, if es has Return the score of the current query, then this score will be automatically mapped to this field

property	type	must specify	default value	description
decimalPlaces	int	No	0	The score retains decimal places, it is not processed by default, keep the score value returned by es

@Distance (opens new window)

• Description: Distance annotation
• Use location: The returned field in the entity class is used as the ES geographic location sort distance value
• Example of usage scenarios: For example, if you need to know the data queried by distance from near to far, how far is the actual distance from a certain coordinate, you can add a field of type Double/double to the entity class, and add @ to this field Distance annotation, in subsequent queries, if es has a return distance, this distance will be automatically mapped to this field

property	type	must specify	default value	description
decimalPlaces	int	No	0	The distance retains decimal places, it is not processed by default, and the distance value returned by es is maintained
sortBuilderIndex	int	No	0	The position of the sort field in sortBuilders, the default is 0, if there are multiple sorters, specify its position

other notes

In addition to the above high-frequency annotations, some other annotations are occasionally used in the project, such as the highlight annotation @HighLight, such as the interceptor annotation @Intercepts and other annotations, which we will introduce in detail in the specific chapters below, only listed here. A few annotations must be mastered, and other annotations can be learned as needed.