[DOCS] Combine keyword family docs (#61662) (#61813)

Author: jrodewig

docs/reference/eql/eql-search-api.asciidoc

@@ -146,7 +146,7 @@ Common Schema (ECS)]. If a data stream or index does not contain the
 `event.category` field, this value is required.
 +
 The event category field is typically mapped as a <<keyword,`keyword`>> or
-<<constant-keyword,constant keyword>> field.
+<<constant-keyword-field-type,constant keyword>> field.
 
 `fetch_size`::
 (Optional, integer)

docs/reference/eql/eql.asciidoc

@@ -390,7 +390,7 @@ in the search request using the `timestamp_field` or `event_category_field`
 parameters.
 
 The event category field is typically mapped as a <<keyword,`keyword`>> or
-<<constant-keyword,constant keyword>> field. The timestamp field is typically
+<<constant-keyword-field-type,constant keyword>> field. The timestamp field is typically
 mapped as a <<date,`date`>> or <<date_nanos,`date_nanos`>> field.
 
 NOTE: You cannot use a <<nested,`nested`>> field or the sub-fields of a `nested`

docs/reference/eql/functions.asciidoc

@@ -110,9 +110,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<left>`::
@@ -126,9 +126,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<right>`::
@@ -142,9 +142,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<greedy_matching>`::
@@ -400,9 +400,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<substring>`::
@@ -415,9 +415,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 *Returns:* boolean or `null`
@@ -478,9 +478,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<substring>`::
@@ -499,9 +499,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<start_pos>`::
@@ -565,9 +565,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 *Returns:* integer or `null`
@@ -615,9 +615,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<reg_exp>`::
@@ -812,9 +812,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 
 If this argument is `null`, the function returns `null`.
 --
@@ -880,9 +880,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<substring>`::
@@ -895,9 +895,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 *Returns:* boolean or `null`
@@ -979,9 +979,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 
 `<substring>`::
 (Required, string or `null`)
@@ -991,9 +991,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 
 *Returns:* boolean or `null`
 
@@ -1148,9 +1148,9 @@ If using a field as the argument, this parameter supports only the following
 field data types:
 
 * <<keyword,`keyword`>>
-* <<constant-keyword,`constant_keyword`>>
+* <<constant-keyword-field-type,`constant_keyword`>>
 * <<text,`text`>> field with a <<keyword,`keyword`>> or
-  <<constant-keyword,`constant_keyword`>> sub-field
+  <<constant-keyword-field-type,`constant_keyword`>> sub-field
 --
 
 `<wildcard_exp>`::

docs/reference/how-to/search-speed.asciidoc

@@ -423,7 +423,7 @@ run prefix queries. If your use-case involves running lots of prefix queries,
 this can speed up queries significantly.
 
 [[faster-filtering-with-constant-keyword]]
-=== Use <<constant-keyword,`constant_keyword`>> to speed up filtering
+=== Use <<constant-keyword-field-type,`constant_keyword`>> to speed up filtering
 
 There is a general rule that the cost of a filter is mostly a function of the
 number of matched documents. Imagine that you have an index containing cycles.

docs/reference/mapping/types.asciidoc

@@ -24,8 +24,8 @@ type: `boolean`.
 <<binary,`binary`>>::   Binary value encoded as a Base64 string.
 <<boolean,`boolean`>>:: `true` and `false` values.
 Keyword::               The keyword family, including <<keyword, `keyword`>>,
-                        <<constant-keyword,`constant_keyword`>>, and
-                        <<wildcard, `wildcard`>>.
+                        <<constant-keyword-field-type,`constant_keyword`>>, and
+                        <<wildcard-field-type, `wildcard`>>.
 <<number,Numbers>>::    Numeric types, such as `long` and `double`, used to
                         express amounts.
 Dates::                 Date types, including <<date,`date`>> and 
@@ -178,7 +178,3 @@ include::types/text.asciidoc[]
 include::types/token-count.asciidoc[]
 
 include::types/shape.asciidoc[]
-
-include::types/constant-keyword.asciidoc[]
-
-include::types/wildcard.asciidoc[]

docs/reference/mapping/types/constant-keyword.asciidoc

@@ -1,13 +1,11 @@
 [role="xpack"]
 [testenv="basic"]
 
-[[constant-keyword]]
+[discrete]
+[[constant-keyword-field-type]]
 === Constant keyword field type
-++++
-<titleabbrev>Constant keyword</titleabbrev>
-++++
 
-Constant keyword is a specialization of the <<keyword,`keyword`>> field for
+Constant keyword is a specialization of the `keyword` field for
 the case that all documents in the index have the same value.
 
 [source,console]
@@ -71,6 +69,7 @@ document), queries on the field will not match any documents. This includes
 
 The `value` of the field cannot be changed after it has been set.
 
+[discrete]
 [[constant-keyword-params]]
 ==== Parameters for constant keyword fields
 

docs/reference/mapping/types/keyword.asciidoc

@@ -1,20 +1,31 @@
+[testenv="basic"]
 [[keyword]]
-=== Keyword field type
+=== Keyword type family
 ++++
 <titleabbrev>Keyword</titleabbrev>
 ++++
 
-A field to index structured content such as IDs, email addresses, hostnames,
-status codes, zip codes or tags.
+The keyword family includes the following field types:
+
+* <<keyword,`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>>.
 
-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.
+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`>>.
 
-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,`text`>> field.
+TIP: Avoid using keyword fields for full-text search. Use the <<text,`text`>>
+field type instead.
 
