- Elasticsearch Guide: other versions:
- What is Elasticsearch?
- What’s new in 7.15
- Quick start
- Set up Elasticsearch
- Installing Elasticsearch
- Configuring Elasticsearch
- Important Elasticsearch configuration
- Secure settings
- Auditing settings
- Circuit breaker settings
- Cluster-level shard allocation and routing settings
- Cross-cluster replication settings
- Discovery and cluster formation settings
- Field data cache settings
- Index lifecycle management settings
- Index management settings
- Index recovery settings
- Indexing buffer settings
- License settings
- Local gateway settings
- Logging
- Machine learning settings
- Monitoring settings
- Node
- Networking
- Node query cache settings
- Search settings
- Security settings
- Shard request cache settings
- Snapshot lifecycle management settings
- Transforms settings
- Thread pools
- Watcher settings
- Advanced configuration
- Important system configuration
- Bootstrap Checks
- Heap size check
- File descriptor check
- Memory lock check
- Maximum number of threads check
- Max file size check
- Maximum size virtual memory check
- Maximum map count check
- Client JVM check
- Use serial collector check
- System call filter check
- OnError and OnOutOfMemoryError checks
- Early-access check
- G1GC check
- All permission check
- Discovery configuration check
- Bootstrap Checks for X-Pack
- Starting Elasticsearch
- Stopping Elasticsearch
- Discovery and cluster formation
- Add and remove nodes in your cluster
- Full-cluster restart and rolling restart
- Remote clusters
- Set up X-Pack
- Configuring X-Pack Java Clients
- Plugins
- Upgrade Elasticsearch
- Index modules
- Mapping
- Text analysis
- Overview
- Concepts
- Configure text analysis
- Built-in analyzer reference
- Tokenizer reference
- Token filter reference
- Apostrophe
- ASCII folding
- CJK bigram
- CJK width
- Classic
- Common grams
- Conditional
- Decimal digit
- Delimited payload
- Dictionary decompounder
- Edge n-gram
- Elision
- Fingerprint
- Flatten graph
- Hunspell
- Hyphenation decompounder
- Keep types
- Keep words
- Keyword marker
- Keyword repeat
- KStem
- Length
- Limit token count
- Lowercase
- MinHash
- Multiplexer
- N-gram
- Normalization
- Pattern capture
- Pattern replace
- Phonetic
- Porter stem
- Predicate script
- Remove duplicates
- Reverse
- Shingle
- Snowball
- Stemmer
- Stemmer override
- Stop
- Synonym
- Synonym graph
- Trim
- Truncate
- Unique
- Uppercase
- Word delimiter
- Word delimiter graph
- Character filters reference
- Normalizers
- Index templates
- Data streams
- Ingest pipelines
- Example: Parse logs
- Enrich your data
- Processor reference
- Append
- Bytes
- Circle
- Community ID
- Convert
- CSV
- Date
- Date index name
- Dissect
- Dot expander
- Drop
- Enrich
- Fail
- Fingerprint
- Foreach
- GeoIP
- Grok
- Gsub
- HTML strip
- Inference
- Join
- JSON
- KV
- Lowercase
- Network direction
- Pipeline
- Registered domain
- Remove
- Rename
- Script
- Set
- Set security user
- Sort
- Split
- Trim
- Uppercase
- URL decode
- URI parts
- User agent
- Aliases
- Search your data
- Query DSL
- Aggregations
- Bucket aggregations
- Adjacency matrix
- Auto-interval date histogram
- Children
- Composite
- Date histogram
- Date range
- Diversified sampler
- Filter
- Filters
- Geo-distance
- Geohash grid
- Geotile grid
- Global
- Histogram
- IP range
- Missing
- Multi Terms
- Nested
- Parent
- Range
- Rare terms
- Reverse nested
- Sampler
- Significant terms
- Significant text
- Terms
- Variable width histogram
- Subtleties of bucketing range fields
- Metrics aggregations
- Pipeline aggregations
- Average bucket
- Bucket script
- Bucket count K-S test
- Bucket correlation
- Bucket selector
- Bucket sort
- Cumulative cardinality
- Cumulative sum
- Derivative
- Extended stats bucket
- Inference bucket
- Max bucket
- Min bucket
- Moving average
- Moving function
- Moving percentiles
- Normalize
- Percentiles bucket
- Serial differencing
- Stats bucket
- Sum bucket
- Bucket aggregations
- EQL
- SQL
- Overview
- Getting Started with SQL
- Conventions and Terminology
- Security
- SQL REST API
- SQL Translate API
- SQL CLI
- SQL JDBC
- SQL ODBC
- SQL Client Applications
- SQL Language
- Functions and Operators
- Comparison Operators
- Logical Operators
- Math Operators
- Cast Operators
- LIKE and RLIKE Operators
- Aggregate Functions
- Grouping Functions
- Date/Time and Interval Functions and Operators
- Full-Text Search Functions
- Mathematical Functions
- String Functions
- Type Conversion Functions
- Geo Functions
- Conditional Functions And Expressions
- System Functions
- Reserved keywords
- SQL Limitations
- Scripting
- Data management
- ILM: Manage the index lifecycle
- Overview
- Concepts
- Automate rollover
- Customize built-in ILM policies
- Index lifecycle actions
- Configure a lifecycle policy
- Migrate index allocation filters to node roles
- Troubleshooting index lifecycle management errors
- Start and stop index lifecycle management
- Manage existing indices
- Skip rollover
- Restore a managed data stream or index
- Autoscaling
- Monitor a cluster
- Roll up or transform your data
- Set up a cluster for high availability
- Snapshot and restore
- Secure the Elastic Stack
- Elasticsearch security principles
- Configuring security
- Updating node security certificates
- User authentication
- Built-in users
- Service accounts
- Internal users
- Token-based authentication services
- Realms
- Realm chains
- Active Directory user authentication
- File-based user authentication
- LDAP user authentication
- Native user authentication
- OpenID Connect authentication
- PKI user authentication
- SAML authentication
- Kerberos authentication
- Integrating with other authentication systems
- Enabling anonymous access
- Controlling the user cache
- Configuring SAML single-sign-on on the Elastic Stack
- Configuring single sign-on to the Elastic Stack using OpenID Connect
- User authorization
- Built-in roles
- Defining roles
- Security privileges
- Document level security
- Field level security
- Granting privileges for data streams and aliases
- Mapping users and groups to roles
- Setting up field and document level security
- Submitting requests on behalf of other users
- Configuring authorization delegation
- Customizing roles and authorization
- Enable audit logging
- Restricting connections with IP filtering
- Securing clients and integrations
- Operator privileges
- Troubleshooting
- Some settings are not returned via the nodes settings API
- Authorization exceptions
- Users command fails due to extra arguments
- Users are frequently locked out of Active Directory
- Certificate verification fails for curl on Mac
- SSLHandshakeException causes connections to fail
- Common SSL/TLS exceptions
- Common Kerberos exceptions
- Common SAML issues
- Internal Server Error in Kibana
- Setup-passwords command fails due to connection failure
- Failures due to relocation of the configuration files
- Limitations
- Watcher
- Command line tools
- How to
- REST APIs
- API conventions
- Autoscaling APIs
- Compact and aligned text (CAT) APIs
- cat aliases
- cat allocation
- cat anomaly detectors
- cat count
- cat data frame analytics
- cat datafeeds
- cat fielddata
- cat health
- cat indices
- cat master
- cat nodeattrs
- cat nodes
- cat pending tasks
- cat plugins
- cat recovery
- cat repositories
- cat segments
- cat shards
- cat snapshots
- cat task management
- cat templates
- cat thread pool
- cat trained model
- cat transforms
- Cluster APIs
- Cluster allocation explain
- Cluster get settings
- Cluster health
- Cluster reroute
- Cluster state
- Cluster stats
- Cluster update settings
- Nodes feature usage
- Nodes hot threads
- Nodes info
- Nodes reload secure settings
- Nodes stats
- Pending cluster tasks
- Remote cluster info
- Task management
- Voting configuration exclusions
- Cross-cluster replication APIs
- Data stream APIs
- Document APIs
- Enrich APIs
- EQL APIs
- Features APIs
- Fleet APIs
- Find structure API
- Graph explore API
- Index APIs
- Alias exists
- Aliases
- Analyze
- Analyze index disk usage
- Clear cache
- Clone index
- Close index
- Create index
- Create or update alias
- Create or update component template
- Create or update index template
- Create or update index template (legacy)
- Delete component template
- Delete dangling index
- Delete alias
- Delete index
- Delete index template
- Delete index template (legacy)
- Exists
- Field usage stats
- Flush
- Force merge
- Freeze index
- Get alias
- Get component template
- Get field mapping
- Get index
- Get index settings
- Get index template
- Get index template (legacy)
- Get mapping
- Import dangling index
- Index recovery
- Index segments
- Index shard stores
- Index stats
- Index template exists (legacy)
- List dangling indices
- Open index
- Refresh
- Resolve index
- Rollover
- Shrink index
- Simulate index
- Simulate template
- Split index
- Synced flush
- Type exists
- Unfreeze index
- Update index settings
- Update mapping
- Index lifecycle management APIs
- Ingest APIs
- Info API
- Licensing APIs
- Logstash APIs
- Machine learning anomaly detection APIs
- Add events to calendar
- Add jobs to calendar
- Close jobs
- Create jobs
- Create calendars
- Create datafeeds
- Create filters
- Delete calendars
- Delete datafeeds
- Delete events from calendar
- Delete filters
- Delete forecasts
- Delete jobs
- Delete jobs from calendar
- Delete model snapshots
- Delete expired data
- Estimate model memory
- Find file structure
- Flush jobs
- Forecast jobs
- Get buckets
- Get calendars
- Get categories
- Get datafeeds
- Get datafeed statistics
- Get influencers
- Get jobs
- Get job statistics
- Get machine learning info
- Get model snapshots
- Get overall buckets
- Get scheduled events
- Get filters
- Get records
- Open jobs
- Post data to jobs
- Preview datafeeds
- Reset jobs
- Revert model snapshots
- Set upgrade mode
- Start datafeeds
- Stop datafeeds
- Update datafeeds
- Update filters
- Update jobs
- Update model snapshots
- Upgrade model snapshots
- Machine learning data frame analytics APIs
- Create data frame analytics jobs
- Create or update trained model aliases
- Create trained models
- Update data frame analytics jobs
- Delete data frame analytics jobs
- Delete trained models
- Delete trained model aliases
- Evaluate data frame analytics
- Explain data frame analytics
- Get data frame analytics jobs
- Get data frame analytics jobs stats
- Get trained models
- Get trained models stats
- Preview data frame analytics
- Start data frame analytics jobs
- Stop data frame analytics jobs
- Migration APIs
- Node lifecycle APIs
- Reload search analyzers API
- Repositories metering APIs
- Rollup APIs
- Script APIs
- Search APIs
- Searchable snapshots APIs
- Security APIs
- Authenticate
- Change passwords
- Clear cache
- Clear roles cache
- Clear privileges cache
- Clear API key cache
- Clear service account token caches
- Create API keys
- Create or update application privileges
- Create or update role mappings
- Create or update roles
- Create or update users
- Create service account tokens
- Delegate PKI authentication
- Delete application privileges
- Delete role mappings
- Delete roles
- Delete service account token
- Delete users
- Disable users
- Enable users
- Get API key information
- Query API key information
- Get application privileges
- Get builtin privileges
- Get role mappings
- Get roles
- Get service accounts
- Get service account credentials
- Get token
- Get user privileges
- Get users
- Grant API keys
- Has privileges
- Invalidate API key
- Invalidate token
- OpenID Connect prepare authentication
- OpenID Connect authenticate
- OpenID Connect logout
- SAML prepare authentication
- SAML authenticate
- SAML logout
- SAML invalidate
- SAML complete logout
- SAML service provider metadata
- SSL certificate
- Snapshot and restore APIs
- Snapshot lifecycle management APIs
- SQL APIs
- Transform APIs
- Usage API
- Watcher APIs
- Definitions
- Migration guide
- Release notes
- Elasticsearch version 7.15.2
- Elasticsearch version 7.15.1
- Elasticsearch version 7.15.0
- Elasticsearch version 7.14.2
- Elasticsearch version 7.14.1
- Elasticsearch version 7.14.0
- Elasticsearch version 7.13.4
- Elasticsearch version 7.13.3
- Elasticsearch version 7.13.2
- Elasticsearch version 7.13.1
- Elasticsearch version 7.13.0
- Elasticsearch version 7.12.1
- Elasticsearch version 7.12.0
- Elasticsearch version 7.11.2
- Elasticsearch version 7.11.1
- Elasticsearch version 7.11.0
- Elasticsearch version 7.10.2
- Elasticsearch version 7.10.1
- Elasticsearch version 7.10.0
- Elasticsearch version 7.9.3
- Elasticsearch version 7.9.2
- Elasticsearch version 7.9.1
- Elasticsearch version 7.9.0
- Elasticsearch version 7.8.1
- Elasticsearch version 7.8.0
- Elasticsearch version 7.7.1
- Elasticsearch version 7.7.0
- Elasticsearch version 7.6.2
- Elasticsearch version 7.6.1
- Elasticsearch version 7.6.0
- Elasticsearch version 7.5.2
- Elasticsearch version 7.5.1
- Elasticsearch version 7.5.0
- Elasticsearch version 7.4.2
- Elasticsearch version 7.4.1
- Elasticsearch version 7.4.0
- Elasticsearch version 7.3.2
- Elasticsearch version 7.3.1
- Elasticsearch version 7.3.0
- Elasticsearch version 7.2.1
- Elasticsearch version 7.2.0
- Elasticsearch version 7.1.1
- Elasticsearch version 7.1.0
- Elasticsearch version 7.0.0
- Elasticsearch version 7.0.0-rc2
- Elasticsearch version 7.0.0-rc1
- Elasticsearch version 7.0.0-beta1
- Elasticsearch version 7.0.0-alpha2
- Elasticsearch version 7.0.0-alpha1
- Dependencies and versions
Removal of mapping types
editRemoval of mapping types
editIndices created in Elasticsearch 7.0.0 or later no longer accept a
_default_
mapping. Indices created in 6.x will continue to function as before
in Elasticsearch 6.x. Types are deprecated in APIs in 7.0, with breaking changes
to the index creation, put mapping, get mapping, put template, get template and
get field mappings APIs.
What are mapping types?
editSince the first release of Elasticsearch, each document has been stored in a
single index and assigned a single mapping type. A mapping type was used to
represent the type of document or entity being indexed, for instance a
twitter
index might have a user
type and a tweet
type.
Each mapping type could have its own fields, so the user
type might have a
full_name
field, a user_name
field, and an email
field, while the
tweet
type could have a content
field, a tweeted_at
field and, like the
user
type, a user_name
field.
Each document had a _type
metadata field containing the type name, and searches
could be limited to one or more types by specifying the type name(s) in the
URL:
GET twitter/user,tweet/_search { "query": { "match": { "user_name": "kimchy" } } }
The _type
field was combined with the document’s _id
to generate a _uid
field, so documents of different types with the same _id
could exist in a
single index.
Mapping types were also used to establish a
parent-child relationship
between documents, so documents of type question
could be parents to
documents of type answer
.
Why are mapping types being removed?
editInitially, we spoke about an “index” being similar to a “database” in an SQL database, and a “type” being equivalent to a “table”.
This was a bad analogy that led to incorrect assumptions. In an SQL database, tables are independent of each other. The columns in one table have no bearing on columns with the same name in another table. This is not the case for fields in a mapping type.
In an Elasticsearch index, fields that have the same name in different mapping
types are backed by the same Lucene field internally. In other words, using
the example above, the user_name
field in the user
type is stored in
exactly the same field as the user_name
field in the tweet
type, and both
user_name
fields must have the same mapping (definition) in both types.
This can lead to frustration when, for example, you want deleted
to be a
date
field in one type and a boolean
field in another type in the same
index.
On top of that, storing different entities that have few or no fields in common in the same index leads to sparse data and interferes with Lucene’s ability to compress documents efficiently.
For these reasons, we have decided to remove the concept of mapping types from Elasticsearch.
Alternatives to mapping types
editIndex per document type
editThe first alternative is to have an index per document type. Instead of
storing tweets and users in a single twitter
index, you could store tweets
in the tweets
index and users in the user
index. Indices are completely
independent of each other and so there will be no conflict of field types
between indices.
This approach has two benefits:
- Data is more likely to be dense and so benefit from compression techniques used in Lucene.
- The term statistics used for scoring in full text search are more likely to be accurate because all documents in the same index represent a single entity.
Each index can be sized appropriately for the number of documents it will
contain: you can use a smaller number of primary shards for users
and a
larger number of primary shards for tweets
.
Custom type field
editOf course, there is a limit to how many primary shards can exist in a cluster
so you may not want to waste an entire shard for a collection of only a few
thousand documents. In this case, you can implement your own custom type
field which will work in a similar way to the old _type
.
Let’s take the user
/tweet
example above. Originally, the workflow would
have looked something like this:
PUT twitter { "mappings": { "user": { "properties": { "name": { "type": "text" }, "user_name": { "type": "keyword" }, "email": { "type": "keyword" } } }, "tweet": { "properties": { "content": { "type": "text" }, "user_name": { "type": "keyword" }, "tweeted_at": { "type": "date" } } } } } PUT twitter/user/kimchy { "name": "Shay Banon", "user_name": "kimchy", "email": "shay@kimchy.com" } PUT twitter/tweet/1 { "user_name": "kimchy", "tweeted_at": "2017-10-24T09:00:00Z", "content": "Types are going away" } GET twitter/tweet/_search { "query": { "match": { "user_name": "kimchy" } } }
You can achieve the same thing by adding a custom type
field as follows:
PUT twitter { "mappings": { "_doc": { "properties": { "type": { "type": "keyword" }, "name": { "type": "text" }, "user_name": { "type": "keyword" }, "email": { "type": "keyword" }, "content": { "type": "text" }, "tweeted_at": { "type": "date" } } } } } PUT twitter/_doc/user-kimchy { "type": "user", "name": "Shay Banon", "user_name": "kimchy", "email": "shay@kimchy.com" } PUT twitter/_doc/tweet-1 { "type": "tweet", "user_name": "kimchy", "tweeted_at": "2017-10-24T09:00:00Z", "content": "Types are going away" } GET twitter/_search { "query": { "bool": { "must": { "match": { "user_name": "kimchy" } }, "filter": { "match": { "type": "tweet" } } } } }
Parent/Child without mapping types
editPreviously, a parent-child relationship was represented by making one mapping
type the parent, and one or more other mapping types the children. Without
types, we can no longer use this syntax. The parent-child feature will
continue to function as before, except that the way of expressing the
relationship between documents has been changed to use the new
join
field.
Schedule for removal of mapping types
editThis is a big change for our users, so we have tried to make it as painless as possible. The change will roll out as follows:
- Elasticsearch 5.6.0
-
-
Setting
index.mapping.single_type: true
on an index will enable the single-type-per-index behaviour which will be enforced in 6.0. -
The
join
field replacement for parent-child is available on indices created in 5.6.
-
Setting
- Elasticsearch 6.x
-
- Indices created in 5.x will continue to function in 6.x as they did in 5.x.
-
Indices created in 6.x only allow a single-type per index. Any name
can be used for the type, but there can be only one. The preferred type name
is
_doc
, so that index APIs have the same path as they will have in 7.0:PUT {index}/_doc/{id}
andPOST {index}/_doc
-
The
_type
name can no longer be combined with the_id
to form the_uid
field. The_uid
field has become an alias for the_id
field. -
New indices no longer support the old-style of parent/child and should
use the
join
field instead. -
The
_default_
mapping type is deprecated. -
In 6.8, 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 totrue
, and should be set to an explicit value to prepare to upgrade to 7.0. Not settinginclude_type_name
will result in a deprecation warning. Indices which don’t have an explicit type will use the dummy type name_doc
.
- Elasticsearch 7.x
-
-
Specifying types in requests is deprecated. For instance, indexing a
document no longer requires a document
type
. The new index APIs arePUT {index}/_doc/{id}
in case of explicit ids andPOST {index}/_doc
for auto-generated ids. Note that in 7.0,_doc
is a permanent part of the path, and represents the endpoint name rather than the document type. -
The
include_type_name
parameter in the index creation, index template, and mapping APIs will default tofalse
. Setting the parameter at all will result in a deprecation warning. -
The
_default_
mapping type is removed.
-
Specifying types in requests is deprecated. For instance, indexing a
document no longer requires a document
- Elasticsearch 8.x
-
- Specifying types in requests is no longer supported.
-
The
include_type_name
parameter is removed.
Migrating multi-type indices to single-type
editThe Reindex API can be used to convert multi-type indices to
single-type indices. The following examples can be used in Elasticsearch 5.6
or Elasticsearch 6.x. In 6.x, there is no need to specify
index.mapping.single_type
as that is the default.
Index per document type
editThis first example splits our twitter
index into a tweets
index and a
users
index:
PUT users { "settings": { "index.mapping.single_type": true }, "mappings": { "_doc": { "properties": { "name": { "type": "text" }, "user_name": { "type": "keyword" }, "email": { "type": "keyword" } } } } } PUT tweets { "settings": { "index.mapping.single_type": true }, "mappings": { "_doc": { "properties": { "content": { "type": "text" }, "user_name": { "type": "keyword" }, "tweeted_at": { "type": "date" } } } } } POST _reindex { "source": { "index": "twitter", "type": "user" }, "dest": { "index": "users", "type": "_doc" } } POST _reindex { "source": { "index": "twitter", "type": "tweet" }, "dest": { "index": "tweets", "type": "_doc" } }
Custom type field
editThis next example adds a custom type
field and sets it to the value of the
original _type
. It also adds the type to the _id
in case there are any
documents of different types which have conflicting IDs:
PUT new_twitter { "mappings": { "_doc": { "properties": { "type": { "type": "keyword" }, "name": { "type": "text" }, "user_name": { "type": "keyword" }, "email": { "type": "keyword" }, "content": { "type": "text" }, "tweeted_at": { "type": "date" } } } } } POST _reindex { "source": { "index": "twitter" }, "dest": { "index": "new_twitter" }, "script": { "source": """ ctx._source.type = ctx._type; ctx._id = ctx._type + '-' + ctx._id; ctx._type = '_doc'; """ } }
Typeless APIs in 7.0
editIn Elasticsearch 7.0, each API will support typeless requests, and specifying a type will produce a deprecation warning.
Typeless APIs work even if the target index contains a custom type.
For example, if an index has the custom type name my_type
, we can add
documents to it using typeless index
calls, and load documents with typeless
get
calls.
Index APIs
editIndex 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.8 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.
It should be set explicitly in 6.8 to prepare to upgrade to 7.0. To avoid deprecation
warnings in 6.8, the parameter can be set to either true
or false
. In 7.0, setting
include_type_name
at all will result in a deprecation warning.
See some examples of interactions with Elasticsearch with this option set to false
:
PUT /my-index-000001?include_type_name=false { "mappings": { "properties": { "foo": { "type": "keyword" } } } }
PUT /my-index-000001/_mappings?include_type_name=false { "properties": { "bar": { "type": "text" } } }
GET /my-index-000001/_mappings?include_type_name=false
The above call returns
{ "my-index-000001": { "mappings": { "properties": { "foo": { "type": "keyword" }, "bar": { "type": "text" } } } } }
Document APIs
editIn 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.
PUT /my-index-000001/_doc/1 { "foo": "baz" }
{ "_index": "my-index-000001", "_id": "1", "_type": "_doc", "_version": 1, "result": "created", "_shards": { "total": 2, "successful": 1, "failed": 0 }, "_seq_no": 0, "_primary_term": 1 }
Similarly, the get
and delete
APIs use the path {index}/_doc/{id}
:
GET /my-index-000001/_doc/1
In 7.0, _doc
represents the endpoint name instead of the document type.
The _doc
component is a permanent part of the path for the document index
,
get
, and delete
APIs going forward, and will not be removed in 8.0.
For API paths that contain both a type and endpoint name like _update
,
in 7.0 the endpoint will immediately follow the index name:
POST /my-index-000001/_update/1 { "doc" : { "foo" : "qux" } } GET /my-index-000001/_source/1
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:
POST _bulk { "index" : { "_index" : "my-index-000001", "_id" : "3" } } { "foo" : "baz" } { "index" : { "_index" : "my-index-000001", "_id" : "4" } } { "foo" : "qux" }
Search APIs
editWhen 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.
Types in responses
editThe 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
:
PUT /my-index-000001/my_type/1 { "foo": "baz" } GET /my-index-000001/_doc/1
{ "_index" : "my-index-000001", "_type" : "_doc", "_id" : "1", "_version" : 1, "_seq_no" : 0, "_primary_term" : 1, "found": true, "_source" : { "foo" : "baz" } }
Index templates
editIt is recommended to make index templates typeless by re-adding them with
include_type_name
set to false
. Under the hood, typeless templates will use
the dummy type _doc
when creating indices.
In case typeless templates are used with typed index creation calls or typed
templates are used with typeless index creation calls, the template will still
be applied but the index creation call decides whether there should be a type
or not. For instance in the below example, index-1-01
will have a type in
spite of the fact that it matches a template that is typeless, and index-2-01
will be typeless in spite of the fact that it matches a template that defines
a type. Both index-1-01
and index-2-01
will inherit the foo
field from
the template that they match.
PUT _template/template1 { "index_patterns":[ "index-1-*" ], "mappings": { "properties": { "foo": { "type": "keyword" } } } } PUT _template/template2?include_type_name=true { "index_patterns":[ "index-2-*" ], "mappings": { "type": { "properties": { "foo": { "type": "keyword" } } } } } PUT index-1-01?include_type_name=true { "mappings": { "type": { "properties": { "bar": { "type": "long" } } } } } PUT index-2-01 { "mappings": { "properties": { "bar": { "type": "long" } } } }
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.
Mixed-version clusters
editIn a cluster composed of both 6.8 and 7.0 nodes, the parameter
include_type_name
should be specified in index APIs like index
creation. This is because the parameter has a different default between
6.8 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.8 nodes. This also holds true for the typeless
versions of queries that perform document lookups, such as terms
.
On this page
- What are mapping types?
- Why are mapping types being removed?
- Alternatives to mapping types
- Index per document type
- Custom type field
- Parent/Child without mapping types
- Schedule for removal of mapping types
- Migrating multi-type indices to single-type
- Index per document type
- Custom type field
- Typeless APIs in 7.0
- Index APIs
- Document APIs
- Search APIs
- Types in responses
- Index templates
- Mixed-version clusters