From 91b79ebed41b489eb6844ef574160bb0d07675d6 Mon Sep 17 00:00:00 2001 From: Julie Tibshirani Date: Thu, 31 Jan 2019 10:26:24 -0800 Subject: [PATCH] Update 'removal of types' docs to reflect the new plan. (#38003) --- .../mapping/removal_of_types.asciidoc | 198 ++++++++++++++---- 1 file changed, 152 insertions(+), 46 deletions(-) diff --git a/docs/reference/mapping/removal_of_types.asciidoc b/docs/reference/mapping/removal_of_types.asciidoc index 5b7138ffa3f..db8b3a3d17c 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? @@ -161,12 +162,12 @@ You can achieve the same thing by adding a custom `type` field as follows: [source,js] ---- -PUT twitter?include_type_name=true <1> +PUT twitter { "mappings": { "_doc": { "properties": { - "type": { "type": "keyword" }, <2> + "type": { "type": "keyword" }, <1> "name": { "type": "text" }, "user_name": { "type": "keyword" }, "email": { "type": "keyword" }, @@ -204,7 +205,7 @@ GET twitter/_search }, "filter": { "match": { - "type": "tweet" <2> + "type": "tweet" <1> } } } @@ -212,9 +213,7 @@ GET twitter/_search } ---- // NOTCONSOLE -<1> Use `include_type_name=true` in case need to use the "old" syntax including the "_doc" object like -in this example -<2> The explicit `type` field takes the place of the implicit `_type` field. +<1> The explicit `type` field takes the place of the implicit `_type` field. [float] ==== Parent/Child without mapping types @@ -258,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. @@ -427,17 +424,26 @@ POST _reindex // NOTCONSOLE [float] -=== Use `include_type_name=false` to prepare for upgrade to 8.0 +=== Typeless APIs in 7.0 -Index creation and mapping APIs support a new `include_type_name` url parameter -starting with version 6.7. It will default to `true` in version 6.7, default to -`false` in version 7.0 and will be removed in version 8.0. When set to `true`, -this parameter enables the pre-7.0 behavior of using type names in the API. +In Elasticsearch 7.0, each API will support typeless requests, +and specifying a type will produce a deprecation warning. -See some examples of interactions with Elasticsearch with this option turned off: +NOTE: Typeless APIs work even if the target index contains a custom type. +For example, if an index has the the custom type name `my_type`, we can add +documents to it using typeless `index` calls, and load documents with typeless +`get` calls. [float] -==== Index creation +==== 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] -------------------------------------------------- @@ -455,27 +461,27 @@ PUT index?include_type_name=false // CONSOLE <1> Mappings are included directly under the `mappings` key, without a type name. -[float] -==== PUT and GET mappings - [source,js] -------------------------------------------------- -PUT index - PUT index/_mappings?include_type_name=false { "properties": { <1> - "foo": { - "type": "keyword" + "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 -<1> Mappings are included directly under the `mappings` key, without a type name. - +// TEST[continued] The above call returns @@ -487,6 +493,9 @@ The above call returns "properties": { <1> "foo": { "type": "keyword" + }, + "bar": { + "type": "text" } } } @@ -499,14 +508,14 @@ The above call returns [float] ==== Document APIs -Index APIs must be called with the `{index}/_doc` path for automatic generation of -the `_id` and `{index}/_doc/{id}` with explicit ids. +In 7.0, index APIs must be called with the `{index}/_doc` path for automatic +generation of the `_id` and `{index}/_doc/{id}` with explicit ids. [source,js] -------------------------------------------------- PUT index/_doc/1 { - "foo": "bar" + "foo": "baz" } -------------------------------------------------- // CONSOLE @@ -514,7 +523,7 @@ PUT index/_doc/1 [source,js] -------------------------------------------------- { - "_index": "index", <1> + "_index": "index", "_id": "1", "_type": "_doc", "_version": 1, @@ -529,14 +538,98 @@ PUT index/_doc/1 } -------------------------------------------------- // TESTRESPONSE -<1> The response does not include a `_type`. -The <>, <>, <> and <> APIs -will continue to return a `_type` key in the response in 7.0, but it is considered deprecated and will be -removed in 8.0. +Similarly, the `get` and `delete` APIs use the path `{index}/_doc/{id}`: + +[source,js] +-------------------------------------------------- +GET index/_doc/1 +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +For API paths that contain both a type and endpoint name like `_update`, +in 7.0 the endpoint will immediately follow the index name: + +[source,js] +-------------------------------------------------- +POST index/_update/1 +{ + "doc" : { + "foo" : "qux" + } +} + +GET /index/_source/1 +-------------------------------------------------- +// CONSOLE +// TEST[continued] + +Types should also no longer appear in the body of requests. The following +example of bulk indexing omits the type both in the URL, and in the individual +bulk commands: + +[source,js] +-------------------------------------------------- +POST _bulk +{ "index" : { "_index" : "index", "_id" : "3" } } +{ "foo" : "baz" } +{ "index" : { "_index" : "index", "_id" : "4" } } +{ "foo" : "qux" } +-------------------------------------------------- +// CONSOLE [float] -=== Index templates +==== Search APIs + +When calling a search API such `_search`, `_msearch`, or `_explain`, types +should not be included in the URL. Additionally, the `_type` field should not +be used in queries, aggregations, or scripts. + +[float] +==== Types in responses + +The document and search APIs will continue to return a `_type` key in +responses, to avoid breaks to response parsing. However, the key is +considered deprecated and should no longer be referenced. Types will +be completely removed from responses in 8.0. + +Note that when a deprecated typed API is used, the index's mapping type will be +returned as normal, but that typeless APIs will return the dummy type `_doc` +in the response. For example, the following typeless `get` call will always +return `_doc` as the type, even if the mapping has a custom type name like +`my_type`: + +[source,js] +-------------------------------------------------- +PUT index/my_type/1 +{ + "foo": "baz" +} + +GET index/_doc/1 +-------------------------------------------------- +// CONSOLE + +[source,js] +-------------------------------------------------- +{ + "_index" : "index", + "_type" : "_doc", + "_id" : "1", + "_version" : 1, + "_seq_no" : 0, + "_primary_term" : 1, + "found": true, + "_source" : { + "foo" : "baz" + } +} +-------------------------------------------------- +// TESTRESPONSE + +[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`. @@ -608,3 +701,16 @@ 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 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`.