honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update 'removal of types' docs to reflect the new plan. (#38003)

This commit is contained in:
Julie Tibshirani 2019-01-31 10:26:24 -08:00 committed by GitHub
parent 237fcda2cc
commit 91b79ebed4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 152 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
docs/reference/mapping/removal_of_types.asciidoc
View File

@ -4,7 +4,8 @@
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
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 <<docs-index_,GET>>, <<docs-delete,`DELETE`>>, <<docs-update,`_update`>> and <<search,`_search`>> 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`.