Elasticsearch provides a field type called “alias” which can be used for defining an additional/alternate name for a real field.

In order to define a field alias you must provide:

  • a name
  • a reference to a real field

here is an example:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "keyword"
      },
      "title_untokenized": {
        "type": "alias",
        "path": "title" 
      }
    }
  }
}

The field can be used in different contexts, in place of the target field. However, there are some restrictions to keep in mind. Let’s list them.

The path must indicate an existent, concrete field

The target field of an alias cannot be an object, an array or another field alias, including the field itself: it must be a concrete field.

In addition, it can’t be a dynamic field (i.e. a field whose name has been declared with wildcards in the dynamic_templates section) because the alias binding is done at mapping time. As a consequence of that, the target field must exist when the alias is created. The following request:

{
  "mappings": {
    "dynamic_templates": [
      {
        "dates": {
          "match": "*_date",
          "mapping": {
            "type": "date",
            "format": "dd/MM/yyyy"
          }
        }
      }
    ],
    "properties": {
      "title": {
        "type": "text"
      },
      "author": {
        "type": "text"
      },
      "headings": {
        "type": "alias",
        "path": "creation_date"
      }
    }
  }
}

will return a 400 error with the following message:

Invalid [path] value [creation_date] for field alias [headings]: an alias must refer to an existing field in the mappings

An alias can’t have multiple target fields

That means the value of the path attribute cannot be an array, only a single value. In other words, it’s not possible to have a single field that aliases multiple fields. The following request:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "author": {
        "type": "text"
      },
      "headings": {
        "type": "alias",
        "path" : ["title", "author"]
      }
    }
  }
}

will return a 400 error with the following message:

Invalid [path] value [[title, author]] for field alias [headings]: an alias must refer to an existing field in the mappings

which I could agree with you, that doesn’t really indicate the real problem. That is because the whole value of the path attribute is interpreted as a field name, and “[[title, author]]” doesn’t correspond to a field.

Target field cannot be an alias

This means that we cannot indicate an alias field in the path attribute:

"headings": {
  "type": "alias",
  "path" : "another_field_whose_type_is_alias"
}

a request like the above will return the following error:

Invalid [path] value [another_field_whose_type_is_alias] for field alias [headings]: an alias cannot refer to another alias

other than the example above, under the same rule we should mention:

  • an alias field cannot be used in the copy_to directive
  • an alias field cannot be used as a type of a multi-field

The reason is the same for both points above: the alias field doesn’t exist, it’s virtual, so it cannot be used as a destination for a value coming from another field, as it happens in multi-fields or in the copy_to directive.

The following definitions are invalid:

{
  "properties": {
    "title": {
      "type": "text",
      "copy_to": "alias_field"
    },
    "alias_field": {
      "type": "alias",
      "path": <some other field, even a concrete one>
    }
  }
}
{
  "properties": {
    "title": { 
      "type": "text",
      "fields": {
        "en": {
          "type": "text",
          "analyzer": "english"
        },
        "it": {
          "type": "alias",
          "path": <some other field, even a concrete one>
        }
      } 
    }
  }
}

(Alias) Field name containing a dot

This is actually a rule that is valid for all fields. The dot character has a special meaning in elasticsearch: it is used for defining derived fields (called multi-fields) that are created on top of a parent field definition, as in the following example:

{
  "properties": {
    "title": { 
      "type": "text",
      "fields": {
        "en": {
          "type": "text",
          "analyzer": "english"
        },
        "it": {
          "type": "text",
          "analyzer": "italian"
        }
      } 
    }
  }
}

The configuration above will create three different fields:

  • title: the parent field. It is associated with a standard analyzer
  • title.en: a derived field which will inherits the value from the parent field. The value will be processed using a symmetric (i.e. index and query time) english analyzer
  • title.it: a derived field which will inherits the value from the parent field. The value will be processed using a symmetric (i.e. index and query time) italian analyzer

So in the definition above, the value assigned to the parent field will be used also for creating the derived fields.

Can a field name contain a dot? The answer is “it depends”.

Specifically, if the part before the dot denotes another existing field, then answer is negative, because Elasticsearch will interpret it as a de-touched multi-field. The following request:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "title.en": {
        "type": "alias",
        "path": "title" 
      }
    }
  }
}

produces a 400 response with the following error message:

Can’t merge a non object mapping [title] with an object mapping [title]

However, the following requests is perfectly valid:

{
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "author.en": {
        "type": "alias",
        "path": "title"
      }
    }
  }
}

and it will create the following mappings:


    "mappings": {
      "properties": {
        "author": {
          "properties": {
            "en": {
              "type": "alias",
              "path": "title"
            }
          }
        },
        "title": {
          "type": "text"
        }
      }
    }

An alias can’t be used in input documents (i.e. indexing)

Being virtual fields, input documents (i.e. documents sent to Elasticsearch for indexing) cannot contain alias fields: they must indicate only concrete fields.

Aliases cannot be used in source filtering

Remember: alias fields are virtual, they are not part of the source document, and as a consequence of that:

Unsupported

It’s not possible to use the alias fields in some APIs such as term vectors and in some queries such as term/terms and more_like_this.


Did you find this post on “Elasticsearch Alias Field Type” useful?
Subscribe to our Newsletter and you will receive monthly news and posts about Information Retrieval.

Processing…
Success! You're on the list.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.