From 2c00b2de361cf2d64eee017e66e812b06fa33fa7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Christoph=20B=C3=BCscher?= <cbuescher@posteo.de>
Date: Tue, 4 Jun 2019 18:48:09 +0200
Subject: [PATCH] Add documentation about reloading search analyzers

---
 .../tokenfilters/synonym-tokenfilter.asciidoc | 41 ++++++++++++++
 .../indices/reload-analyzers.asciidoc         | 56 +++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 docs/reference/indices/reload-analyzers.asciidoc

diff --git a/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc b/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
index 139f7c3ab0ad0..8ffd41267a696 100644
--- a/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
+++ b/docs/reference/analysis/tokenfilters/synonym-tokenfilter.asciidoc
@@ -43,6 +43,10 @@ Additional settings are:
 * `expand` (defaults to `true`).
 * `lenient` (defaults to `false`). If `true` ignores exceptions while parsing the synonym configuration. It is important
 to note that only those synonym rules which cannot get parsed are ignored. For instance consider the following request:
+* `updateable` (defaults to false). If `true`, this marks the filter to be updateable using the 
+<<analyzer reload API,indices-reload-analyzers>>, but it will also restrict the filter to only be usable in 
+<<search analyzers,search-analyzer>>. 
+
 
 [source,js]
 --------------------------------------------------
@@ -181,3 +185,40 @@ error.
 If you need to build analyzers that include both multi-token filters and synonym
 filters, consider using the <<analysis-multiplexer-tokenfilter,multiplexer>> filter,
 with the multi-token filters in one branch and the synonym filter in the other.
+
+=== Updateability of search time synonyms
+
+Synonym filters that are used in <<search analyzers,search-analyzer>> can be marked
+as updateable using the `updateable` flag:
+
+[source,js]
+--------------------------------------------------
+PUT /test_index
+{
+    "settings": {
+        "index" : {
+            "analysis" : {
+                "analyzer" : {
+                    "synonym" : {
+                        "tokenizer" : "whitespace",
+                        "filter" : ["synonym"]
+                    }
+                },
+                "filter" : {
+                    "synonym" : {
+                        "type" : "synonym",
+                        "synonyms_path" : "analysis/synonym.txt",
+                        "updateable" : true
+                    }
+                }
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+
+Using the <<analyzer reload API,indices-reload-analyzers>>, 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. Note that if you trying to use the above
+analyzer as an index analyzer will result in an error.
\ No newline at end of file
diff --git a/docs/reference/indices/reload-analyzers.asciidoc b/docs/reference/indices/reload-analyzers.asciidoc
new file mode 100644
index 0000000000000..ffdd5530d460b
--- /dev/null
+++ b/docs/reference/indices/reload-analyzers.asciidoc
@@ -0,0 +1,56 @@
+[[indices-reload-analyzers]]
+== Reload Search Analyzers
+
+Reloads search analyzers and its resources.
+
+The `_reload_search_analyzers` API can be run on one more indices and will
+reload all search analyzers that contain components that were marked as
+updateable when they were created, such as 
+<<synonym token filters,analysis-synonym-tokenfilter>>:
+
+[source,js]
+--------------------------------------------------
+PUT /test_index
+{
+    "settings": {
+        "index" : {
+            "analysis" : {
+                "analyzer" : {
+                    "synonym" : {
+                        "tokenizer" : "whitespace",
+                        "filter" : ["synonym"]
+                    }
+                },
+                "filter" : {
+                    "synonym" : {
+                        "type" : "synonym",
+                        "synonyms_path" : "analysis/synonym.txt",
+                        "updateable" : true <1>
+                    }
+                }
+            }
+        }
+    },
+    "mappings": {
+        "properties": {
+            "text": {
+                "type": "text",
+                "search_analyzer": "synonym" <2>
+            }
+        }
+    }
+}
+--------------------------------------------------
+// CONSOLE
+
+<1> Mark the synonym filter as updateable.
+<2> Synonym filter is usable as a search_analyzer.
+
+Calling the `_reload_search_analyzers` endpoint will now trigger reloading the
+synonyms from the configured "synonym.txt" file.
+
+[source,js]
+--------------------------------------------------
+POST /test_index/_reload_search_analyzers
+--------------------------------------------------
+// CONSOLE