ESQL: Hide some "extras" from docs (#124763) (#126126)

Hides some of the "extra" lines from ESQL's documentation. These lines
are required to make the documentation into nice tests which is
important to make sure the docs don't get out of date. But readers don't
need to see them.

docs/reference/esql/functions/examples/qstr.asciidoc

@@ -1,6 +1,6 @@
 // This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
 
-*Example*
+*Examples*
 
 [source.merge.styled,esql]
 ----
@@ -10,4 +10,12 @@ include::{esql-specs}/qstr-function.csv-spec[tag=qstr-with-field]
 |===
 include::{esql-specs}/qstr-function.csv-spec[tag=qstr-with-field-result]
 |===
+[source.merge.styled,esql]
+----
+include::{esql-specs}/qstr-function.csv-spec[tag=qstr-with-options]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/qstr-function.csv-spec[tag=qstr-with-options-result]
+|===
 

docs/reference/esql/functions/functionNamedParams/qstr.asciidoc

@@ -7,21 +7,21 @@
 name | types | description
 max_determinized_states | [integer] | Maximum number of automaton states required for the query. Default is 10000.
 fuzziness | [keyword] | Maximum edit distance allowed for matching.
-auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms.
-phrase_slop | [integer] | Maximum number of positions allowed between matching tokens for phrases.
+auto_generate_synonyms_phrase_query | [boolean] | If true, match phrase queries are automatically created for multi-term synonyms. Defaults to true.
+phrase_slop | [integer] | Maximum number of positions allowed between matching tokens for phrases. Defaults to 0 (which means exact matches are required).
 default_field | [keyword] | Default field to search if no field is provided in the query string. Supports wildcards (*).
-allow_leading_wildcard | [boolean] | If true, the wildcard characters * and ? are allowed as the first character of the query string.
+allow_leading_wildcard | [boolean] | If true, the wildcard characters * and ? are allowed as the first character of the query string. Defaults to true.
 minimum_should_match | [string] | Minimum number of clauses that must match for a document to be returned.
-fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba).
+fuzzy_transpositions | [boolean] | If true, edits for fuzzy matching include transpositions of two adjacent characters (ab → ba). Defaults to true.
 fuzzy_prefix_length | [integer] | Number of beginning characters left unchanged for fuzzy matching. Defaults to 0.
 time_zone | [keyword] | Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query string to UTC.
-lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned.
+lenient | [boolean] | If false, format-based errors, such as providing a text query value for a numeric field, are returned. Defaults to false.
 rewrite | [keyword] | Method used to rewrite the query.
 default_operator | [keyword] | Default boolean logic used to interpret text in the query string if no operators are specified.
-analyzer | [keyword] | Analyzer used to convert the text in the query value into token.
+analyzer | [keyword] | Analyzer used to convert the text in the query value into token. Defaults to the index-time analyzer mapped for the default_field.
 fuzzy_max_expansions | [integer] | Maximum number of terms to which the query expands for fuzzy matching. Defaults to 50.
-quote_analyzer | [keyword] | Analyzer used to convert quoted text in the query string into tokens.
-allow_wildcard | [boolean] | If true, the query attempts to analyze wildcard terms in the query string.
+quote_analyzer | [keyword] | Analyzer used to convert quoted text in the query string into tokens. Defaults to the search_quote_analyzer mapped for the default_field.
+allow_wildcard | [boolean] | If true, the query attempts to analyze wildcard terms in the query string. Defaults to false. 
 boost | [float] | Floating point number used to decrease or increase the relevance scores of the query.
 quote_field_suffix | [keyword] | Suffix appended to quoted text in the query string.
 enable_position_increments | [boolean] | If true, enable position increments in queries constructed from a query_string search. Defaults to true.

docs/reference/esql/functions/kibana/definition/bucket.json

@@ -1590,16 +1590,16 @@
     }
   ],
   "examples" : [
-    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")\n| SORT hire_date",
+    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")",
     "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hires_per_month = COUNT(*) BY month = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")\n| SORT month",
-    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")\n| SORT week",
+    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")",
     "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 1 week)\n| SORT week",
     "FROM employees\n| STATS COUNT(*) by bs = BUCKET(salary, 20, 25324, 74999)\n| SORT bs",
     "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS c = COUNT(1) BY b = BUCKET(salary, 5000.)\n| SORT b",
     "FROM sample_data \n| WHERE @timestamp >= NOW() - 1 day and @timestamp < NOW()\n| STATS COUNT(*) BY bucket = BUCKET(@timestamp, 25, NOW() - 1 day, NOW())",
