[DOCS] Update `KEEP` command with duplicate precedence rules (#105146)

docs/reference/esql/processing-commands/keep.asciidoc

@@ -10,6 +10,7 @@ KEEP columns
 ----
 
 *Parameters*
+
 `columns`::
 A comma-separated list of columns to keep. Supports wildcards.
 
@@ -18,6 +19,17 @@ A comma-separated list of columns to keep. Supports wildcards.
 The `KEEP` processing command enables you to specify what columns are returned
 and the order in which they are returned.
 
+Precedence rules are applied when a field name matches multiple expressions.
+Fields are added in the order they appear. If one field matches multiple expressions, the following precedence rules apply (from highest to lowest priority):
+
+1. Complete field name (no wildcards)
+2. Partial wildcard expressions (for example: `fieldNam*`)
+3. Wildcard only (`*`)
+
+If a field matches two expressions with the same precedence, the right-most expression wins.
+
+Refer to the examples for illustrations of these precedence rules.
+
 *Examples*
 
 The columns are returned in the specified order:
@@ -38,12 +50,58 @@ columns with a name that matches a pattern:
 ----
 include::{esql-specs}/docs.csv-spec[tag=keepWildcard]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-result]
+|===
 
 The asterisk wildcard (`*`) by itself translates to all columns that do not
-match the other arguments. This query will first return all columns with a name
+match the other arguments.
+
+This query will first return all columns with a name
 that starts with `h`, followed by all other columns:
 
 [source,esql]
 ----
 include::{esql-specs}/docs.csv-spec[tag=keepDoubleWildcard]
 ----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=keep-double-wildcard-result]
+|===
+
+The following examples show how precedence rules work when a field name matches multiple expressions.   
+
+Complete field name has precedence over wildcard expressions:
+
+[source,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=keepCompleteName]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=keep-complete-name-result]
+|===
+
+Wildcard expressions have the same priority, but last one wins (despite being less specific):
+
+[source,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=keepWildcardPrecedence]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-precedence-result]
+|===
+
+A simple wildcard expression `*` has the lowest precedence.
+Output order is determined by the other arguments:
+
+[source,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=keepWildcardLowest]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=keep-wildcard-lowest-result]
+|===

x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec

@@ -61,7 +61,9 @@ FROM employees
 // end::keepWildcard[]
 | LIMIT 0;
 
+// tag::keep-wildcard-result[]
 height:double | height.float:double | height.half_float:double | height.scaled_float:double | hire_date:date
+// end::keep-wildcard-result[]
 ;
 
 docsKeepDoubleWildcard
@@ -71,7 +73,45 @@ FROM employees
 // end::keepDoubleWildcard[]
 | LIMIT 0;
 
+// tag::keep-double-wildcard-result[]
 height:double | height.float:double | height.half_float:double | height.scaled_float:double |       hire_date:date | avg_worked_seconds:long | birth_date:date | emp_no:integer | first_name:keyword | gender:keyword | is_rehired:boolean | job_positions:keyword | languages:integer | languages.byte:integer | languages.long:long | languages.short:integer | last_name:keyword | salary:integer | salary_change:double | salary_change.int:integer |salary_change.keyword:keyword |salary_change.long:long |still_hired:boolean
+// end::keep-double-wildcard-result[]
+;
+
+docsKeepCompleteName#[skip:-8.12.99, reason:duplicate precedence rules added in 8.13]
+// tag::keepCompleteName[]
+FROM employees
+| KEEP first_name, last_name, first_name*
+// end::keepCompleteName[]
+| LIMIT 0;
+
+// tag::keep-complete-name-result[]
+first_name:keyword | last_name:keyword
+// end::keep-complete-name-result[]
+;
+
+docsKeepWildcardPrecedence#[skip:-8.12.99, reason:duplicate precedence rules added in 8.13]
+// tag::keepWildcardPrecedence[]
+FROM employees
+| KEEP first_name*, last_name, first_na*
+// end::keepWildcardPrecedence[]
+| LIMIT 0;
+
+// tag::keep-wildcard-precedence-result[]
+last_name:keyword | first_name:keyword
+// end::keep-wildcard-precedence-result[]
+;
+
+docsKeepWildcardLowest#[skip:-8.12.99, reason:duplicate precedence rules added in 8.13]
+// tag::keepWildcardLowest[]
+FROM employees
+| KEEP *, first_name
+// end::keepWildcardLowest[]
+| LIMIT 0;
+
+// tag::keep-wildcard-lowest-result[]
+avg_worked_seconds:long|birth_date:date|emp_no:integer|gender:keyword|height:double|height.float:double|height.half_float:double|height.scaled_float:double|hire_date:date|is_rehired:boolean|job_positions:keyword|languages:integer|languages.byte:integer|languages.long:long|languages.short:integer|last_name:keyword|salary:integer|salary_change:double|salary_change.int:integer|salary_change.keyword:keyword|salary_change.long:long|still_hired:boolean|first_name:keyword
+// end::keep-wildcard-lowest-result[]
 ;
 
 docsRename