« SQL APIs Text structure APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

同义词API

edit

同义词API

edit

同义词管理API提供了一种便捷的方式来定义和管理内部系统索引中的同义词。相关的同义词可以分组在一个“同义词集”中。 您可以根据需要创建任意数量的同义词集。

这提供了另一种选择：

  • 在分析器定义中定义内联同义词，这会影响映射大小并可能导致性能问题。
  • 使用同义词文件，这意味着需要在所有集群节点上上传和管理文件一致性。

同义词集可以用于配置同义词图令牌过滤器和同义词令牌过滤器。 这些过滤器作为分析过程的一部分，由搜索分析器应用。

同义词集最多包含每个集10,000条同义词规则。 如果您需要管理更多同义词规则，可以创建多个同义词集。

同义词集必须在添加到索引之前存在。 如果创建的索引引用了不存在的同义词集，索引将保持部分创建且无法操作的状态。 从这种情况恢复的唯一方法是确保同义词集存在，然后删除并重新创建索引，或者关闭并重新打开索引。

无效的同义词规则在应用分析器更改时可能会导致错误。 对于可重新加载的分析器，这会阻止重新加载和应用更改。 您必须更正同义词规则中的错误并重新加载分析器。

具有无效同义词规则的索引无法重新打开，使其在以下情况下无法操作：

  • 包含索引的节点启动
  • 从关闭状态打开索引
  • 发生节点重启（重新打开分配给该节点的分片）

同义词集 API

edit

您可以使用这些API来动态更新搜索时使用的同义词集。 您的搜索结果将立即反映同义词集的变化。

使用以下API来管理同义词集：

同义词规则 API

edit

同义词集由同义词规则组成。 每条同义词规则定义了一组作为同义词的词语。 您可以更新特定同义词集中的单个同义词规则，而不必更新整个同义词集。

使用以下API来管理同义词集中的单个同义词规则：

创建或更新同义词集

edit

创建或更新同义词集。

同义词集最多包含每个集10,000条同义词规则。 如果您需要管理更多同义词规则，可以创建多个同义词集。

请求

edit

PUT _synonyms/

先决条件

edit

需要 manage_search_synonyms 集群权限。

路径参数

edit
<synonyms_set>
(必需，字符串) 要创建的同义词集标识符。 此标识符将由其他同义词API用于管理同义词集。

请求体

edit
synonyms_set
(必需，同义词规则对象数组) 同义词集的同义词规则定义。
synonyms_set对象的属性
id
(可选，字符串) 与同义词规则关联的标识符，可以通过同义词规则API来管理单个同义词规则。 如果未指定同义词规则ID，Elasticsearch将自动创建一个标识符。
synonyms

(必需，字符串) 同义词规则。这需要采用Solr格式。一些示例如下：

  • "i-pod, i pod ⇒ ipod",
  • "universe, cosmos"

示例

edit

以下示例创建了一个名为 my-synonyms-set 的新同义词集：

PUT _synonyms/my-synonyms-set
{
  "synonyms_set": [
    {
      "id": "test-1",
      "synonyms": "hello, hi"
    },
    {
      "synonyms": "bye, goodbye"
    },
    {
      "id": "test-2",
      "synonyms": "test => check"
    }
  ]
}

如果包含的任何同义词规则无效，API将返回错误。

PUT _synonyms/my-synonyms-set
{
  "synonyms_set": [
    {
      "synonyms": "hello => hi => howdy"
    }
  ]
}
{
  "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
}

分析器重载

edit

当现有的同义词集被更新时，所有使用该同义词集的索引的搜索分析器会自动重新加载。 这相当于为所有使用该同义词集的索引调用重新加载搜索分析器API。

例如，使用同义词集创建索引并更新它：

PUT _synonyms/my-synonyms-set
{
    "synonyms_set": [
        {
            "id": "test-1",
            "synonyms": "hello, hi"
        }
    ]
}

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"
      }
    }
  }
}

PUT _synonyms/my-synonyms-set
{
    "synonyms_set": [
        {
            "id": "test-1",
            "synonyms": "hello, hi, howdy"
        }
    ]
}

重新加载的结果作为响应的一部分包含在内：

{
  "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"
        ]
      }
    ]
  }
}

获取同义词集

edit

检索同义词集。

请求

edit

GET _synonyms/

先决条件

edit

需要 manage_search_synonyms 集群权限。

路径参数

edit
<synonyms_set>
(必需，字符串) 同义词集标识符，用于检索。

查询参数

edit
from
(可选，整数) 同义词规则检索的起始偏移量。默认为 0。
size
(可选，整数) 指定要检索的最大同义词规则数量。默认为 10。

响应代码

edit
400
未提供 synonyms_set 标识符。
404 (Missing resources)
未找到与标识符 synonyms_set 设置的同义词。

示例

edit

以下示例检索一个名为 my-synonyms-set 的同义词集：

GET _synonyms/my-synonyms-set

返回的同义词集信息将包括同义词集包含的同义词规则总数，以及根据from和size参数的同义词规则。

一个示例响应：

{
  "count": 3,
  "synonyms_set": [
    {
      "id": "test-1",
      "synonyms": "hello, hi"
    },
    {
      "id": "test-2",
      "synonyms": "bye, goodbye"
    },
    {
      "id": "test-3",
      "synonyms": "test => check"
    }
  ]
}

列出同义词集

edit

检索所有已定义同义词集的摘要。

此API允许检索定义的同义词集总数。 对于每个同义词集，返回其标识符和定义的同义词规则总数。

