Synonym Rules APIs docs (#98064)

docs/reference/cluster/stats.asciidoc

@@ -840,6 +840,70 @@ Occurrences of the built-in analyzer in selected nodes.
 `index_count`::
 (integer)
 Number of indices using the built-in analyzer in selected nodes.
+======
+
+`synonyms`::
+(object)
+Contains statistics about synonyms defined in <<analysis-synonym-tokenfilter,synonym>> and <<analysis-synonym-graph-tokenfilter,synonym graph>> token filters configuration.
+
++
+.Properties of `synonyms` objects
+[%collapsible%open]
+======
+`synonyms`::
+(object)
+Inline synonyms defined using `synonyms` configuration in synonym or synonym graph token filters.
+
++
+.Properties of `synonyms` objects
+[%collapsible%open]
+=======
+
+`count`::
+(integer)
+Occurrences of inline synonyms configuration in selected nodes.
+Each inline synonyms configuration will be counted separately, regardless of the synonyms defined.
+Two synonyms configurations with the same synonyms will count as separate ocurrences.
+
+`index_count`::
+(integer)
+Number of indices that use inline synonyms configuration for synonyms token filters.
+=======
+
+`synonyms_path`::
+(object)
+Contains statistics about synonym files defined as `synonyms_path` in <<analysis-synonym-tokenfilter,synonym>> and <<analysis-synonym-graph-tokenfilter,synonym graph>> token filters configuration.
+
++
+.Properties of `synonyms_path` objects
+[%collapsible%open]
+=======
+`count`::
+(integer)
+Occurrences of unique synonym paths in selected nodes.
+
+`index_count`::
+(integer)
+Number of indices that use `synonyms_path` configuration for synonyms token filters.
+=======
+
+`synonyms_sets`::
+(object)
+Contains statistics about synonyms sets configured as `synonyms_set` in <<analysis-synonym-tokenfilter,synonym>> and <<analysis-synonym-graph-tokenfilter,synonym graph>> token filters configuration.
+
++
+.Properties of `synonyms_sets` objects
+[%collapsible%open]
+=======
+`count`::
+(integer)
+Occurrences of unique synonyms sets in selected nodes.
+
+`index_count`::
+(integer)
+Number of indices that use `synonyms_set` configuration for synonyms token filters.
+=======
+
 ======
 =====
 

docs/reference/redirects.asciidoc

@@ -1902,32 +1902,17 @@ Refer to <<data-streams-get-lifecycle,Get data stream lifecycle API>>.
 
 Refer to <<data-streams-delete-lifecycle,Update data stream lifecycle API>>.
 
-[role="exclude",id="get-synonym-rule"]
-=== Get synonym rule API
-
-coming::[8.10.0]
-
 [role="exclude",id="get-synonyms"]
 === Get synonyms set API
 
-coming::[8.10.0]
-
-[role="exclude",id="list-synonyms"]
-=== List synonyms sets API
-
-coming::[8.10.0]
-
-[role="exclude",id="put-synonym-rule"]
-=== Create or update synonym rule API
-
-coming::[8.10.0]
+See <<get-synonyms-set>>
 
 [role="exclude",id="delete-synonyms"]
 === Delete synonyms sets API
 
-coming::[8.10.0]
+See <<delete-synonyms-set>>
 
 [role="exclude",id="put-synonyms"]
-=== Create or update synonyms sets API
+=== Create or delete synonyms sets API
 
-coming::[8.10.0]
+See <<put-synonyms-set>>

docs/reference/synonyms/apis/delete-synonym-rule.asciidoc

@@ -0,0 +1,135 @@
+[[delete-synonym-rule]]
+=== Delete synonym rule
+
+beta::[]
+
+++++
+<titleabbrev>Delete synonym rule</titleabbrev>
+++++
+
+Deletes an individual synonym rule from a synonyms set.
+
+[[delete-synonym-rule-request]]
+==== {api-request-title}
+
+`DELETE _synonyms/<synonyms_set>/<synonym_rule>`
+
+[[delete-synonym-rule-prereqs]]
+==== {api-prereq-title}
+
+Requires the `manage_search_synonyms` cluster privilege.
+
+[[delete-synonym-rule-path-params]]
+==== {api-path-parms-title}
+
+`<synonyms_set>`::
+(Required, string)
+Synonyms set identifier to update.
+
+`<synonym_rule>`::
+(Required, string)
+Synonym rule identifier to delete.
+
+[[delete-synonym-rule-response-codes]]
+==== {api-response-codes-title}
+
+`404` (Missing resources)::
+The `synonyms_set` identifier was not found, or the synonym rule specified by `synonym_rule` was not found in the synonyms set.
+
+
+[[delete-synonym-rule-example]]
+==== {api-examples-title}
+
+The following example deletes an existing synonym rule called `test-1` for the synonyms set `my-synonyms-set`:
+
+////
+[source,console]
+----
+PUT _synonyms/my-synonyms-set
+{
+  "synonyms_set": [
+    {
+      "id": "test-1",
+      "synonyms": "hello, hi"
+    },
+    {
+      "synonyms": "bye, goodbye"
+    },
+    {
+      "id": "test-2",
+      "synonyms": "test => check"
+    }
+  ]
+}
+
+PUT /test-index
+{
+  "settings": {
+    "analysis": {
+      "filter": {
+        "synonyms_filter": {
+          "type": "synonym_graph",
+          "synonyms_set": "my-synonyms-set",
+          "updateable": true
+        }
+      },
+      "analyzer": {
+        "my_index_analyzer": {
+          "type": "custom",
+          "tokenizer": "standard",
+          "filter": ["lowercase"]
+        },
+        "my_search_analyzer": {
+          "type": "custom",
+          "tokenizer": "standard",
+          "filter": ["lowercase", "synonyms_filter"]
+        }
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "my_index_analyzer",
+        "search_analyzer": "my_search_analyzer"
+      }
+    }
+  }
+}
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+DELETE _synonyms/my-synonyms-set/test-1
+----
+
+[source,console-result]
+----
+{
+  "result": "deleted",
+  "reload_analyzers_details": {
+    "_shards": {
+      "total": 2,
+      "successful": 1,
+      "failed": 0
+    },
+    "reload_details": [
+      {
+        "index": "test-index",
+        "reloaded_analyzers": [
+          "my_search_analyzer"
+        ],
+        "reloaded_node_ids": [
+          "1wYFZzq8Sxeu_Jvt9mlbkg"
+        ]
+      }
+    ]
+  }
+}
+----
+// TESTRESPONSE[s/1wYFZzq8Sxeu_Jvt9mlbkg/$body.reload_analyzers_details.reload_details.0.reloaded_node_ids.0/]
+
+All analyzers using this synonyms set will be <<synonyms-set-analyzer-reloading,reloaded automatically>> to reflect the rule being deleted.

docs/reference/synonyms/apis/get-synonym-rule.asciidoc

@@ -0,0 +1,80 @@
+[[get-synonym-rule]]
+=== Get synonym rule
+
+beta::[]
+
+++++
+<titleabbrev>Get synonym rule</titleabbrev>
+++++
+
+Retrieves a synonym rule from a synonyms set.
+
+[[get-synonym-rule-request]]
+==== {api-request-title}
+
+`GET _synonyms/<synonyms_set>/<synonym_rule>`
+
+[[get-synonym-rule-prereqs]]
+==== {api-prereq-title}
+
+Requires the `manage_search_synonyms` cluster privilege.
+
+[[get-synonym-rule-path-params]]
+==== {api-path-parms-title}
+
+`<synonyms_set>`::
+(Required, string)
+Synonyms set identifier to retrieve the synonym rule from.
+
+`<synonym_rule>`::
+(Required, string)
+Synonym rule identifier to retrieve.
+
+[[get-synonym-rule-response-codes]]
+==== {api-response-codes-title}
+
+`404` (Missing resources)::
+The `synonyms_set` identifier was not found, or the synonym rule specified by `synonym_rule` was not found in the synonyms set.
+
+[[get-synonym-rule-example]]
+==== {api-examples-title}
+
+The following example retrieves an existing synonym rule called `test-1` for the synonyms set `my-synonyms-set`:
+
+////
+[source,console]
+----
+PUT _synonyms/my-synonyms-set
+{
+  "synonyms_set": [
+    {
+      "id": "test-1",
+      "synonyms": "hello, hi"
+    },
+    {
+      "id": "test-3",
+      "synonyms": "bye, goodbye"
+    },
+    {
+      "id": "test-2",
+      "synonyms": "test => check"
+    }
+  ]
+}
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+GET _synonyms/my-synonyms-set/test-1
+----
+
+[source,console-result]
+----
+{
+  "id": "test-1",
+  "synonyms": "hello, hi"
+}
+----
+

docs/reference/synonyms/apis/put-synonym-rule.asciidoc

@@ -0,0 +1,173 @@
+[[put-synonym-rule]]
+=== Create or update synonym rule
+
+beta::[]
+
+++++
+<titleabbrev>Create or update synonym rule</titleabbrev>
+++++
+
+Creates or updates a synonym rule for a synonym set.
+
+[[put-synonym-rule-request]]
+==== {api-request-title}
+
+`PUT _synonyms/<synonyms_set>/<synonym_rule>`
+
+[[put-synonym-rule-prereqs]]
+==== {api-prereq-title}
+
+Requires the `manage_search_synonyms` cluster privilege.
+
+[[put-synonym-rule-path-params]]
+==== {api-path-parms-title}
+
+`<synonyms_set>`::
+(Required, string)
+Synonyms set identifier to update.
+
+`<synonym_rule>`::
+(Required, string)
+Synonym rule identifier to create or update.
+
+[[put-synonym-rule-request-body]]
+==== {api-request-body-title}
+
+`synonyms`::
+(Required, string)
+The synonym rule definition.
+This needs to be in <<_solr_synonyms>> format. Some examples are:
+
+* "i-pod, i pod => ipod",
+* "universe, cosmos"
+
+[[put-synonym-rule-example]]
+==== {api-examples-title}
+
+The following example updates an existing synonym rule called `test-1` for the synonyms set `my-synonyms-set`:
+
+////
+[source,console]
+----
+PUT _synonyms/my-synonyms-set
+{
+  "synonyms_set": [
+    {
+      "id": "test-1",
+      "synonyms": "hello, hi"
+    },
+    {
+      "synonyms": "bye, goodbye"
+    },
+    {
+      "id": "test-2",
+      "synonyms": "test => check"
+    }
+  ]
+}
+
+PUT /test-index
+{
+  "settings": {
+    "analysis": {
+      "filter": {
+        "synonyms_filter": {
+          "type": "synonym_graph",
+          "synonyms_set": "my-synonyms-set",
+          "updateable": true
+        }
+      },
+      "analyzer": {
+        "my_index_analyzer": {
+          "type": "custom",
+          "tokenizer": "standard",
+          "filter": ["lowercase"]
+        },
+        "my_search_analyzer": {
+          "type": "custom",
+          "tokenizer": "standard",
+          "filter": ["lowercase", "synonyms_filter"]
+        }
+      }
+    }
+  },
+  "mappings": {
+    "properties": {
+      "title": {
+        "type": "text",
+        "analyzer": "my_index_analyzer",
+        "search_analyzer": "my_search_analyzer"
+      }
+    }
+  }
+}
+----
+// TESTSETUP
+////
+
+[source,console]
+----
+PUT _synonyms/my-synonyms-set/test-1
+{
+  "synonyms": "hello, hi, howdy"
+}
+----
+
+[source,console-result]
+----
+{
+  "result": "updated",
+  "reload_analyzers_details": {
+    "_shards": {
+      "total": 2,
+      "successful": 1,
+      "failed": 0
+    },
+    "reload_details": [
+      {
+        "index": "test-index",
+        "reloaded_analyzers": [
+          "my_search_analyzer"
+        ],
+        "reloaded_node_ids": [
+          "1wYFZzq8Sxeu_Jvt9mlbkg"
+        ]
+      }
+    ]
+  }
+}
+----
+// TESTRESPONSE[s/1wYFZzq8Sxeu_Jvt9mlbkg/$body.reload_analyzers_details.reload_details.0.reloaded_node_ids.0/]
+
+All analyzers using this synonyms set will be <<synonyms-set-analyzer-reloading,reloaded automatically>> to reflect the new rule.
+
+If any of the synonym rules included is invalid, the API will return an error.
+
+[source,console]
+----
+PUT _synonyms/my-synonyms-set/test-1
+{
+  "synonyms": "hello => hi => howdy"
+}
+----
+// TEST[catch:bad_request]
+
+[source,console-result]
+----
+{
+  "error": {
+    "root_cause": [
+      {
+        "type": "action_request_validation_exception",
+        "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
+        "stack_trace": ...
+      }
+    ],
+    "type": "action_request_validation_exception",
+    "reason": "Validation Failed: 1: More than one explicit mapping specified in the same synonyms rule: [hello => hi => howdy];",
+    "stack_trace": ...
+  },
+  "status": 400
+}
+----
+// TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/]

docs/reference/synonyms/apis/put-synonyms-set.asciidoc

@@ -40,13 +40,13 @@ The synonym rules definitions for the synonyms set.
 
 `id`::
 (Optional, string)
-// TODO link to synonym rules APIs
-The identifier associated to the synonym rule, that can be used to manage individual synonym rules via Synonym Rules APIs.
+The identifier associated to the synonym rule, that can be used to manage individual synonym rules via <<synonym-rules-apis,synonym rules APIs>>.
 In case a synonym rule id is not specified, an identifier will be created automatically by {es}.
 
 `synonyms`::
-(Requried, string)
-The synonym rule. This needs to be in <<_solr_synonyms>> format. Some examples are:
+(Required, string)
+The synonym rule. This needs to be in <<_solr_synonyms>> format.
+Some examples are:
 * "i-pod, i pod => ipod",
 * "universe, cosmos"
 
@@ -114,7 +114,7 @@ PUT _synonyms/my-synonyms-set
 // TESTRESPONSE[s/"stack_trace": \.\.\./"stack_trace": $body.$_path/]
 
 
-[discrete]
+[[synonyms-set-analyzer-reloading]]
 ==== Analyzer reloading
 When an existing synonyms set is updated, the <<search-analyzer, search analyzers>> that use the synonyms set are reloaded automatically for all indices.
 This would be equivalent to invoking <<indices-reload-analyzers>> for all indices that use the synonyms set.

docs/reference/synonyms/apis/synonyms-apis.asciidoc

@@ -13,11 +13,16 @@ The synonyms management API provides a convenient way to define and manage synon
 Create as many synonym sets as you need.
 
 This provides an alternative to:
+
 - Defining inline synonyms in an analyzer definition, which impacts mapping size and can lead to performance issues.
 - Using synonyms files, which implies uploading and managing file consistency on all cluster nodes.
 
 Synonyms sets can be used to configure <<analysis-synonym-graph-tokenfilter,synonym graph token filters>> and <<analysis-synonym-tokenfilter,synonym token filters>>.
-These filters are applied as part of the <<search-analyzer,search analyzer>> analysis process.
+These filters are applied as part of the <<analysis,analysis>> process by the <<search-analyzer,search analyzer>>.
+
+[discrete]
+[[synonyms-sets-apis]]
+=== Synonyms sets APIs
 
 You can use these APIs to dynamically update synonyms sets used at search time.
 Your search results will immediately reflect the synonyms set changes.
@@ -29,8 +34,25 @@ Use the following APIs to manage synonyms sets:
 * <<list-synonyms-sets>>
 * <<delete-synonyms-set>>
 
+[discrete]
+[[synonym-rules-apis]]
+=== Synonym rules APIs
+
+Synonyms sets are composed of synonym rules.
+Each synonym rule defines a group of words that act as synonyms.
+You can update individual synonym rules for a specific synonyms set instead of updating the complete synonyms set.
+
+Use the following APIs to manage individual synonym rules in a synonyms set:
+
+* <<put-synonym-rule>>
+* <<get-synonym-rule>>
+* <<delete-synonym-rule>>
+
 include::put-synonyms-set.asciidoc[]
 include::get-synonyms-set.asciidoc[]
 include::list-synonyms-sets.asciidoc[]
 include::delete-synonyms-set.asciidoc[]
+include::put-synonym-rule.asciidoc[]
+include::get-synonym-rule.asciidoc[]
+include::delete-synonym-rule.asciidoc[]