Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation around field aliases. #31538

Merged
merged 2 commits into from
Jun 25, 2018
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've noticed that we usually don't put spaces after the comma, not sure whether it has rendering implications.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll check -- thanks.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update: I couldn't observe any rendering difference. I'll plan to keep it as-is, I think the space makes this read more clearly.


[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.

<<feature>>:: Record numeric features to boost hits at query time.

<<feature-vector>>:: Record numeric feature vectors to boost hits at query time.
Expand All @@ -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[]
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.