Skip to content

Update 'removal of types' docs to reflect the new plan for 7.0. #38003

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 31, 2019
Merged

Update 'removal of types' docs to reflect the new plan for 7.0. #38003

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
198 changes: 152 additions & 46 deletions docs/reference/mapping/removal_of_types.asciidoc
View file
Open in desktop
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 @@ -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" },
Expand Down Expand Up @@ -204,17 +205,15 @@ GET twitter/_search
},
"filter": {
"match": {
"type": "tweet" <2>
"type": "tweet" <1>
}
}
}
}
}
----
// 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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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]
--------------------------------------------------
Expand All @@ -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"
}
}
}

GET index/_mappings?include_type_name=false
--------------------------------------------------
// 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

Expand All @@ -487,6 +493,9 @@ The above call returns
"properties": { <1>
"foo": {
"type": "keyword"
},
"bar": {
"type": "text"
}
}
}
Expand All @@ -499,22 +508,22 @@ 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

[source,js]
--------------------------------------------------
{
"_index": "index", <1>
"_index": "index",
"_id": "1",
"_type": "_doc",
"_version": 1,
Expand All @@ -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]
==== 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
==== 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 @@ -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 typless 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`.