请求

edit

GET _synonyms

先决条件

edit

需要 manage_search_synonyms 集群权限。

查询参数

edit
from
(可选，整数) 用于检索同义词集的起始偏移量。默认为 0。
size
(可选，整数) 指定要检索的最大同义词集数量。默认为 10。

示例

edit

以下示例检索所有已定义的同义词集：

GET _synonyms

一个示例响应：

{
  "count": 3,
  "results": [
    {
      "synonyms_set": "ecommerce-synonyms",
      "count": 2
    },
    {
      "synonyms_set": "my-synonyms-set",
      "count": 3
    },
    {
      "synonyms_set": "new-ecommerce-synonyms",
      "count": 1
    }
  ]
}

删除同义词集

edit

删除一个同义词集。

请求

edit

DELETE _synonyms/

前提条件

edit
  • 需要 manage_search_synonyms 集群权限。
  • 您只能删除未被任何索引分析器使用的同义词集。有关更多信息，请参阅 删除同义词集分析器要求。

路径参数

edit
<synonyms_set>
(必需，字符串) 要删除的同义词集标识符。

响应代码

edit
400
未提供 synonyms_set 标识符，或者同义词集无法删除，因为它不符合 指定的要求。
404 (Missing resources)
未找到与标识符 synonyms_set 设置的同义词。

示例

edit

以下示例删除了一个名为 my-synonyms-set 的同义词集：

DELETE _synonyms/my-synonyms-set

删除同义词集分析器要求

edit

同义词集可以用于 同义词图令牌过滤器 和 同义词令牌过滤器。 这些同义词过滤器可以作为 搜索分析器 的一部分使用。

在恢复索引时（例如节点启动或索引变为打开状态），需要加载分析器。 即使分析器未在任何字段映射中使用，它仍然需要在索引恢复阶段加载。

如果任何分析器无法加载，索引将变得不可用，并且集群状态将变为红色或黄色，因为索引分片不可用。

为了防止这种情况，在分析器中使用的同义词集不能被删除。 在这种情况下，删除请求将返回一个400响应代码，并带有以下错误消息：

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "synonyms set [my-synonyms-set] cannot be deleted as it is used in the following indices: index-1, index-2",
        "stack_trace": ...
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "synonyms set [my-synonyms-set] cannot be deleted as it is used in the following indices: index-1, index-2",
    "stack_trace": ...
  },
  "status": 400
}

要删除一个同义词集，您必须首先删除所有包含使用该同义词集的分析器的索引。 您可以通过创建一个不包含带有同义词集的词条过滤器的新索引来迁移索引，并使用Reindex来复制索引数据。 完成后，您可以删除该索引。

当同义词集未在分析器中使用时，您将能够删除它。

创建或更新同义词规则

edit

创建或更新同义词集的同义词规则。

请求

edit

PUT _synonyms//

先决条件

edit

需要 manage_search_synonyms 集群权限。

路径参数

edit
<synonyms_set>
(必需，字符串) 同义词集标识符，用于更新。
<synonym_rule>
(必需，字符串) 同义词规则标识符，用于创建或更新。

请求体

edit
synonyms

(必需，字符串) 同义词规则定义。 这需要采用Solr格式。一些示例如下：

  • "i-pod, i pod ⇒ ipod",
  • "universe, cosmos"

示例

edit

以下示例更新了名为 test-1 的现有同义词规则，用于同义词集 my-synonyms-set：

PUT _synonyms/my-synonyms-set/test-1
{
  "synonyms": "hello, hi, howdy"
}
{
  "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"
        ]
      }
    ]
  }
}

所有使用此同义词集的分析器将自动重新加载以反映新规则。

如果包含的任何同义词规则无效，API将返回错误。

PUT _synonyms/my-synonyms-set/test-1
{
  "synonyms": "hello => hi => howdy"
}
{
  "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
}

获取同义词规则

edit

从同义词集中检索一个同义词规则。

请求

edit

GET _synonyms//

先决条件

edit

需要 manage_search_synonyms 集群权限。

路径参数

edit
<synonyms_set>
(必需，字符串) 同义词集标识符，用于从中检索同义词规则。
<synonym_rule>
(必需，字符串) 同义词规则标识符，用于检索。

响应代码

edit
404 (Missing resources)
未找到 synonyms_set 标识符，或者在同义词集中未找到由 synonym_rule 指定的同义词规则。

示例

edit

以下示例检索名为 test-1 的现有同义词规则，用于同义词集 my-synonyms-set：

GET _synonyms/my-synonyms-set/test-1
{
  "id": "test-1",
  "synonyms": "hello, hi"
}

删除同义词规则

edit

从同义词集中删除单个同义词规则。

请求

edit

DELETE _synonyms//

前提条件

edit

需要 manage_search_synonyms 集群权限。

路径参数

edit
<synonyms_set>
(必需，字符串) 要更新的同义词集标识符。
<synonym_rule>
(必需, 字符串) 要删除的同义词规则标识符。

响应代码

edit
404 (Missing resources)
未找到 synonyms_set 标识符，或者在同义词集中未找到由 synonym_rule 指定的同义词规则。

示例

edit

以下示例删除了名为 test-1 的现有同义词规则，该规则属于同义词集 my-synonyms-set：

DELETE _synonyms/my-synonyms-set/test-1
{
  "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"
        ]
      }
    ]
  }
}

所有使用此同义词集的分析器将自动重新加载以反映被删除的规则。

« SQL APIs Text structure APIs »