Mapping

An alias mapping defines an alternate name for a field in the index. The alias can be used in place of the target field in search requests, and selected other APIs like field capabilities.

Almost all components of the search request accept field aliases. In particular, aliases can be used in queries, aggregations, and sort fields, as well as when requesting docvalue_fields, stored_fields, suggestions, and highlights. Scripts also support aliases when accessing field values. Please see the section on unsupported APIs for exceptions.

In some parts of the search request and when requesting field capabilities, field wildcard patterns can be provided. In these cases, the wildcard pattern will match field aliases in addition to concrete fields:

In Elasticsearch, there is no dedicated array datatype. Any field can contain zero or more values by default, however, all values in the array must be of the same datatype. For instance:

When adding a field dynamically, the first value in the array determines the field type. All subsequent values must be of the same datatype or it must at least be possible to coerce subsequent values to the same datatype.

Arrays with a mixture of datatypes are not supported: [ 10, "some string" ]

An array may contain null values, which are either replaced by the configured null_value or skipped entirely. An empty array [] is treated as a missing field — a field with no values.

Nothing needs to be pre-configured in order to use arrays in documents, they are supported out of the box:

The binary type accepts a binary value as a Base64 encoded string. The field is not stored by default and is not searchable:

The following range types are supported:

Below is an example of configuring a mapping with various range fields followed by an example that indexes several range types.

The following is an example of a term query on the integer_range field named "expected_attendees".

The result produced by the above query.

The following is an example of a date_range query over the date_range field named "time_frame".

This query produces a similar result:

Boolean fields accept JSON true and false values, but can also accept strings which are interpreted as either true or false:

For example:

Aggregations like the terms aggregation use 1 and 0 for the key, and the strings "true" and "false" for the key_as_string. Boolean fields when used in scripts, return 1 and 0:

JSON doesn’t have a date datatype, so dates in Elasticsearch can either be:

Internally, dates are converted to UTC (if the time-zone is specified) and stored as a long number representing milliseconds-since-the-epoch.

Queries on dates are internally converted to range queries on this long representation, and the result of aggregations and stored fields is converted back to a string depending on the date format that is associated with the field.

Date formats can be customised, but if no format is specified then it uses the default:

This means that it will accept dates with optional timestamps, which conform to the formats supported by strict_date_optional_time or milliseconds-since-the-epoch.

For instance:

Fields of type geo_point accept latitude-longitude pairs, which can be used:

There are four ways that a geo-point may be specified, as demonstrated below:

The geo_shape datatype facilitates the indexing of and searching with arbitrary geo shapes such as rectangles and polygons. It should be used when either the data being indexed or the queries being executed contain shapes other than just points.

You can query documents using this type using geo_shape Query.

The geo_shape mapping maps geo_json geometry objects to the geo_shape type. To enable it, users must explicitly map fields to the geo_shape type.

GeoShape types are indexed by decomposing the shape into a triangular mesh and indexing each triangle as a 7 dimension point in a BKD tree. This provides near perfect spatial resolution (down to 1e-7 decimal degree precision) since all spatial relations are computed using an encoded vector representation of the original shape instead of a raster-grid representation as used by the Prefix trees indexing approach. Performance of the tessellator primarily depends on the number of vertices that define the polygon/multi-polygon. While this is the default indexing technique prefix trees can still be used by setting the tree or strategy parameters according to the appropriate Mapping Options. Note that these parameters are now deprecated and will be removed in a future version.

IMPORTANT NOTES

The following features are not yet supported with the new indexing approach:

deprecated[6.6, PrefixTrees no longer used] To efficiently represent shapes in an inverted index, Shapes are converted into a series of hashes representing grid squares (commonly referred to as "rasters") using implementations of a PrefixTree. The tree notion comes from the fact that the PrefixTree uses multiple grid layers, each with an increasing level of precision to represent the Earth. This can be thought of as increasing the level of detail of a map or image at higher zoom levels. Since this approach causes precision issues with indexed shape, it has been deprecated in favor of a vector indexing approach that indexes the shapes as a triangular mesh (see Indexing approach).

Multiple PrefixTree implementations are provided:

deprecated[6.6, PrefixTrees no longer used] The indexing implementation selected relies on a SpatialStrategy for choosing how to decompose the shapes (either as grid squares or a tessellated triangular mesh). Each strategy answers the following:

The following Strategy implementations (with corresponding capabilities) are provided:

