Skip to content

Commit

Permalink
Add documentation around field aliases. (elastic#31538)
Browse files Browse the repository at this point in the history
  • Loading branch information
jtibshirani committed Jul 24, 2018
1 parent 01b4918 commit ebc37fd
Show file tree
Hide file tree
Showing 4 changed files with 107 additions and 3 deletions.
3 changes: 2 additions & 1 deletion docs/reference/indices/clearcache.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 4 additions & 2 deletions docs/reference/mapping.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -120,8 +120,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
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/mapping/types.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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.

[float]
=== Multi-fields

Expand All @@ -54,6 +56,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[]
Expand Down
97 changes: 97 additions & 0 deletions docs/reference/mapping/types/alias.asciidoc
Original file line number Diff line number Diff line change
@@ -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.

0 comments on commit ebc37fd

Please sign in to comment.