-    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")\n| SORT bucket",
+    "FROM employees\n| WHERE hire_date >= \"1985-01-01T00:00:00Z\" AND hire_date < \"1986-01-01T00:00:00Z\"\n| STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, \"1985-01-01T00:00:00Z\", \"1986-01-01T00:00:00Z\")",
     "FROM employees\n| STATS s1 = b1 + 1, s2 = BUCKET(salary / 1000 + 999, 50.) + 2 BY b1 = BUCKET(salary / 100 + 99, 50.), b2 = BUCKET(salary / 1000 + 999, 50.)\n| SORT b1, b2\n| KEEP s1, b1, s2, b2",
-    "FROM employees\n| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR\n| EVAL d_count = MV_COUNT(dates)\n| SORT d_count, b\n| LIMIT 3"
+    "FROM employees\n| STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR\n| EVAL d_count = MV_COUNT(dates)"
   ],
   "preview" : false,
   "snapshot_only" : false

docs/reference/esql/functions/kibana/definition/kql.json

@@ -30,7 +30,7 @@
     }
   ],
   "examples" : [
-    "FROM books \n| WHERE KQL(\"author: Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5"
+    "FROM books \n| WHERE KQL(\"author: Faulkner\")\n| KEEP book_no, author \n| SORT book_no "
   ],
   "preview" : true,
   "snapshot_only" : false

docs/reference/esql/functions/kibana/definition/left.json

@@ -42,7 +42,7 @@
     }
   ],
   "examples" : [
-    "FROM employees\n| KEEP last_name\n| EVAL left = LEFT(last_name, 3)\n| SORT last_name ASC\n| LIMIT 5"
+    "FROM employees\n| KEEP last_name\n| EVAL left = LEFT(last_name, 3)"
   ],
   "preview" : false,
   "snapshot_only" : false

docs/reference/esql/functions/kibana/definition/match.json

@@ -731,7 +731,7 @@
     }
   ],
   "examples" : [
-    "FROM books \n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5",
+    "FROM books \n| WHERE MATCH(author, \"Faulkner\")",
     "FROM books \n| WHERE MATCH(title, \"Hobbit Back Again\", {\"operator\": \"AND\"})\n| KEEP title;"
   ],
   "preview" : true,

docs/reference/esql/functions/kibana/definition/match_operator.json

@@ -529,7 +529,7 @@
     }
   ],
   "examples" : [
-    "FROM books \n| WHERE MATCH(author, \"Faulkner\")\n| KEEP book_no, author \n| SORT book_no \n| LIMIT 5"
+    "FROM books \n| WHERE MATCH(author, \"Faulkner\")"
   ],
   "preview" : true,
   "snapshot_only" : false

docs/reference/esql/functions/kibana/definition/right.json

@@ -42,7 +42,7 @@
     }
   ],
   "examples" : [
-    "FROM employees\n| KEEP last_name\n| EVAL right = RIGHT(last_name, 3)\n| SORT last_name ASC\n| LIMIT 5"
+    "FROM employees\n| KEEP last_name\n| EVAL right = RIGHT(last_name, 3)"
   ],
   "preview" : false,
   "snapshot_only" : false

docs/reference/esql/functions/kibana/definition/term.json

@@ -78,7 +78,7 @@
     }
   ],
   "examples" : [
-    "FROM books \n| WHERE TERM(author, \"gabriel\")  \n| KEEP book_no, title\n| LIMIT 3;"
+    "FROM books \n| WHERE TERM(author, \"gabriel\")  "
   ],
   "preview" : true,
   "snapshot_only" : true

docs/reference/esql/functions/kibana/docs/bucket.md

@@ -10,5 +10,4 @@ The size of the buckets can either be provided directly, or chosen based on a re
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
 | STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
-| SORT hire_date
 ```

docs/reference/esql/functions/kibana/docs/kql.md

@@ -10,5 +10,4 @@ FROM books
 | WHERE KQL("author: Faulkner")
 | KEEP book_no, author 
 | SORT book_no 
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/left.md

@@ -9,6 +9,4 @@ Returns the substring that extracts 'length' chars from 'string' starting from t
 FROM employees
 | KEEP last_name
 | EVAL left = LEFT(last_name, 3)
-| SORT last_name ASC
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/match.md

@@ -19,7 +19,4 @@ For a simplified syntax, you can use the <<esql-search-operators,match operator>
 ```
 FROM books 
 | WHERE MATCH(author, "Faulkner")
-| KEEP book_no, author 
-| SORT book_no 
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/match_operator.md

@@ -16,7 +16,4 @@ For using the function syntax, or adding <<match-field-params,match query parame
 ```
 FROM books 
 | WHERE MATCH(author, "Faulkner")
-| KEEP book_no, author 
-| SORT book_no 
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/qstr.md

@@ -8,7 +8,4 @@ Performs a <<query-dsl-query-string-query,query string query>>. Returns true if
 ```
 FROM books 
 | WHERE QSTR("author: Faulkner")