Recursive and Term strategies do not provide 100% accuracy and depending on how they are configured it may return some false positives for INTERSECTS, WITHIN and CONTAINS queries, and some false negatives for DISJOINT queries. To mitigate this, it is important to select an appropriate value for the tree_levels parameter and to adjust expectations accordingly. For example, a point may be near the border of a particular grid cell and may thus not match a query that only matches the cell right next to it — even though the shape is very close to the point.

This mapping definition maps the location field to the geo_shape type using the default vector implementation. It provides approximately 1e-7 decimal degree precision.

deprecated[6.6, PrefixTrees no longer used] With prefix trees, Elasticsearch uses the paths in the tree as terms in the inverted index and in queries. The higher the level (and thus the precision), the more terms are generated. Of course, calculating the terms, keeping them in memory, and storing them on disk all have a price. Especially with higher tree levels, indices can become extremely large even with a modest amount of data. Additionally, the size of the features also matters. Big, complex polygons can take up a lot of space at higher tree levels. Which setting is right depends on the use case. Generally one trades off accuracy against index size and query performance.

The defaults in Elasticsearch for both implementations are a compromise between index size and a reasonable level of precision of 50m at the equator. This allows for indexing tens of millions of shapes without overly bloating the resulting index too much relative to the input size.

Shapes can be represented using either the GeoJSON or Well-Known Text (WKT) format. The following table provides a mapping of GeoJSON and WKT to Elasticsearch types:

A point is a single geographic coordinate, such as the location of a building or the current position given by a smartphone’s Geolocation API. The following is an example of a point in GeoJSON.

The following is an example of a point in WKT:

A linestring defined by an array of two or more positions. By specifying only two points, the linestring will represent a straight line. Specifying more than two points creates an arbitrary path. The following is an example of a LineString in GeoJSON.

The following is an example of a LineString in WKT:

The above linestring would draw a straight line starting at the White House to the US Capitol Building.

A polygon is defined by a list of a list of points. The first and last points in each (outer) list must be the same (the polygon must be closed). The following is an example of a Polygon in GeoJSON.

The following is an example of a Polygon in WKT:

The first array represents the outer boundary of the polygon, the other arrays represent the interior shapes ("holes"). The following is a GeoJSON example of a polygon with a hole:

The following is an example of a Polygon with a hole in WKT:

IMPORTANT NOTE: WKT does not enforce a specific order for vertices thus ambiguous polygons around the dateline and poles are possible. GeoJSON mandates that the outer polygon must be counterclockwise and interior shapes must be clockwise, which agrees with the Open Geospatial Consortium (OGC) Simple Feature Access specification for vertex ordering.

Elasticsearch accepts both clockwise and counterclockwise polygons if they appear not to cross the dateline (i.e. they cross less than 180° of longitude), but for polygons that do cross the dateline (or for other polygons wider than 180°) Elasticsearch requires the vertex ordering to comply with the OGC and GeoJSON specifications. Otherwise, an unintended polygon may be created and unexpected query/filter results will be returned.

The following provides an example of an ambiguous polygon. Elasticsearch will apply the GeoJSON standard to eliminate ambiguity resulting in a polygon that crosses the dateline.

An orientation parameter can be defined when setting the geo_shape mapping (see Mapping Options). This will define vertex order for the coordinate list on the mapped geo_shape field. It can also be overridden on each document. The following is an example for overriding the orientation on a document:

The following is an example of a list of geojson points:

The following is an example of a list of WKT points:

The following is an example of a list of geojson linestrings:

The following is an example of a list of WKT linestrings:

The following is an example of a list of geojson polygons (second polygon contains a hole):

The following is an example of a list of WKT polygons (second polygon contains a hole):

The following is an example of a collection of geojson geometry objects:

The following is an example of a collection of WKT geometry objects:

Elasticsearch supports an envelope type, which consists of coordinates for upper left and lower right points of the shape to represent a bounding rectangle in the format :

The following is an example of an envelope using the WKT BBOX format:

NOTE: WKT specification expects the following order: minLon, maxLon, maxLat, minLat.

Elasticsearch supports a circle type, which consists of a center point with a radius. Note that this circle representation can only be indexed when using the recursive Prefix Tree strategy. For the default Indexing approach circles should be approximated using a POLYGON.

Note: The inner radius field is required. If not specified, then the units of the radius will default to METERS.

