Skip to content

Commit

Permalink
Update 'removal of types' docs to reflect the new plan. (#38548)
Browse files Browse the repository at this point in the history
Backport of #38003.
  • Loading branch information
jtibshirani authored Feb 7, 2019
1 parent 8115c2f commit 19e33d5
Showing 1 changed file with 109 additions and 17 deletions.
126 changes: 109 additions & 17 deletions docs/reference/mapping/removal_of_types.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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`.

0 comments on commit 19e33d5

Please sign in to comment.