What's the use of a mapping annotation and do I need it?(Spring Data ElasticSearch)

Question

I am working with ElasticSearch using Spring Data ElasticSearch 3.1.0.RELEASE and I am fairly new to ElasticSearch itself, knowing not too much about it.

Here(spring-data-elastic docs) I see that the mappings(schema) for the documents are auto-generated using metadata(annotations) very much the same way as in the Spring Data MongoDB in a dynamic way, but in our organization, all entities are annotated with @Mapping annotation and refer to the JSON documents, which reflect their structure, so for each document entity - JSON file is written although all entities have respective annotations.

A small snippet of a sample class to give a hint what am I talking about

@Document(indexName = "sampleIndex", type = "sample", shards = 16, createIndex = false)
@Mapping(mappingPath = "/elasticsearch/mappings/sample.json")
public final class Sample {

    @Id
    private String id;

    @Field(type = FieldType.Long)
    private long sampleId;

    @Field(type = FieldType.Keyword)
    private SampleObject sampleObject;

    @Field(type = FieldType.Nested)
    private Map<String, String> data;

And the respective /elasticsearch/mappings/sample.json file

{
    "samples": {
        "mappings": {
            "sample": {
                "properties": {
                    "sampleId": {
                        "type": "long"
                    },
                    "sampleObject": {
                        "type": "string"
                    },
                    "data": {
                        "type": "nested"
                    },
....

Approximately, I can understand the whole idea behind this annotation though I don't even see any mentions of it in the (spring-data-elastic docs) and I don't see any meaningful JavaDocs.

Regardless, I still can't get how does this annotation work, what are the use cases and why is it needed, from my point of view I would just remove it completely because the schemas can be auto-generated based on the other annotations by Spring. Or am I wrong?

_{Additional points related to the question: I am not sure about this either: does this mapping JSON file override the structure defined in the entity by annotations?}

Answer 1

The ElasticsearchOperations interface has a method putMapping(class<?>). This method can be used to write the index mappings to an index. The default non-reactive repository implementations do this when an index is created.

The default method implementation checks if there is a @Mapping annotation on the class. If yes, this mapping definitions are used. If this annotation is not present, then the class is inspected and checked for the @Field annotation on the properties.

So in your case, the annotations on the properties are not used for writing the index mappings.

I would recommend to use the properties on the class, because it's more likely that you change some mapping property in the class and forget it in the json file.

For example in your code in the class sampleObject is defined as keyword but int the mappings it's a String. Somebody looking just at the code might miss the different definition.