[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`>> for unstructured machine-generated content.
The `wildcard` type is optimized for fields with large values or high
cardinality.

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.
    Note that this cannot be set if the `script` value is used.

`on_script_error`::

    Defines what to do if the script defined by the `script` parameter
    throws an error at indexing time. Accepts `fail` (default), which
    will cause the entire document to be rejected, and `continue`, which
    will register the field in the document's
    <<mapping-ignored-field,`_ignored`>> metadata field and continue
    indexing. This parameter can only be set if the `script` field is
    also set.

`script`::

    If this parameter is set, then the field will index values generated
    by this script, rather than reading the values directly from the
    source. If a value is set for this field on the input document, then
    the document will be rejected with an error.
    Scripts are in the same format as their
    <<runtime-mapping-fields,runtime equivalent>>. Values emitted by the
    script are normalized as usual, and will be ignored if they are longer
    that the value set on `ignore_above`.

<<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[]

