Dots in field names

edit

In Elasticsearch 5.0, dots are permitted in field names and each step in the path is interpreted as an object field, except for the last step. For instance, indexing the following document in Elasticsearch 5.0:

{
  "server.latency.max": 100
}

would result in the following mapping:

{
  "properties": {
    "server": {
      "type": "object",
      "properties": {
        "latency": {
          "type": "object",
          "properties": {
            "max": {
              "type": "long"
            }
          }
        }
      }
    }
  }
}

Elasticsearch 2.x does not support this dots-to-object transformation and so dots in field names are not allowed in versions 2.0 - 2.3.

Enabling support for dots in field names

edit

Elasticsearch 2.4.0 adds a system property called mapper.allow_dots_in_name which will disable the check for dots in field names. You can enable this system property as follows:

export ES_JAVA_OPTS="-Dmapper.allow_dots_in_name=true"
./bin/elasticsearch

(ES_JAVA_OPTS can be set in the /etc/default/elasticsearch file if you’re using the Debian package, or in the /etc/sysconfig/elasticsearch file if you’re using the RPM.)

With this sytem property enabled, indexing the document above in 2.4.0 will result in the following mapping:

{
  "properties": {
    "server.latency.max": {
      "type": "long"
    }
  }
}

Upgrading fields with dots to 5.x

edit

Indices created in 1.x must be reindexed in 2.4 before being upgraded to 5.x, regardless of whether they have fields with dots or not. Alternatively, indices from a 1.x cluster can be imported directly into a 5.x cluster using reindex-from-remote.

Indices created in 2.4 can be upgraded to 5.x directly, as long as there are no conflicts (see below). If there are dots in field names, the mapping will be automatically updated to the object-style mapping shown in Dots in field names.

Dots can create conflicting fields

Indices containing fields that would produce conflicts when upgrading to the object-style mapping cannot be upgraded to 5.x. For instance, the following mapping can be upgraded:

{
  "properties": {
    "server.latency": {
      "type": "long"
    },
    "server.name": {
      "type": "string"
    }
  }
}

The server field will become an object field in both cases.

This mapping cannot be upgraded:

{
  "properties": {
    "server.latency": {
      "type": "long"
    },
    "server": {
      "type": "string"
    }
  }
}

The server field is an object in server.latency, but a string in server. This is a conflict and will prevent the index from being opened in 5.x.