NOTE: Neither GeoJSON or WKT support a point-radius circle type.

Due to the complex input structure and index representation of shapes, it is not currently possible to sort shapes or retrieve their fields directly. The geo_shape value is only retrievable through the _source field.

An ip field can index/store either IPv4 or IPv6 addresses.

A field to index structured content such as email addresses, hostnames, status codes, zip codes or tags.

They are typically used for filtering (Find me all blog posts where status is published), for sorting, and for aggregations. Keyword fields are only searchable by their exact value.

If you need to index full text content such as email bodies or product descriptions, it is likely that you should rather use a text field.

Below is an example of a mapping for a keyword field:

The nested type is a specialised version of the object datatype that allows arrays of objects to be indexed in a way that they can be queried independently of each other.

The following numeric types are supported:

Below is an example of configuring a mapping with numeric fields:

JSON documents are hierarchical in nature: the document may contain inner objects which, in turn, may contain inner objects themselves:

Internally, this document is indexed as a simple, flat list of key-value pairs, something like this:

An explicit mapping for the above document could look like this:

You are not required to set the field type to object explicitly, as this is the default value.

A field to index full-text values, such as the body of an email or the description of a product. These fields are analyzed, that is they are passed through an analyzer to convert the string into a list of individual terms before being indexed. The analysis process allows Elasticsearch to search for individual words within each full text field. Text fields are not used for sorting and seldom used for aggregations (although the significant text aggregation is a notable exception).

If you need to index structured content such as email addresses, hostnames, status codes, or tags, it is likely that you should rather use a keyword field.

Below is an example of a mapping for a text field:

A field of type token_count is really an integer field which accepts string values, analyzes them, then indexes the number of tokens in the string.

For instance:

The percolator field type parses a json structure into a native query and stores that query, so that the percolate query can use it to match provided documents.

Any field that contains a json object can be configured to be a percolator field. The percolator field type has no settings. Just configuring the percolator field type is sufficient to instruct Elasticsearch to treat a field as a query.

If the following mapping configures the percolator field type for the query field:

Then you can index a query:

Reindexing percolator queries is sometimes required to benefit from improvements made to the percolator field type in new releases.

Reindexing percolator queries can be reindexed by using the reindex api. Lets take a look at the following index with a percolator field type:

Lets say you’re going to upgrade to a new major version and in order for the new Elasticsearch version to still be able to read your queries you need to reindex your queries into a new index on the current Elasticsearch version:

Executing the percolate query via the queries alias:

now returns matches from the new index:

When the percolator verifies a percolator candidate match it is going to parse, perform query time text analysis and actually run the percolator query on the document being percolated. This is done for each candidate match and every time the percolate query executes. If your query time text analysis is relatively expensive part of query parsing then text analysis can become the dominating factor time is being spent on when percolating. This query parsing overhead can become noticeable when the percolator ends up verifying many candidate percolator query matches.

To avoid the most expensive part of text analysis at percolate time. One can choose to do the expensive part of text analysis when indexing the percolator query. This requires using two different analyzers. The first analyzer actually performs text analysis that needs be performed (expensive part). The second analyzer (usually whitespace) just splits the generated tokens that the first analyzer has produced. Then before indexing a percolator query, the analyze api should be used to analyze the query text with the more expensive analyzer. The result of the analyze api, the tokens, should be used to substitute the original query text in the percolator query. It is important that the query should now be configured to override the analyzer from the mapping and just the second analyzer. Most text based queries support an analyzer option (match, query_string, simple_query_string). Using this approach the expensive text analysis is performed once instead of many times.

Lets demonstrate this workflow via a simplified example.

Lets say we want to index the following percolator query:

with these settings and mapping:

First we need to use the analyze api to perform the text analysis prior to indexing:

This results the following response:

All the tokens in the returned order need to replace the query text in the percolator query:

The analyze api prior to the indexing the percolator flow should be done for each percolator query.

At percolate time nothing changes and the percolate query can be defined normally:

This results in a response like this:

Wildcard queries are more expensive than other queries for the percolator, especially if the wildcard expressions are large.

In the case of wildcard queries with prefix wildcard expressions or just the prefix query, the edge_ngram token filter can be used to replace these queries with regular term query on a field where the edge_ngram token filter is configured.

Creating an index with custom analysis settings:

Then instead of indexing the following query:

this query below should be indexed:

This way can handle the second query more efficiently than the first query.

