<commit_before>[role="xpack"]
[testenv="basic"]
[[indices-reload-analyzers]]
== Reload Search Analyzers

experimental[]

Reloads search analyzers and its 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]
--------------------------------------------------
PUT /my_index
{
    "settings": {
        "index" : {
            "analysis" : {
                "analyzer" : {
                    "my_synonyms" : {
                        "tokenizer" : "whitespace",
                        "filter" : ["synonym"]
                    }
                },
                "filter" : {
                    "synonym" : {
                        "type" : "synonym",
                        "synonyms_path" : "analysis/synonym.txt",
                        "updateable" : true <1>
                    }
                }
            }
        }
    },
    "mappings": {
        "properties": {
            "text": {
                "type": "text",
                "analyzer" : "standard",
                "search_analyzer": "my_synonyms" <2>
            }
        }
    }
}
--------------------------------------------------

<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.

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.

[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:

[source,console-result]
--------------------------------------------------
{
    "_shards" : {
        "total" : 2,
        "successful" : 2,
        "failed" : 0
    },
    "reload_details" : [
        {
            "index" : "my_index",
            "reloaded_analyzers" : [
                "my_synonyms" 
            ],
            "reloaded_node_ids" : [
                "mfdqTXn_T7SGr2Ho2KT8uw"
            ]
        }
    ]
}
--------------------------------------------------
// TEST[continued]
// 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.<commit_msg>[DOCS] Reformat reload search analyzers API docs (#47824)<commit_after>[role="xpack"]
[testenv="basic"]
[[indices-reload-analyzers]]
== Reload search analyzers API
++++
<titleabbrev>Reload search analyzers</titleabbrev>
++++

experimental::[]

Reloads an index's <<search-analyzer,search analyzers>> and their resources.

[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]
--------------------------------------------------
PUT /my_index
{
    "settings": {
        "index" : {
            "analysis" : {
                "analyzer" : {
                    "my_synonyms" : {
                        "tokenizer" : "whitespace",
                        "filter" : ["synonym"]
                    }
                },
                "filter" : {
                    "synonym" : {
                        "type" : "synonym_graph",
                        "synonyms_path" : "analysis/synonym.txt", <1>
                        "updateable" : true <2>
                    }
                }
            }
        }
    },
    "mappings": {
        "properties": {
            "text": {
                "type": "text",
                "analyzer" : "standard",
                "search_analyzer": "my_synonyms" <3>
            }
        }
    }
}
--------------------------------------------------

<1> Includes a synonym file.
<2> Marks the token filter as updateable.
<3> Marks the analyzer as a search analyzer.

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 API returns the following response.

[source,console-result]
--------------------------------------------------
{
    "_shards" : {
        "total" : 2,
        "successful" : 2,
        "failed" : 0
    },
    "reload_details" : [
        {
            "index" : "my_index",
            "reloaded_analyzers" : [
                "my_synonyms" 
            ],
            "reloaded_node_ids" : [
                "mfdqTXn_T7SGr2Ho2KT8uw"
            ]
        }
    ]
}
--------------------------------------------------
// TEST[continued]
// 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/]
{'fraction_non_alphanumeric': 0.18786595241061418, 'fraction_numerical': 0.005606079481749097, 'mean_word_length': 1.835747085835394, 'pattern_counts': {'":': 12, '<': 34, '<?xml version=': 0, '>': 34, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4887720', 'n_tokens_mistral': 2357, 'n_tokens_neox': 2248, 'n_words': 644}