From 19e33d52c54c601cb9ac0e671737b5367a3e4b06 Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Wed, 6 Feb 2019 18:00:56 -0800 Subject: [PATCH] Update 'removal of types' docs to reflect the new plan. (#38548) Backport of #38003. --- .../mapping/removal_of_types.asciidoc | 126 +++++++++++++++--- 1 file changed, 109 insertions(+), 17 deletions(-) diff --git a/docs/reference/mapping/removal_of_types.asciidoc b/docs/reference/mapping/removal_of_types.asciidoc index 67ef215931b48..03982bac802c2 100644 --- a/docs/reference/mapping/removal_of_types.asciidoc +++ b/docs/reference/mapping/removal_of_types.asciidoc @@ -4,7 +4,8 @@ IMPORTANT: Indices created in Elasticsearch 6.0.0 or later may only contain a single <>. Indices created in 5.x with multiple mapping types will continue to function as before in Elasticsearch 6.x. -Mapping types will be completely removed in Elasticsearch 7.0.0. +Types will be deprecated in APIs in Elasticsearch 7.0.0, and completely +removed in 8.0.0. [float] === What are mapping types? @@ -256,30 +257,28 @@ Elasticsearch 6.x:: * The `_default_` mapping type is deprecated. +* In 6.7, the index creation, index template, and mapping APIs support a query + string parameter (`include_type_name`) which indicates whether requests and + responses should include a type name. It defaults to `true`, and not setting + `include_type_name=false` will result in a deprecation warning. Indices which + don't have an explicit type will use the dummy type name `_doc`. + Elasticsearch 7.x:: -* The `type` parameter in URLs are deprecated. For instance, indexing - a document no longer requires a document `type`. The new index APIs +* Specifying types in requests is deprecated. For instance, indexing a + document no longer requires a document `type`. The new index APIs are `PUT {index}/_doc/{id}` in case of explicit ids and `POST {index}/_doc` for auto-generated ids. -* The index creation, `GET|PUT _mapping` and document APIs support a query - string parameter (`include_type_name`) which indicates whether requests and - responses should include a type name. It defaults to `true`. - 7.x indices which don't have an explicit type will use the dummy type name - `_doc`. Not setting `include_type_name=false` will result in a deprecation - warning. +* The `include_type_name` parameter in the index creation, index template, + and mapping APIs will default to `false`. Setting the parameter will result + in a deprecation warning. * The `_default_` mapping type is removed. Elasticsearch 8.x:: -* The `type` parameter is no longer supported in URLs. - -* The `include_type_name` parameter is deprecated, default to `false` and fails - the request when set to `true`. - -Elasticsearch 9.x:: +* Specifying types in requests is no longer supported. * The `include_type_name` parameter is removed. @@ -425,7 +424,87 @@ POST _reindex // NOTCONSOLE [float] -=== Index templates +=== Typeless APIs in 7.0 + +In Elasticsearch 7.0, each API will support typeless requests, +and specifying a type will produce a deprecation warning. Certain +typeless APIs are also available in 6.7, to enable a smooth upgrade +path to 7.0. + +[float] +==== Indices APIs + +Index creation, index template, and mapping APIs support a new `include_type_name` +url parameter that specifies whether mapping definitions in requests and responses +should contain the type name. The parameter defaults to `true` in version 6.7 to +match the pre-7.0 behavior of using type names in mappings. It defaults to `false` +in version 7.0 and will be removed in version 8.0. + +See some examples of interactions with Elasticsearch with this option provided: + +[source,js] +-------------------------------------------------- +PUT index?include_type_name=false +{ + "mappings": { + "properties": { <1> + "foo": { + "type": "keyword" + } + } + } +} +-------------------------------------------------- +// CONSOLE +<1> Mappings are included directly under the `mappings` key, without a type name. + +[source,js] +-------------------------------------------------- +PUT index/_mappings?include_type_name=false +{ + "properties": { <1> + "bar": { + "type": "text" + } + } +} +-------------------------------------------------- +// CONSOLE +// TEST[continued] +<1> Mappings are included directly under the `mappings` key, without a type name. + +[source,js] +-------------------------------------------------- +GET index/_mappings?include_type_name=false +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +The above call returns + +[source,js] +-------------------------------------------------- +{ + "index": { + "mappings": { + "properties": { <1> + "foo": { + "type": "keyword" + }, + "bar": { + "type": "text" + } + } + } + } +} +-------------------------------------------------- +// CONSOLE +// TESTRESPONSE +<1> Mappings are included directly under the `mappings` key, without a type name. + +[float] +==== Index templates It is recommended to make index templates typeless before upgrading to 7.0 by re-adding them with `include_type_name` set to `false`. @@ -495,5 +574,18 @@ PUT index-2-01?include_type_name=false In case of implicit index creation, because of documents that get indexed in an index that doesn't exist yet, the template is always honored. This is -usually not a problem due to the fact that typless index calls work on typed +usually not a problem due to the fact that typeless index calls work on typed indices. + +[float] +==== Mixed-version clusters + +In a cluster composed of both 6.7 and 7.0 nodes, the parameter +`include_type_name` should be specified in indices APIs like index +creation. This is because the parameter has a different default between +6.7 and 7.0, so the same mapping definition will not be valid for both +node versions. + +Typeless document APIs such as `bulk` and `update` are only available as of +7.0, and will not work with 6.7 nodes. This also holds true for the typeless +versions of queries that perform document lookups, such as `terms`.