Where do I put the mapping files for Elasticsearch?

Question

I am confused by the ES docs, in fact here they state the the indexes must go in the mapping dir (and indexname sub dirs):

Mappings can be defined within files called [mapping_name].json and be placed either under config/mappings/_default location, or under config/mappings/[index_name] (for mappings that should be associated only with a specific index).

But then here in the "config" section, it states:

Index templates can also be placed within the config location (path.conf) under the templates directory (note, make sure to place them on all master eligible nodes). For example, a file called template_1.json can be placed under config/templates and it will be added if it matches an index.

I put my mapping in /config/mappings/myindexname/mappinfile.json and it is like:

{
    "template": "maincontentindex",
    "settings": {
        "index": {
            "analysis": {
                "analyzer": {
                    "htmlStrippingAnalyzer": {
                        "tokenizer": "standard",
                        "filter": ["standard", "lowercase"],
                        "char_filter": "html_strip"
                    }
                }
            }
        }
    },

    "mappings": {
        "rendition": {
            "_timestamp": {
                "enabled": true,
                "store" : true
            },
            "properties": {
                "key": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "parentPage": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "type": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "language": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "device": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "territory": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "channel": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "template": {
                    "type": "string",
                    "store": "yes",
                    "analyzer": "keyword"
                },
                "meta": {
                    "properties": {
                        "content": {
                            "type": "string",
                            "store": "yes"
                        }
                    }
                }       
            }
        }
    }
}

if I use the REST Api to put it in the server it works fine and if I call /maincontentindex/rendition/_mapping I just get the above structure (even with no data).

But with the directory I just get a 404 and if I insert anything it's just the usual dynamic mapping.

Ftr: (at least) [as of ES 5.1](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-conf-mappings.html) "It is no longer possible to specify mappings in files in the config directory. Instead, mappings should be created using the API". I strongly assume the same goes for templates. — dtk, Dec 15 '16 at 13:11

score 31 · Accepted Answer · answered Sep 17 '13 at 17:10

There is a difference between mappings and templates.

Mappings contain your fields and how you want to index/store them in elasticsearch. They refer to a specific index and type (or multiple types in the same index when using the _default_ special type). You can submit mappings either while creating an index through the create index api, or through the put mapping api to modify the mappings for an existing index.

Index templates are a way to automatically apply mappings and index settings to indices that are going to be created in the future, whose names match a specified pattern. Let's say that mappings are a part of an index template. An index template can contains mappings for multiple types and index settings too.

If you have an index template, you can put it under templates as mentioned in the reference. If you have a mapping for a type, you need to put it under the mappings directory.

The json that you pasted into the question is an index template, which needs to go under the templates folder, not under the mappings one. What you get back using the get mapping api as described is not the template itself as you said but the current mapping for the index/type that you specified in the url (only the mappings part of your template).

Also, I would suggest you to use the REST api that elasticsearch provides. Using files on file system doesn't really look like the elasticsearch way of doing things.

while I was waiting for the answer I worked that out alread :) only one thing doesn't work... when writing a mapping, where do I put the settings section? — gotch4, Sep 17 '13 at 21:03
Settings don't fit in the mappings :) You have to use the update settings api separately. I'm not aware of a place where you can put the index settings on file system. I would then use index templates which can contain both mappings and settings. — javanna, Sep 18 '13 at 11:27
Why is using files discouraged ? having configuration files is way easier for automated deployment and version control, also easy to read off the current configuration by opening a file in a text editor. I'm always wondering how many people do with only rest APIs with elasticsearch. When deploying a new cluster with known configuration, how do you use REST API to set your configuration ? — MohamedEzz, Jun 07 '16 at 16:57

Where do I put the mapping files for Elasticsearch?

1 Answers1

Linked