Index name, type name and field name rules

I am using ES 6. What are exact rules regarding formation of index name, type name and field name strings.. I know ES only takes lower case.. Does it apply to field names too?

Is this documented officially somewhere? I couldnt find it anywhere


I'm not actually sure it's documented anywhere... still looking myself. I'll open a PR to add them to the docs if I don't find anything.

The rules for index names are encoded in MetaDataCreateIndexService. Essentially:

  • Lowercase only
  • Cannot include \, /, *, ?, ", <, >, |, space (the character, not the word), ,, #
  • Indices prior to 7.0 could contain a colon (:), but that's been deprecated and won't be supported in 7.0+
  • Cannot start with -, _, +
  • Cannot be . or ..
  • Cannot be longer than 255 characters

Many of these naming restrictions were put in place when Elasticsearch used the index name as the directory name to store data on disk, so the names had to be conservative to play nicely with different file systems (that's why there are restrictions with not allowing .. as a name, etc).

I suspect these might loosen up in the future, since we've moved to associating indices with a UUID which is used on-disk now, instead of the index name.

I believe the only restriction on field names is that it can't be entirely whitespace. Periods are allowed, but they are short-hand for objects. E.g.

"": "abc"

is equivalent to:

"foo": {
  "bar": {
    "baz": "abc"

Which has the knock-on effect that "object paths" have to be valid. So is not allowed because it doesn't resolve to a valid path. Similarly:

"foo.": {
  "bar": {
    "baz": "abc"

isn't allowed for the same reason (the trailing period on foo. makes it ambiguous).

I'll see what I can do about the docs :slight_smile:


Also note: both index names and field names support full unicode, so you technically can have :poop: as a field name... but it's not encouraged because it can lead to a lot of subtle irritations (accents vs unaccented characters, etc). Plain ASCII is the easiest unless there's a compelling reason otherwise :slight_smile:

Just merged in some documentation improvements, sorry for the confusion!

This topic was automatically closed 28 days after the last reply. New replies are no longer allowed.