-| KEEP book_no, author 
-| SORT book_no 
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/right.md

@@ -9,6 +9,4 @@ Return the substring that extracts 'length' chars from 'str' starting from the r
 FROM employees
 | KEEP last_name
 | EVAL right = RIGHT(last_name, 3)
-| SORT last_name ASC
-| LIMIT 5
 ```

docs/reference/esql/functions/kibana/docs/term.md

@@ -8,6 +8,4 @@ Performs a Term query on the specified field. Returns true if the provided term
 ```
 FROM books 
 | WHERE TERM(author, "gabriel")  
-| KEEP book_no, title
-| LIMIT 3;
 ```

docs/reference/esql/functions/layout/qstr.asciidoc

@@ -14,4 +14,5 @@ image::esql/functions/signature/qstr.svg[Embedded,opts=inline]
 include::../parameters/qstr.asciidoc[]
 include::../description/qstr.asciidoc[]
 include::../types/qstr.asciidoc[]
+include::../functionNamedParams/qstr.asciidoc[]
 include::../examples/qstr.asciidoc[]

docs/reference/esql/functions/parameters/qstr.asciidoc

@@ -4,3 +4,6 @@
 
 `query`::
 Query string in Lucene query string format.
+
+`options`::
+(Optional) Additional options for Query String as <<esql-function-named-params,function named parameters>>. See <<query-dsl-query-string-query,query string query>> for more information.

docs/reference/esql/functions/signature/qstr.svg

@@ -1 +1 @@
-<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="252" height="46" viewbox="0 0 252 46"><defs><style type="text/css">#guide .c{fill:none;stroke:#222222;}#guide .k{fill:#000000;font-family:Roboto Mono,Sans-serif;font-size:20px;}#guide .s{fill:#e4f4ff;stroke:#222222;}#guide .syn{fill:#8D8D8D;font-family:Roboto Mono,Sans-serif;font-size:20px;}</style></defs><path class="c" d="M0 31h5m68 0h10m32 0h10m80 0h10m32 0h5"/><rect class="s" x="5" y="5" width="68" height="36"/><text class="k" x="15" y="31">QSTR</text><rect class="s" x="83" y="5" width="32" height="36" rx="7"/><text class="syn" x="93" y="31">(</text><rect class="s" x="125" y="5" width="80" height="36" rx="7"/><text class="k" x="135" y="31">query</text><rect class="s" x="215" y="5" width="32" height="36" rx="7"/><text class="syn" x="225" y="31">)</text></svg>
+<svg version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" width="408" height="46" viewbox="0 0 408 46"><defs><style type="text/css">#guide .c{fill:none;stroke:#222222;}#guide .k{fill:#000000;font-family:Roboto Mono,Sans-serif;font-size:20px;}#guide .s{fill:#e4f4ff;stroke:#222222;}#guide .syn{fill:#8D8D8D;font-family:Roboto Mono,Sans-serif;font-size:20px;}</style></defs><path class="c" d="M0 31h5m68 0h10m32 0h10m80 0h10m32 0h10m104 0h10m32 0h5"/><rect class="s" x="5" y="5" width="68" height="36"/><text class="k" x="15" y="31">QSTR</text><rect class="s" x="83" y="5" width="32" height="36" rx="7"/><text class="syn" x="93" y="31">(</text><rect class="s" x="125" y="5" width="80" height="36" rx="7"/><text class="k" x="135" y="31">query</text><rect class="s" x="215" y="5" width="32" height="36" rx="7"/><text class="syn" x="225" y="31">,</text><rect class="s" x="257" y="5" width="104" height="36" rx="7"/><text class="k" x="267" y="31">options</text><rect class="s" x="371" y="5" width="32" height="36" rx="7"/><text class="syn" x="381" y="31">)</text></svg>

docs/reference/esql/functions/types/qstr.asciidoc

@@ -4,7 +4,7 @@
 
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-query | result
-keyword | boolean
-text | boolean
+query | options | result
+keyword | named parameters | boolean
+text | named parameters | boolean
 |===

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

@@ -130,8 +130,8 @@ bucketMonthInAgg#[skip:-8.13.99, reason:BUCKET renamed in 8.14]
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
 | STATS AVG(salary) BY bucket = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
-| SORT bucket
 // end::bucket_in_agg[]
+| SORT bucket
 ;
 
 // tag::bucket_in_agg-result[]
@@ -150,9 +150,9 @@ bucketWithOffset#[skip:-8.13.99, reason:BUCKET renamed in 8.14]
 FROM employees
 | STATS dates = MV_SORT(VALUES(birth_date)) BY b = BUCKET(birth_date + 1 HOUR, 1 YEAR) - 1 HOUR
 | EVAL d_count = MV_COUNT(dates)
+// end::bucketWithOffset[]
 | SORT d_count, b
 | LIMIT 3
-// end::bucketWithOffset[]
 ;
 
 // tag::bucketWithOffset-result[]
@@ -168,8 +168,8 @@ docsBucketMonth#[skip:-8.13.99, reason:BUCKET renamed in 8.14]
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
 | STATS hire_date = MV_SORT(VALUES(hire_date)) BY month = BUCKET(hire_date, 20, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
-| SORT hire_date
 //end::docsBucketMonth[]
+| SORT hire_date
 ;
 
 //tag::docsBucketMonth-result[]
@@ -208,8 +208,8 @@ docsBucketWeeklyHistogram#[skip:-8.13.99, reason:BUCKET renamed in 8.14]
 FROM employees
 | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
 | STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, 100, "1985-01-01T00:00:00Z", "1986-01-01T00:00:00Z")
-| SORT week
 //end::docsBucketWeeklyHistogram[]
+| SORT week
 ;
 
 //tag::docsBucketWeeklyHistogram-result[]

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

@@ -10,8 +10,10 @@ FROM books
 | WHERE KQL("author: Faulkner")
 | KEEP book_no, author 
 | SORT book_no 
-| LIMIT 5
 // end::kql-with-field[]
+| KEEP book_no, author
+| SORT book_no
+| LIMIT 5
 ;
 
 // tag::kql-with-field-result[]

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

@@ -8,10 +8,10 @@ required_capability: match_function
 // tag::match-with-field[]
 FROM books 
 | WHERE MATCH(author, "Faulkner")
-| KEEP book_no, author 
-| SORT book_no 
-| LIMIT 5
 // end::match-with-field[]
+| KEEP book_no, author
+| SORT book_no
+| LIMIT 5
 ;
 
 // tag::match-with-field-result[]

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

@@ -8,10 +8,10 @@ required_capability: match_operator_colon
 // tag::match-with-field[]
 FROM books 
 | WHERE author:"Faulkner"
+// end::match-with-field[]
 | KEEP book_no, author 
 | SORT book_no 
 | LIMIT 5
-// end::match-with-field[]
 ;
 
 // tag::match-with-field-result[]

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

@@ -28,10 +28,10 @@ isNullForDocs
 // tag::is-null[]
 FROM employees
 | WHERE birth_date IS NULL
+// end::is-null[]
 | KEEP first_name, last_name
 | SORT first_name
 | LIMIT 3
-// end::is-null[]
 ;
 
 // tag::is-null-result[]

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

@@ -8,10 +8,10 @@ required_capability: qstr_function
 // tag::qstr-with-field[]
 FROM books 
 | WHERE QSTR("author: Faulkner")
+// end::qstr-with-field[]
 | KEEP book_no, author 
 | SORT book_no 
 | LIMIT 5
-// end::qstr-with-field[]
 ;
 
 // tag::qstr-with-field-result[]
@@ -197,15 +197,17 @@ required_capability: query_string_function_options
 // tag::qstr-with-options[]
 FROM books 
 | WHERE QSTR("title: Hobbjt~", {"fuzziness": 2})
+// end::qstr-with-options[]
 | KEEP book_no, title 
 | SORT book_no 
 | LIMIT 5
-// end::qstr-with-options[]
 ;
 ignoreOrder: true
 
+// tag::qstr-with-options-result[]
 book_no:keyword | title:text                        
 4289            | Poems from the Hobbit             
 6405            | The Hobbit or There and Back Again
 7480            | The Hobbit                                     
+// end::qstr-with-options-result[]
 ;

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

@@ -1127,9 +1127,9 @@ left
 FROM employees
 | KEEP last_name
 | EVAL left = LEFT(last_name, 3)
+// end::left[]
 | SORT last_name ASC
 | LIMIT 5
-// end::left[]
 ;
 
 // tag::left-result[]
@@ -1147,9 +1147,9 @@ right
 FROM employees
 | KEEP last_name
 | EVAL right = RIGHT(last_name, 3)
+// end::right[]
 | SORT last_name ASC
 | LIMIT 5
-// end::right[]
 ;
 
 // tag::right-result[]

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

@@ -8,9 +8,11 @@ required_capability: term_function
 // tag::term-with-field[]
 FROM books 
 | WHERE TERM(author, "gabriel")  
+// end::term-with-field[]
 | KEEP book_no, title
-| LIMIT 3;
 // end::term-with-field[]
+| LIMIT 3
+;
 ignoreOrder:true
 
 book_no:keyword | title:text