The following search request will match with the previously indexed percolator query:

The same technique can also be used to speed up suffix wildcard searches. By using the reverse token filter before the edge_ngram token filter.

Then instead of indexing the following query:

the following query below should be indexed:

The following search request will match with the previously indexed percolator query:

Percolate queries can be added to any index. Instead of adding percolate queries to the index the data resides in, these queries can also be added to a dedicated index. The advantage of this is that this dedicated percolator index can have its own index settings (For example the number of primary and replica shards). If you choose to have a dedicated percolate index, you need to make sure that the mappings from the normal index are also available on the percolate index. Otherwise percolate queries can be parsed incorrectly.

In certain cases it is unknown what kind of percolator queries do get registered, and if no field mapping exists for fields that are referred by percolator queries then adding a percolator query fails. This means the mapping needs to be updated to have the field with the appropriate settings, and then the percolator query can be added. But sometimes it is sufficient if all unmapped fields are handled as if these were default text fields. In those cases one can configure the index.percolator.map_unmapped_fields_as_text setting to true (default to false) and then if a field referred in a percolator query does not exist, it will be handled as a default text field so that adding the percolator query doesn’t fail.

Because the percolate query is processing one document at a time, it doesn’t support queries and filters that run against child documents such as has_child and has_parent.

There are a number of queries that fetch data via a get call during query parsing. For example the terms query when using terms lookup, template query when using indexed scripts and geo_shape when using pre-indexed shapes. When these queries are indexed by the percolator field type then the get call is executed once. So each time the percolator query evaluates these queries, the fetches terms, shapes etc. as the were upon index time will be used. Important to note is that fetching of terms that these queries do, happens both each time the percolator query gets indexed on both primary and replica shards, so the terms that are actually indexed can be different between shard copies, if the source index changed while indexing.

The script inside a script query can only access doc values fields. The percolate query indexes the provided document into an in-memory index. This in-memory index doesn’t support stored fields and because of that the _source field and other stored fields are not stored. This is the reason why in the script query the _source and other stored fields aren’t available.

Percolator queries that contain field aliases may not always behave as expected. In particular, if a percolator query is registered that contains a field alias, and then that alias is updated in the mappings to refer to a different field, the stored query will still refer to the original target field. To pick up the change to the field alias, the percolator query must be explicitly reindexed.

The join datatype is a special field that creates parent/child relation within documents of the same index. The relations section defines a set of possible relations within the documents, each relation being a parent name and a child name. A parent/child relation can be defined as follows:

To index a document with a join, the name of the relation and the optional parent of the document must be provided in the source. For instance the following example creates two parent documents in the question context:

When indexing parent documents, you can choose to specify just the name of the relation as a shortcut instead of encapsulating it in the normal object notation:

When indexing a child, the name of the relation as well as the parent id of the document must be added in the _source.

For instance the following example shows how to index two child documents:

deprecated::[6.0.0, "`_all` may no longer be enabled for indices created in 6.0+, use a custom field and the mapping copy_to parameter"]

The all field is a special _catch-all field which concatenates the values of all of the other fields into one big string, using space as a delimiter, which is then analyzed and indexed, but not stored. This means that it can be searched, but not retrieved.

The _all field allows you to search for values in documents without knowing which field contains the value. This makes it a useful option when getting started with a new dataset. For instance:

The _all field is just a text field, and accepts the same parameters that other string fields accept, including analyzer, term_vectors, index_options, and store.

The _all field can be useful, especially when exploring new data using simple filtering. However, by concatenating field values into one big string, the _all field loses the distinction between short fields (more relevant) and long fields (less relevant). For use cases where search relevance is important, it is better to query individual fields specifically.

The _all field is not free: it requires extra CPU cycles and uses more disk space. For this reason, it is disabled by default. If needed, it can be enabled.

The _field_names field used to index the names of every field in a document that contains any value other than null. This field was used by the exists query to find documents that either have or don’t have any non-null value for a particular field.

Now the _field_names field only indexes the names of fields that have doc_values and norms disabled. For fields which have either doc_values or norm enabled the exists query will still be available but will not use the _field_names field.

added[6.4.0]

The _ignored field indexes and stores the names of every field in a document that has been ignored because it was malformed and ignore_malformed was turned on.

This field is searchable with term, terms and exists queries, and is returned as part of the search hits.

For instance the below query matches all documents that have one or more fields that got ignored:

