From da5554417afb2fcc66339fdabae4e23cd262e1f6 Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Fri, 15 Jun 2018 15:32:01 -0700 Subject: [PATCH 1/2] Add documentation around field aliases. --- docs/reference/indices/clearcache.asciidoc | 3 +- docs/reference/mapping.asciidoc | 6 +- docs/reference/mapping/types.asciidoc | 4 + docs/reference/mapping/types/alias.asciidoc | 101 ++++++++++++++++++++ 4 files changed, 111 insertions(+), 3 deletions(-) create mode 100644 docs/reference/mapping/types/alias.asciidoc diff --git a/docs/reference/indices/clearcache.asciidoc b/docs/reference/indices/clearcache.asciidoc index 6a7240dc9586e..6b90f9d49cba8 100644 --- a/docs/reference/indices/clearcache.asciidoc +++ b/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 diff --git a/docs/reference/mapping.asciidoc b/docs/reference/mapping.asciidoc index 6f8f1b38d6f22..31957344baf99 100644 --- a/docs/reference/mapping.asciidoc +++ b/docs/reference/mapping.asciidoc @@ -124,8 +124,10 @@ fields to an existing index with the <>. 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 <> your data into that index. +documents. Instead, you should create a new index with the correct mappings +and <> 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 <> field. [float] == Example mapping diff --git a/docs/reference/mapping/types.asciidoc b/docs/reference/mapping/types.asciidoc index 9b71d7e740495..fbd8181d0959a 100644 --- a/docs/reference/mapping/types.asciidoc +++ b/docs/reference/mapping/types.asciidoc @@ -40,6 +40,8 @@ string:: <> and <> <>:: Defines parent/child relation for documents within the same index +<>:: Defines an alias to an existing field. + <>:: Record numeric features to boost hits at query time. <>:: Record numeric feature vectors to boost hits at query time. @@ -58,6 +60,8 @@ the <>, the This is the purpose of _multi-fields_. Most datatypes support multi-fields via the <> parameter. +include::types/alias.asciidoc[] + include::types/array.asciidoc[] include::types/binary.asciidoc[] diff --git a/docs/reference/mapping/types/alias.asciidoc b/docs/reference/mapping/types/alias.asciidoc new file mode 100644 index 0000000000000..bbc1cbedf22e8 --- /dev/null +++ b/docs/reference/mapping/types/alias.asciidoc @@ -0,0 +1,101 @@ +[[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 <> requests, +and select other APIs like <>. + +[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`). + +All relevant 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. + +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 /_search +{ + "query" : { + "match_all": {} + }, + "docvalue_fields": ["route_*", "transit_mode"] +} +-------------------------------- +// CONSOLE + +[[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 + +Finally, currently only the search and field capabilities APIs will accept and resolve +field aliases. Other APIs that accept field names, such as <>, +cannot be used with field aliases. From f8f613d4ac3e07931f42f40eef9d1bc089ae2966 Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Mon, 25 Jun 2018 10:46:14 -0700 Subject: [PATCH 2/2] Address code review feedback. --- docs/reference/mapping/types/alias.asciidoc | 24 +++++++++------------ 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/reference/mapping/types/alias.asciidoc b/docs/reference/mapping/types/alias.asciidoc index bbc1cbedf22e8..42b27eaffca03 100644 --- a/docs/reference/mapping/types/alias.asciidoc +++ b/docs/reference/mapping/types/alias.asciidoc @@ -3,7 +3,7 @@ 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 <> requests, -and select other APIs like <>. +and selected other APIs like <>. [source,js] -------------------------------- @@ -43,25 +43,20 @@ GET _search <1> The path to the target field. Note that this must be the full path, including any parent objects (e.g. `object1.object2.field`). -All relevant components of the search request accept field aliases. In particular, aliases can be +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. +field values. Please see the section on <> 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 /_search -{ - "query" : { - "match_all": {} - }, - "docvalue_fields": ["route_*", "transit_mode"] -} +GET trips/_field_caps?fields=route_*,transit_mode -------------------------------- // CONSOLE +// TEST[continued] [[alias-targets]] ==== Alias targets @@ -88,13 +83,14 @@ source filtering. For example, the following request will return an empty result -------------------------------- GET /_search { - "query" : { - "match_all": {} - }, - "_source": "route_length_miles" + "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 <>,