ESQL: Add docs for the OPTIONS directive (#107013)

This adds the docs for the newly added `OPTIONS` directive to `FROM`.

docs/reference/esql/esql-index-options.asciidoc

@@ -0,0 +1,52 @@
+[[esql-index-options]]
+=== {esql} index options
+
+++++
+<titleabbrev>Index options</titleabbrev>
+++++
+
+The `OPTIONS` directive of the <<esql-from,FROM>> command allows configuring
+the way {esql} accesses the data to be queried. The argument passed to this
+directive is a comma-separated list of option name-value pairs, with the option
+name and the corresponding value double-quoted.
+
+[source,esql]
+----
+FROM index_pattern [OPTIONS "option1"="value1"[,...[,"optionN"="valueN"]]]
+----
+
+These options can only be provided as part of a <<esql-from,FROM>> command,
+and they apply to all the indices provided or matched by an index pattern.
+
+The option names and their values are the same as used by the
+<<search-search-api-query-params,Search API>>, however note that the default
+values may differ.
+
+The currently supported options are:
+
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
++
+Defaults to `true`.
+
+// unlike "allow-no-indices", "index-ignore-unavailable" includes a default
+// in common-parms.asciidoc, which is different from QL's -- we need to
+// provide the full text here.
+`ignore_unavailable`::
+(Optional, Boolean) If `false`, the request returns an error if it targets a
+missing or closed index.
++
+Defaults to `true`.
+
+include::{es-repo-dir}/search/search.asciidoc[tag=search-preference]
+
+*Examples*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/from.csv-spec[tag=convertFromDatetimeWithOptions]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/from.csv-spec[tag=convertFromDatetimeWithOptions-result]
+|===
+

docs/reference/esql/esql-language.asciidoc

@@ -11,6 +11,7 @@ Detailed information about the {esql} language:
 * <<esql-commands>>
 * <<esql-functions>>
 * <<esql-metadata-fields>>
+* <<esql-index-options>>
 * <<esql-multivalued-fields>>
 * <<esql-enrich-data>>
 * <<esql-process-data-with-dissect-and-grok>>
@@ -19,6 +20,7 @@ include::esql-syntax.asciidoc[]
 include::esql-commands.asciidoc[]
 include::esql-functions-operators.asciidoc[]
 include::metadata-fields.asciidoc[]
+include::esql-index-options.asciidoc[]
 include::multivalued-fields.asciidoc[]
 include::esql-process-data-with-dissect-grok.asciidoc[]
-include::esql-enrich-data.asciidoc[]
+include::esql-enrich-data.asciidoc[]

docs/reference/esql/source-commands/from.asciidoc

@@ -6,7 +6,7 @@
 
 [source,esql]
 ----
-FROM index_pattern [METADATA fields]
+FROM index_pattern [METADATA fields] [OPTIONS options]
 ----
 
 *Parameters*
@@ -17,6 +17,10 @@ A list of indices, data streams or aliases. Supports wildcards and date math.
 `fields`::
 A comma-separated list of <<esql-metadata-fields,metadata fields>> to retrieve.
 
+`options`::
+A comma-separated list of <<esql-index-options,index options>> to configure
+data access.
+
 *Description*
 
 The `FROM` source command returns a table with data from a data stream, index,
@@ -82,3 +86,11 @@ Use the optional `METADATA` directive to enable <<esql-metadata-fields,metadata
 ----
 FROM employees METADATA _id
 ----
+
+Use the optional `OPTIONS` directive to specify <<esql-index-options,index access options>>.
+This directive must follow `METADATA`, if both are specified:
+
+[source,esql]
+----
+FROM employees* METADATA _index OPTIONS "ignore_unavailable"="true"
+----

docs/reference/search/search.asciidoc

@@ -141,6 +141,7 @@ When unspecified, the pre-filter phase is executed if any of these conditions is
   - The primary sort of the query targets an indexed field.
 
 [[search-preference]]
+tag::search-preference[]
 `preference`::
 (Optional, string)
 Nodes and shards used for the search. By default, {es} selects from eligible
@@ -177,6 +178,7 @@ Any string that does not start with `_`. If the cluster state and selected
 shards do not change, searches using the same `<custom-string>` value are routed
 to the same shards in the same order.
 ====
+end::search-preference[]
 
 
 [[search-api-query-params-q]]

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

@@ -132,14 +132,19 @@ c:l | name:k
 convertFromDatetimeWithOptions
 required_feature: esql.from_options
 
+// tag::convertFromDatetimeWithOptions[]
   FROM employees OPTIONS "allow_no_indices"="false","preference"="_shards:0"
 | SORT emp_no
 | EVAL hire_double = to_double(hire_date)
 | KEEP emp_no, hire_date, hire_double
-| LIMIT 3;
+| LIMIT 3
+// end::convertFromDatetimeWithOptions[]
+;
 
+// tag::convertFromDatetimeWithOptions-result[]
 emp_no:integer |hire_date:date          |hire_double:double
 10001          |1986-06-26T00:00:00.000Z|5.20128E11
 10002          |1985-11-21T00:00:00.000Z|5.013792E11
 10003          |1986-08-28T00:00:00.000Z|5.255712E11
+// end::convertFromDatetimeWithOptions-result[]
 ;