Similarly, the below query finds all documents whose @timestamp field was ignored at index time:

Each document has an _id that uniquely identifies it, which is indexed so that documents can be looked up either with the GET API or the ids query.

The value of the _id field is accessible in certain queries (term, terms, match, query_string, simple_query_string).

The value of the _id field is also accessible in aggregations or for sorting, but doing so is discouraged as it requires to load a lot of data in memory. In case sorting or aggregating on the _id field is required, it is advised to duplicate the content of the _id field in another field that has doc_values enabled.

When performing queries across multiple indexes, it is sometimes desirable to add query clauses that are associated with documents of only certain indexes. The _index field allows matching on the index a document was indexed into. Its value is accessible in term, or terms queries, aggregations, scripts, and when sorting:

A mapping type can have custom meta data associated with it. These are not used at all by Elasticsearch, but can be used to store application-specific metadata, such as the class that a document belongs to:

The _meta field can be updated on an existing type using the PUT mapping API:

A document is routed to a particular shard in an index using the following formula:

The default value used for _routing is the document’s _id.

Custom routing patterns can be implemented by specifying a custom routing value per document. For instance:

The value of the _routing field is accessible in queries:

The source field contains the original JSON document body that was passed at index time. The _source field itself is not indexed (and thus is not searchable), but it is stored so that it can be returned when executing _fetch requests, like get or search.

deprecated[6.0.0,See Removal of mapping types]

Each document indexed is associated with a _type (see Mapping Type) and an _id. The _type field is indexed in order to make searching by type name fast.

The value of the _type field is accessible in queries, aggregations, scripts, and when sorting:

deprecated::[6.0.0, "Now that types have been removed, documents are uniquely identified by their _id and the _uid field has only been kept as a view over the _id field for backward compatibility."]

Each document indexed is associated with a _type (see Mapping Type) and an _id. These values are combined as {type}#{id} and indexed as the _uid field.

The value of the _uid field is accessible in queries, aggregations, scripts, and when sorting:

The values of analyzed string fields are passed through an analyzer to convert the string into a stream of tokens or terms. For instance, the string "The quick Brown Foxes." may, depending on which analyzer is used, be analyzed to the tokens: quick, brown, fox. These are the actual terms that are indexed for the field, which makes it possible to search efficiently for individual words within big blobs of text.

This analysis process needs to happen not just at index time, but also at query time: the query string needs to be passed through the same (or a similar) analyzer so that the terms that it tries to find are in the same format as those that exist in the index.

Elasticsearch ships with a number of pre-defined analyzers, which can be used without further configuration. It also ships with many character filters, tokenizers, and [analysis-tokenfilters] which can be combined to configure custom analyzers per index.

Analyzers can be specified per-query, per-field or per-index. At index time, Elasticsearch will look for an analyzer in this order:

At query time, there are a few more layers:

The easiest way to specify an analyzer for a particular field is to define it in the field mapping, as follows:

The normalizer property of keyword fields is similar to analyzer except that it guarantees that the analysis chain produces a single token.

The normalizer is applied prior to indexing the keyword, as well as at search-time when the keyword field is searched via a query parser such as the match query or via a term-level query such as the term query.

The above queries match documents 1 and 2 since BÀR is converted to bar at both index and query time.

Also, the fact that keywords are converted prior to indexing also means that aggregations return normalized values:

returns

Individual fields can be boosted automatically — count more towards the relevance score — at query time, with the boost parameter as follows:

You can achieve the same effect by using the boost parameter directly in the query, for instance the following query (with field time boost):

is equivalent to:

The boost is also applied when it is copied with the value in the _all field. This means that, when querying the _all field, words that originated from the title field will have a higher score than words that originated in the content field. This functionality comes at a cost: queries on the _all field are slower when field boosting is used.

deprecated[5.0.0, "index time boost is deprecated. Instead, the field mapping boost is applied at query time. For indices created before 5.0.0 the boost will still be applied at index time."]

Data is not always clean. Depending on how it is produced a number might be rendered in the JSON body as a true JSON number, e.g. 5, but it might also be rendered as a string, e.g. "5". Alternatively, a number that should be an integer might instead be rendered as a floating point, e.g. 5.0, or even "5.0".

Coercion attempts to clean up dirty values to fit the datatype of a field. For instance:

For instance:

