[testenv="basic"]
[[keyword]]
=== Keyword type family
++++
<titleabbrev>Keyword</titleabbrev>
++++

The keyword family includes the following field types:

* <<keyword-field-type,`keyword`>>, which is used for structured content such as IDs, email
addresses, hostnames, status codes, zip codes, or tags. 
* <<constant-keyword-field-type,`constant_keyword`>> for keyword fields that always contain
the same value.
* <<wildcard-field-type,`wildcard`>>, which optimizes log lines and similar keyword values
for grep-like <<query-dsl-wildcard-query,wildcard queries>>.

Keyword fields are often used in <<sort-search-results,sorting>>,
<<search-aggregations,aggregations>>, and <<term-level-queries,term-level
queries>>, such as <<query-dsl-term-query,`term`>>.

TIP: Avoid using keyword fields for full-text search. Use the <<text,`text`>>
field type instead.

[discrete]
[[keyword-field-type]]
=== Keyword field type

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

[source,console]
--------------------------------
PUT my-index-000001
{
  "mappings": {
    "properties": {
      "tags": {
        "type":  "keyword"
      }
    }
  }
}
--------------------------------

[TIP]
.Mapping numeric identifiers
====
include::numeric.asciidoc[tag=map-ids-as-keyword]
====

[discrete]
[[keyword-params]]
==== Parameters for basic keyword fields

The following parameters are accepted by `keyword` fields:

[horizontal]

<<mapping-boost,`boost`>>::

    Mapping field-level query time boosting. Accepts a floating point number, defaults
    to `1.0`.

<<doc-values,`doc_values`>>::

    Should the field be stored on disk in a column-stride fashion, so that it
    can later be used for sorting, aggregations, or scripting? Accepts `true`
    (default) or `false`.

<<eager-global-ordinals,`eager_global_ordinals`>>::

    Should global ordinals be loaded eagerly on refresh? Accepts `true` or `false`
    (default). Enabling this is a good idea on fields that are frequently used for
    terms aggregations.

<<multi-fields,`fields`>>::

    Multi-fields allow the same string value to be indexed in multiple ways for
    different purposes, such as one field for search and a multi-field for
    sorting and aggregations.

<<ignore-above,`ignore_above`>>::

    Do not index any string longer than this value.  Defaults to `2147483647`
    so that all values would be accepted. Please however note that default
    dynamic mapping rules create a sub `keyword` field that overrides this
    default by setting `ignore_above: 256`.

<<mapping-index,`index`>>::

    Should the field be searchable? Accepts `true` (default) or `false`.

<<index-options,`index_options`>>::

    What information should be stored in the index, for scoring purposes.
    Defaults to `docs` but can also be set to `freqs` to take term frequency into account
    when computing scores.

<<norms,`norms`>>::

    Whether field-length should be taken into account when scoring queries.
    Accepts `true` or `false` (default).

<<null-value,`null_value`>>::

    Accepts a string value which is substituted for any explicit `null`
    values.  Defaults to `null`, which means the field is treated as missing.

<<mapping-store,`store`>>::

    Whether the field value should be stored and retrievable separately from
    the <<mapping-source-field,`_source`>> field. Accepts `true` or `false`
    (default).

<<similarity,`similarity`>>::

    Which scoring algorithm or _similarity_ should be used. Defaults
    to `BM25`.

<<normalizer,`normalizer`>>::

    How to pre-process the keyword prior to indexing. Defaults to `null`,
    meaning the keyword is kept as-is.

`split_queries_on_whitespace`::

    Whether <<full-text-queries,full text queries>> should split the input on whitespace
    when building a query for this field.
    Accepts `true` or `false` (default).

<<mapping-field-meta,`meta`>>::

    Metadata about the field.

include::constant-keyword.asciidoc[]

include::wildcard.asciidoc[]

