[DOCS] Reformat reload search analyzers API docs (#47824) (#47907)

Author: jrodewig

docs/reference/indices/apis/reload-analyzers.asciidoc

@@ -1,15 +1,98 @@
 [role="xpack"]
 [testenv="basic"]
 [[indices-reload-analyzers]]
-== Reload Search Analyzers
+== Reload search analyzers API
+++++
+<titleabbrev>Reload search analyzers</titleabbrev>
+++++
 
-experimental[]
+experimental::[]
 
-Reloads search analyzers and its resources.
+Reloads an index's <<search-analyzer,search analyzers>> and their resources.
 
-Synonym filters (both `synonym` and `synonym_graph`) can be declared as
-updateable if they are only used in <<search-analyzer,search analyzers>> 
-with the `updateable` flag:
+[source,console]
+--------------------------------------------------
+POST /twitter/_reload_search_analyzers
+--------------------------------------------------
+// TEST[setup:twitter]
+
+[discrete]
+[[indices-reload-analyzers-api-request]]
+=== {api-request-title}
+
+`POST /<index>/_reload_search_analyzers`
+
+`GET /<index>/_reload_search_analyzers`
+
+
+[discrete]
+[[indices-reload-analyzers-api-desc]]
+=== {api-description-title}
+
+You can use the reload search analyzers API
+to pick up changes to synonym files
+used in the <<analysis-synonym-graph-tokenfilter,`synonym_graph`>>
+or <<analysis-synonym-tokenfilter,`synonym`>> token filter
+of a <<search-analyzer,search analyzer>>.
+To be eligible,
+the token filter must have an `updateable` flag of `true`
+and only be used in search analyzers.
+
+[NOTE]
+====
+This API does not perform a reload
+for each shard of an index.
+Instead,
+it performs a reload for each node
+containing index shards.
+As a result,
+the total shard count returned by the API
+can differ from the number of index shards.
+
+Because reloading affects every node with an index shard,
+its important to update the synonym file
+on every data node in the cluster,
+including nodes that don't contain a shard replica,
+before using this API.
+This ensures the synonym file is updated
+everywhere in the cluster
+in case shards are relocated
+in the future.
+====
+
+
+[discrete]
+[[indices-reload-analyzers-api-path-params]]
+=== {api-path-parms-title}
+
+`<index>`::
+(Required, string)
+Comma-separated list or wildcard expression of index names
+used to limit the request.
+
+
+[discrete]
+[[indices-reload-analyzers-api-query-params]]
+=== {api-query-parms-title}
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
++
+Defaults to `open`.
+
+include::{docdir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]
+
+
+[discrete]
+[[indices-reload-analyzers-api-example]]
+=== {api-examples-title}
+
+Use the <<indices-create-index, create index API>>
+to create an index with a search analyzer
+that contains an updateable synonym filter.
+
+NOTE: Using the following analyzer as an index analyzer results in an error.
 
 [source,console]
 --------------------------------------------------
@@ -26,9 +109,9 @@ PUT /my_index
                 },
                 "filter" : {
                     "synonym" : {
-                        "type" : "synonym",
-                        "synonyms_path" : "analysis/synonym.txt",
-                        "updateable" : true <1>
+                        "type" : "synonym_graph",
+                        "synonyms_path" : "analysis/synonym.txt", <1>
+                        "updateable" : true <2>
                     }
                 }
             }
@@ -39,38 +122,29 @@ PUT /my_index
             "text": {
                 "type": "text",
                 "analyzer" : "standard",
-                "search_analyzer": "my_synonyms" <2>
+                "search_analyzer": "my_synonyms" <3>
             }
         }
     }
 }
 --------------------------------------------------
 
-<1> Mark the synonym filter as updateable.
-<2> Synonym analyzer is usable as a search_analyzer.
-
-NOTE: Trying to use the above analyzer as an index analyzer will result in an error.
+<1> Includes a synonym file.
+<2> Marks the token filter as updateable.
+<3> Marks the analyzer as a search analyzer.
 
-Using the <<indices-reload-analyzers,analyzer reload API>>, you can trigger reloading of the
-synonym definition. The contents of the configured synonyms file will be reloaded and the
-synonyms definition the filter uses will be updated. 
-
-The `_reload_search_analyzers` API can be run on one or more indices and will trigger 
-reloading of the synonyms from the configured file.
-
-NOTE: Reloading will happen on every node the index has shards, so its important
-to update the synonym file contents on every data node (even the ones that don't currently
-hold shard copies; shards might be relocated there in the future) before calling
-reload to ensure the new state of the file is reflected everywhere in the cluster.
+After updating the synonym file,
+use the <<indices-reload-analyzers,analyzer reload API>>
+to reload the search analyzer
+and pick up the file changes.
 
 [source,console]
 --------------------------------------------------
 POST /my_index/_reload_search_analyzers
 --------------------------------------------------
 // TEST[continued]
 
-The reload request returns information about the nodes it was executed on and the
-analyzers that were reloaded:
+The API returns the following response.
 
 [source,console-result]
 --------------------------------------------------
@@ -97,7 +171,3 @@ analyzers that were reloaded:
 // TESTRESPONSE[s/"total" : 2/"total" : $body._shards.total/]
 // TESTRESPONSE[s/"successful" : 2/"successful" : $body._shards.successful/]
 // TESTRESPONSE[s/mfdqTXn_T7SGr2Ho2KT8uw/$body.reload_details.0.reloaded_node_ids.0/]
-
-NOTE: Reloading does not happen on each shard of an index, but once on each node
-the index has shards on. The total shard count can therefore differ from the number
-of index shards.