The copy_to parameter allows you to create custom _all fields. In other words, the values of multiple fields can be copied into a group field, which can then be queried as a single field. For instance, the first_name and last_name fields can be copied to the full_name field as follows:

Some important points:

Most fields are indexed by default, which makes them searchable. The inverted index allows queries to look up the search term in unique sorted list of terms, and from that immediately have access to the list of documents that contain the term.

Sorting, aggregations, and access to field values in scripts requires a different data access pattern. Instead of looking up the term and finding documents, we need to be able to look up the document and find the terms that it has in a field.

Doc values are the on-disk data structure, built at document index time, which makes this data access pattern possible. They store the same values as the _source but in a column-oriented fashion that is way more efficient for sorting and aggregations. Doc values are supported on almost all field types, with the notable exception of analyzed string fields.

All fields which support doc values have them enabled by default. If you are sure that you don’t need to sort or aggregate on a field, or access the field value from a script, you can disable doc values in order to save disk space:

By default, fields can be added dynamically to a document, or to inner objects within a document, just by indexing a document containing the new field. For instance:

The details of how new fields are detected and added to the mapping is explained in Dynamic Mapping.

The dynamic setting controls whether new fields can be added dynamically or not. It accepts three settings:

The dynamic setting may be set at the mapping type level, and on each inner object. Inner objects inherit the setting from their parent object or from the mapping type. For instance:

Elasticsearch tries to index all of the fields you give it, but sometimes you want to just store the field without indexing it. For instance, imagine that you are using Elasticsearch as a web session store. You may want to index the session ID and last update time, but you don’t need to query or run aggregations on the session data itself.

The enabled setting, which can be applied only to the mapping type and to object fields, causes Elasticsearch to skip parsing of the contents of the field entirely. The JSON can still be retrieved from the _source field, but it is not searchable or stored in any other way:

The entire mapping type may be disabled as well, in which case the document is stored in the _source field, which means it can be retrieved, but none of its contents are indexed in any way:

The enabled setting for existing fields and the top-level mapping definition cannot be updated.

Most fields are indexed by default, which makes them searchable. Sorting, aggregations, and accessing field values in scripts, however, requires a different access pattern from search.

Search needs to answer the question "Which documents contain this term?", while sorting and aggregations need to answer a different question: "What is the value of this field for this document?".

Most fields can use index-time, on-disk doc_values for this data access pattern, but text fields do not support doc_values.

Instead, text fields use a query-time in-memory data structure called fielddata. This data structure is built on demand the first time that a field is used for aggregations, sorting, or in a script. It is built by reading the entire inverted index for each segment from disk, inverting the term ↔︎ document relationship, and storing the result in memory, in the JVM heap.

In JSON documents, dates are represented as strings. Elasticsearch uses a set of preconfigured formats to recognize and parse these strings into a long value representing milliseconds-since-the-epoch in UTC.

Besides the built-in formats, your own custom formats can be specified using the familiar yyyy/MM/dd syntax:

Many APIs which support date values also support date math expressions, such as now-1m/d — the current time, minus one month, rounded down to the nearest day.

Strings longer than the ignore_above setting will not be indexed or stored. For arrays of strings, ignore_above will be applied for each array element separately and string elements longer than ignore_above will not be indexed or stored.

This option is also useful for protecting against Lucene’s term byte-length limit of 32766.

Sometimes you don’t have much control over the data that you receive. One user may send a login field that is a date, and another sends a login field that is an email address.

Trying to index the wrong datatype into a field throws an exception by default, and rejects the whole document. The ignore_malformed parameter, if set to true, allows the exception to be ignored. The malformed field is not indexed, but other fields in the document are processed normally.

For example:

The index option controls whether field values are indexed. It accepts true or false and defaults to true. Fields that are not indexed are not queryable.

The index_options parameter controls what information is added to the inverted index, for search and highlighting purposes. It accepts the following settings:

Analyzed string fields use positions as the default, and all other fields use docs as the default.

If enabled, two-term word combinations ('shingles') are indexed into a separate field. This allows exact phrase queries (no slop) to run more efficiently, at the expense of a larger index. Note that this works best when stopwords are not removed, as phrases containing stopwords will not use the subsidiary field and will fall back to a standard phrase query. Accepts true or false (default).

The index_prefixes parameter enables the indexing of term prefixes to speed up prefix searches. It accepts the following optional settings:

This example creates a text field using the default prefix length settings:

This example uses custom prefix length settings:

