Update 'removal of types' docs to reflect the new plan. (#38003)
This commit is contained in:
parent
237fcda2cc
commit
91b79ebed4
|
@ -4,7 +4,8 @@
|
||||||
IMPORTANT: Indices created in Elasticsearch 6.0.0 or later may only contain a
|
IMPORTANT: Indices created in Elasticsearch 6.0.0 or later may only contain a
|
||||||
single <<mapping-type,mapping type>>. Indices created in 5.x with multiple
|
single <<mapping-type,mapping type>>. Indices created in 5.x with multiple
|
||||||
mapping types will continue to function as before in Elasticsearch 6.x.
|
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]
|
[float]
|
||||||
=== What are mapping types?
|
=== What are mapping types?
|
||||||
|
@ -161,12 +162,12 @@ You can achieve the same thing by adding a custom `type` field as follows:
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
----
|
----
|
||||||
PUT twitter?include_type_name=true <1>
|
PUT twitter
|
||||||
{
|
{
|
||||||
"mappings": {
|
"mappings": {
|
||||||
"_doc": {
|
"_doc": {
|
||||||
"properties": {
|
"properties": {
|
||||||
"type": { "type": "keyword" }, <2>
|
"type": { "type": "keyword" }, <1>
|
||||||
"name": { "type": "text" },
|
"name": { "type": "text" },
|
||||||
"user_name": { "type": "keyword" },
|
"user_name": { "type": "keyword" },
|
||||||
"email": { "type": "keyword" },
|
"email": { "type": "keyword" },
|
||||||
|
@ -204,7 +205,7 @@ GET twitter/_search
|
||||||
},
|
},
|
||||||
"filter": {
|
"filter": {
|
||||||
"match": {
|
"match": {
|
||||||
"type": "tweet" <2>
|
"type": "tweet" <1>
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -212,9 +213,7 @@ GET twitter/_search
|
||||||
}
|
}
|
||||||
----
|
----
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
<1> Use `include_type_name=true` in case need to use the "old" syntax including the "_doc" object like
|
<1> The explicit `type` field takes the place of the implicit `_type` field.
|
||||||
in this example
|
|
||||||
<2> The explicit `type` field takes the place of the implicit `_type` field.
|
|
||||||
|
|
||||||
[float]
|
[float]
|
||||||
==== Parent/Child without mapping types
|
==== Parent/Child without mapping types
|
||||||
|
@ -258,30 +257,28 @@ Elasticsearch 6.x::
|
||||||
|
|
||||||
* The `_default_` mapping type is deprecated.
|
* 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::
|
Elasticsearch 7.x::
|
||||||
|
|
||||||
* The `type` parameter in URLs are deprecated. For instance, indexing
|
* Specifying types in requests is deprecated. For instance, indexing a
|
||||||
a document no longer requires a document `type`. The new index APIs
|
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`
|
are `PUT {index}/_doc/{id}` in case of explicit ids and `POST {index}/_doc`
|
||||||
for auto-generated ids.
|
for auto-generated ids.
|
||||||
|
|
||||||
* The index creation, `GET|PUT _mapping` and document APIs support a query
|
* The `include_type_name` parameter in the index creation, index template,
|
||||||
string parameter (`include_type_name`) which indicates whether requests and
|
and mapping APIs will default to `false`. Setting the parameter will result
|
||||||
responses should include a type name. It defaults to `true`.
|
in a deprecation warning.
|
||||||
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 `_default_` mapping type is removed.
|
* The `_default_` mapping type is removed.
|
||||||
|
|
||||||
Elasticsearch 8.x::
|
Elasticsearch 8.x::
|
||||||
|
|
||||||
* The `type` parameter is no longer supported in URLs.
|
* Specifying types in requests is no longer supported.
|
||||||
|
|
||||||
* The `include_type_name` parameter is deprecated, default to `false` and fails
|
|
||||||
the request when set to `true`.
|
|
||||||
|
|
||||||
Elasticsearch 9.x::
|
|
||||||
|
|
||||||
* The `include_type_name` parameter is removed.
|
* The `include_type_name` parameter is removed.
|
||||||
|
|
||||||
|
@ -427,17 +424,26 @@ POST _reindex
|
||||||
// NOTCONSOLE
|
// NOTCONSOLE
|
||||||
|
|
||||||
[float]
|
[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
|
In Elasticsearch 7.0, each API will support typeless requests,
|
||||||
starting with version 6.7. It will default to `true` in version 6.7, default to
|
and specifying a type will produce a deprecation warning.
|
||||||
`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.
|
|
||||||
|
|
||||||
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]
|
[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]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
|
@ -455,27 +461,27 @@ PUT index?include_type_name=false
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
<1> Mappings are included directly under the `mappings` key, without a type name.
|
<1> Mappings are included directly under the `mappings` key, without a type name.
|
||||||
|
|
||||||
[float]
|
|
||||||
==== PUT and GET mappings
|
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
PUT index
|
|
||||||
|
|
||||||
PUT index/_mappings?include_type_name=false
|
PUT index/_mappings?include_type_name=false
|
||||||
{
|
{
|
||||||
"properties": { <1>
|
"properties": { <1>
|
||||||
"foo": {
|
"bar": {
|
||||||
"type": "keyword"
|
"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
|
GET index/_mappings?include_type_name=false
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
<1> Mappings are included directly under the `mappings` key, without a type name.
|
// TEST[continued]
|
||||||
|
|
||||||
|
|
||||||
The above call returns
|
The above call returns
|
||||||
|
|
||||||
|
@ -487,6 +493,9 @@ The above call returns
|
||||||
"properties": { <1>
|
"properties": { <1>
|
||||||
"foo": {
|
"foo": {
|
||||||
"type": "keyword"
|
"type": "keyword"
|
||||||
|
},
|
||||||
|
"bar": {
|
||||||
|
"type": "text"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
@ -499,14 +508,14 @@ The above call returns
|
||||||
[float]
|
[float]
|
||||||
==== Document APIs
|
==== Document APIs
|
||||||
|
|
||||||
Index APIs must be called with the `{index}/_doc` path for automatic generation of
|
In 7.0, index APIs must be called with the `{index}/_doc` path for automatic
|
||||||
the `_id` and `{index}/_doc/{id}` with explicit ids.
|
generation of the `_id` and `{index}/_doc/{id}` with explicit ids.
|
||||||
|
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
PUT index/_doc/1
|
PUT index/_doc/1
|
||||||
{
|
{
|
||||||
"foo": "bar"
|
"foo": "baz"
|
||||||
}
|
}
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// CONSOLE
|
// CONSOLE
|
||||||
|
@ -514,7 +523,7 @@ PUT index/_doc/1
|
||||||
[source,js]
|
[source,js]
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
{
|
{
|
||||||
"_index": "index", <1>
|
"_index": "index",
|
||||||
"_id": "1",
|
"_id": "1",
|
||||||
"_type": "_doc",
|
"_type": "_doc",
|
||||||
"_version": 1,
|
"_version": 1,
|
||||||
|
@ -529,14 +538,98 @@ PUT index/_doc/1
|
||||||
}
|
}
|
||||||
--------------------------------------------------
|
--------------------------------------------------
|
||||||
// TESTRESPONSE
|
// TESTRESPONSE
|
||||||
<1> The response does not include a `_type`.
|
|
||||||
|
|
||||||
The <<docs-index_,GET>>, <<docs-delete,`DELETE`>>, <<docs-update,`_update`>> and <<search,`_search`>> APIs
|
Similarly, the `get` and `delete` APIs use the path `{index}/_doc/{id}`:
|
||||||
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.
|
[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]
|
[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
|
It is recommended to make index templates typeless before upgrading to 7.0 by
|
||||||
re-adding them with `include_type_name` set to `false`.
|
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
|
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
|
usually not a problem due to the fact that typeless index calls work on typed
|
||||||
indices.
|
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`.
|
||||||
|
|
Loading…
Reference in New Issue