Add documentation around field aliases. (#31538)

docs/reference/indices/clearcache.asciidoc

@@ -16,7 +16,8 @@ explicitly by setting `query`, `fielddata` or `request`.
 
 All caches relating to a specific field(s) can also be cleared by
 specifying `fields` parameter with a comma delimited list of the
-relevant fields.
+relevant fields. Note that the provided names must refer to concrete
+fields -- objects and field aliases are not supported.
 
 [float]
 === Multi Index

docs/reference/mapping.asciidoc

@@ -124,8 +124,10 @@ fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
 
 Other than where documented, *existing field mappings cannot be
 updated*. Changing the mapping would mean invalidating already indexed
-documents.  Instead, you should create a new index with the correct mappings
-and <<docs-reindex,reindex>> your data into that index.
+documents. Instead, you should create a new index with the correct mappings
+and <<docs-reindex,reindex>> your data into that index. If you only wish
+to rename a field and not change its mappings, it may make sense to introduce
+an <<alias, `alias`>> field.
 
 [float]
 == Example mapping

docs/reference/mapping/types.asciidoc

@@ -40,6 +40,8 @@ string::        <<text,`text`>> and <<keyword,`keyword`>>
 
 <<parent-join>>::   Defines parent/child relation for documents within the same index
 
+<<alias>>::         Defines an alias to an existing field.
+
 <<feature>>::       Record numeric features to boost hits at query time.
 
 <<feature-vector>>:: Record numeric feature vectors to boost hits at query time.
@@ -58,6 +60,8 @@ the <<analysis-standard-analyzer,`standard` analyzer>>, the
 This is the purpose of _multi-fields_.  Most datatypes support multi-fields
 via the <<multi-fields>> parameter.
 
+include::types/alias.asciidoc[]
+
 include::types/array.asciidoc[]
 
 include::types/binary.asciidoc[]

docs/reference/mapping/types/alias.asciidoc

@@ -0,0 +1,97 @@
+[[alias]]
+=== Alias datatype
+
+An `alias` mapping defines an alternate name for a field in the  index.
+The alias can be used in place of the target field in <<search, search>> requests,
+and selected other APIs like <<search-field-caps, field capabilities>>.
+
+[source,js]
+--------------------------------
+PUT trips
+{
+  "mappings": {
+    "_doc": {
+      "properties": {
+        "distance": {
+          "type": "long"
+        },
+        "route_length_miles": {
+          "type": "alias",
+          "path": "distance" // <1>
+        },
+        "transit_mode": {
+          "type": "keyword"
+        }
+      }
+    }
+  }
+}
+
+GET _search
+{
+  "query": {
+    "range" : {
+      "route_length_miles" : {
+        "gte" : 39
+      }
+    }
+  }
+}
+--------------------------------
+// CONSOLE
+
+<1> The path to the target field. Note that this must be the full path, including any parent
+objects (e.g. `object1.object2.field`).
+
+Almost all components of the search request accept field aliases. In particular, aliases can be
+used in queries, aggregations, and sort fields, as well as when requesting `docvalue_fields`,
+`stored_fields`, suggestions, and highlights. Scripts also support aliases when accessing
+field values. Please see the section on <<unsupported-apis, unsupported APIs>> for exceptions.
+
+In some parts of the search request and when requesting field capabilities, field wildcard patterns can be
+provided. In these cases, the wildcard pattern will match field aliases in addition to concrete fields:
+
+[source,js]
+--------------------------------
+GET trips/_field_caps?fields=route_*,transit_mode
+--------------------------------
+// CONSOLE
+// TEST[continued]
+
+[[alias-targets]]
+==== Alias targets
+
+There are a few restrictions on the target of an alias:
+
+  * The target must be a concrete field, and not an object or another field alias.
+  * The target field must exist at the time the alias is created.
+  * If nested objects are defined, a field alias must have the same nested scope as its target.
+
+Additionally, a field alias can only have one target. This means that it is not possible to use a
+field alias to query over multiple target fields in a single clause.
+
+[[unsupported-apis]]
+==== Unsupported APIs
+
+Writes to field aliases are not supported: attempting to use an alias in an index or update request
+will result in a failure.
+
+Because alias names are not present in the document source, aliases cannot be used when performing
+source filtering. For example, the following request will return an empty result for `_source`:
+
+[source,js]
+--------------------------------
+GET /_search
+{
+  "query" : {
+    "match_all": {}
+  },
+  "_source": "route_length_miles"
+}
+--------------------------------
+// CONSOLE
+// TEST[continued]
+
+Finally, currently only the search and field capabilities APIs will accept and resolve
+field aliases. Other APIs that accept field names, such as <<docs-termvectors, term vectors>>,
+cannot be used with field aliases.