It is often useful to index the same field in different ways for different purposes. This is the purpose of multi-fields. For instance, a string field could be mapped as a text field for full-text search, and as a keyword field for sorting or aggregations:

Norms store various normalization factors that are later used at query time in order to compute the score of a document relatively to a query.

Although useful for scoring, norms also require quite a lot of disk (typically in the order of one byte per document per field in your index, even for documents that don’t have this specific field). As a consequence, if you don’t need scoring on a specific field, you should disable norms on that field. In particular, this is the case for fields that are used solely for filtering or aggregations.

Norms can be disabled (but not reenabled) after the fact, using the PUT mapping API like so:

A null value cannot be indexed or searched. When a field is set to null, (or an empty array or an array of null values) it is treated as though that field has no values.

The null_value parameter allows you to replace explicit null values with the specified value so that it can be indexed and searched. For instance:

Analyzed text fields take term positions into account, in order to be able to support proximity or phrase queries. When indexing text fields with multiple values a "fake" gap is added between the values to prevent most phrase queries from matching across the values. The size of this gap is configured using position_increment_gap and defaults to 100.

For example:

The position_increment_gap can be specified in the mapping. For instance:

Type mappings, object fields and nested fields contain sub-fields, called properties. These properties may be of any datatype, including object and nested. Properties can be added:

Below is an example of adding properties to a mapping type, an object field, and a nested field:

Usually, the same analyzer should be applied at index time and at search time, to ensure that the terms in the query are in the same format as the terms in the inverted index.

Sometimes, though, it can make sense to use a different analyzer at search time, such as when using the edge_ngram tokenizer for autocomplete.

By default, queries will use the analyzer defined in the field mapping, but this can be overridden with the search_analyzer setting:

See {defguide}/_index_time_search_as_you_type.html[Index time search-as-you- type] for a full explanation of this example.

Elasticsearch allows you to configure a scoring algorithm or similarity per field. The similarity setting provides a simple way of choosing a similarity algorithm other than the default BM25, such as TF/IDF.

Similarities are mostly useful for text fields, but can also apply to other field types.

Custom similarities can be configured by tuning the parameters of the built-in similarities. For more details about this expert options, see the similarity module.

The only similarities which can be used out of the box, without any further configuration are:

The similarity can be set on the field level when a field is first created, as follows:

By default, field values are indexed to make them searchable, but they are not stored. This means that the field can be queried, but the original field value cannot be retrieved.

Usually this doesn’t matter. The field value is already part of the _source field, which is stored by default. If you only want to retrieve the value of a single field or of a few fields, instead of the whole _source, then this can be achieved with source filtering.

In certain situations it can make sense to store a field. For instance, if you have a document with a title, a date, and a very large content field, you may want to retrieve just the title and the date without having to extract those fields from a large _source field:

Another situation where it can make sense to make a field stored is for those that don’t appear in the _source field (such as copy_to fields).

Term vectors contain information about the terms produced by the analysis process, including:

These term vectors can be stored so that they can be retrieved for a particular document.

The term_vector setting accepts:

The fast vector highlighter requires with_positions_offsets. The term vectors API can retrieve whatever is stored.

By default, when a previously unseen field is found in a document, Elasticsearch will add the new field to the type mapping. This behaviour can be disabled, both at the document and at the object level, by setting the dynamic parameter to false (to ignore new fields) or to strict (to throw an exception if an unknown field is encountered).

Assuming dynamic field mapping is enabled, some simple rules are used to determine which datatype the field should have:

These are the only field datatypes that are dynamically detected. All other datatypes must be mapped explicitly.

Besides the options listed below, dynamic field mapping rules can be further customised with dynamic_templates.

Dynamic templates allow you to define custom mappings that can be applied to dynamically added fields based on:

The original field name {name} and the detected datatype {dynamic_type} template variables can be used in the mapping specification as placeholders.

Dynamic templates are specified as an array of named objects:

Templates are processed in order — the first matching template wins. When putting new dynamic templates through the put mapping API, all existing templates are overwritten. This allows for dynamic templates to be reordered or deleted after they were initially added.

deprecated[6.0.0,See Removal of mapping types]

The default mapping, which will be used as the base mapping for a new mapping type, can be customised by adding a mapping type with the name default to an index, either when creating the index or later on with the PUT mapping API.

The documentation for this feature has been removed as it no longer makes sense in 6.x where there can be only a single type per index.