-Below is an example of a mapping for a keyword field:
+[discrete]
+[[keyword-field-type]]
+=== Keyword field type
+
+Below is an example of a mapping for a basic `keyword` field:
 
 [source,console]
 --------------------------------
@@ -36,8 +47,9 @@ PUT my-index-000001
 include::numeric.asciidoc[tag=map-ids-as-keyword]
 ====
 
+[discrete]
 [[keyword-params]]
-==== Parameters for keyword fields
+==== Parameters for basic keyword fields
 
 The following parameters are accepted by `keyword` fields:
 
@@ -119,8 +131,6 @@ The following parameters are accepted by `keyword` fields:
 
     Metadata about the field.
 
-NOTE: Indexes imported from 2.x do not support `keyword`. Instead they will
-attempt to downgrade `keyword` into `string`. This allows you to merge modern
-mappings with legacy mappings. Long lived indexes will have to be recreated
-before upgrading to 6.x but mapping downgrade gives you the opportunity to do
-the recreation on your own schedule.
+include::constant-keyword.asciidoc[]
+
+include::wildcard.asciidoc[]

docs/reference/mapping/types/wildcard.asciidoc

@@ -1,10 +1,8 @@
 [role="xpack"]
 [testenv="basic"]
-[[wildcard]]
+[discrete]
+[[wildcard-field-type]]
 === Wildcard field type
-++++
-<titleabbrev>Wildcard</titleabbrev>
-++++
 
 A `wildcard` field stores values optimised for wildcard grep-like queries.
 Wildcard queries are possible on other field types but suffer from constraints:
@@ -52,6 +50,7 @@ GET my-index-000001/_search
 --------------------------------------------------
 
 
+[discrete]
 [[wildcard-params]]
 ==== Parameters for wildcard fields
 
@@ -64,6 +63,7 @@ The following parameters are accepted by `wildcard` fields:
     Do not index any string longer than this value.  Defaults to `2147483647`
     so that all values would be accepted.
 
+[discrete]
 ==== Limitations
 
 * `wildcard` fields are untokenized like keyword fields, so do not support queries that rely on word positions such as phrase queries.

docs/reference/query-dsl.asciidoc

@@ -33,10 +33,10 @@ the stability of the cluster. Those queries can be categorised as follows:
 * Queries that need to do linear scans to identify matches:
 ** <<query-dsl-script-query, `script queries`>>
 * Queries that have a high up-front cost :
-** <<query-dsl-fuzzy-query,`fuzzy queries`>> (except on <<wildcard, `wildcard`>> fields)
-** <<query-dsl-regexp-query,`regexp queries`>> (except on <<wildcard, `wildcard`>> fields)
-** <<query-dsl-prefix-query,`prefix queries`>>  (except on <<wildcard, `wildcard`>> fields or those without <<index-prefixes, `index_prefixes`>>)
-** <<query-dsl-wildcard-query, `wildcard queries`>> (except on <<wildcard, `wildcard`>> fields)
+** <<query-dsl-fuzzy-query,`fuzzy queries`>> (except on <<wildcard-field-type, `wildcard`>> fields)
+** <<query-dsl-regexp-query,`regexp queries`>> (except on <<wildcard-field-type, `wildcard`>> fields)
+** <<query-dsl-prefix-query,`prefix queries`>>  (except on <<wildcard-field-type, `wildcard`>> fields or those without <<index-prefixes, `index_prefixes`>>)
+** <<query-dsl-wildcard-query, `wildcard queries`>> (except on <<wildcard-field-type, `wildcard`>> fields)
 ** <<query-dsl-range-query, `range queries>> on <<text, `text`>> and <<keyword, `keyword`>> fields
 * <<joining-queries, `Joining queries`>>
 * Queries on <<prefix-trees, deprecated geo shapes>>

docs/reference/redirects.asciidoc

@@ -1130,3 +1130,13 @@ See <<joining-queries-notes>>.
 === Percolate query notes
 
 See <<percolate-query-notes>>.
+
+[role="exclude",id="constant-keyword"]
+=== Constant keyword field type
+
+See <<constant-keyword-field-type>>.
+
+[role="exclude",id="wildcard"]
+=== Wildcard field type
+
+See <<wildcard-field-type>>.

docs/reference/search/search-your-data/retrieve-selected-fields.asciidoc

@@ -155,7 +155,7 @@ Only leaf fields are returned -- `fields` does not allow for fetching entire
 objects.
 
 The `fields` parameter handles field types like <<alias, field aliases>> and
-<<constant-keyword, `constant_keyword`>> whose values aren't always present in
+<<constant-keyword-field-type, `constant_keyword`>> whose values aren't always present in
 the `_source`. Other mapping options are also respected, including
 <<ignore-above, `ignore_above`>>, <<ignore-malformed, `ignore_malformed`>> and
 <<null-value, `null_value`>>.

docs/reference/sql/language/data-types.asciidoc

@@ -24,7 +24,7 @@ s|SQL precision
 | <<number, `half_float`>>                 | half_float      | FLOAT       | 3
 | <<number, `scaled_float`>>               | scaled_float    | DOUBLE      | 15
 | <<keyword, `keyword`>>                   | keyword         | VARCHAR     | 32,766
-| <<constant-keyword, `constant_keyword`>> | constant_keyword| VARCHAR     | 32,766
+| <<constant-keyword-field-type, `constant_keyword`>> | constant_keyword| VARCHAR     | 32,766
 | <<text, `text`>>                         | text            | VARCHAR     | 2,147,483,647
 | <<binary, `binary`>>                     | binary          | VARBINARY   | 2,147,483,647
 | <<date, `date`>>                         | datetime        | TIMESTAMP   | 29