Search Application APIs | Elasticsearch Guide

放置搜索应用程序

edit

此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试功能不受正式发布功能的支持服务级别协议的约束。

创建或更新一个搜索应用程序。

请求

edit

PUT _application/search_application/

先决条件

edit

需要 manage_search_application 集群权限。还需要对添加到搜索应用程序的所有索引具有管理权限。

路径参数

edit

create

(可选，布尔值) 如果为 true，此请求不能替换或更新现有的搜索应用程序。默认为 false。

<body>

(必需，对象) 包含搜索应用程序的参数：

Properties of objects

indices

(必需, 字符串数组) 与该搜索应用程序关联的索引。所有索引需要存在才能被添加到搜索应用程序中。

template

(可选, 对象) 与该搜索应用程序关联的搜索模板。该搜索应用程序的模板仅存储并通过搜索应用程序访问。

此搜索模板必须是一个Mustache模板。
模板必须包含一个Mustache脚本和脚本源。
模板可以通过后续的put search application请求进行修改。
如果在创建搜索应用程序时未指定模板，或者从搜索应用程序中删除了模板，我们将使用模板示例中定义的query_string作为默认值。
此模板将由搜索应用程序搜索API用于执行搜索。
模板接受一个可选的dictionary参数，该参数定义了一个用于验证发送到搜索应用程序搜索API的参数的JSON schema。

Properties of

script: (必需, 对象) 关联的mustache模板。

dictionary: (可选, 对象) 用于验证与搜索应用程序搜索API一起使用的参数的字典。字典必须是一个有效的JSON schema。如果未指定dictionary，则在模板中应用参数之前不会进行验证。

响应代码

edit

404: 搜索应用程序不存在。
409: 搜索应用程序存在且 create 为 true。

示例

edit

以下示例创建或更新一个名为 my-app 的新搜索应用程序：

PUT _application/search_application/my-app
{
  "indices": [ "index1", "index2" ],
  "template": {
    "script": {
      "source": {
        "query": {
          "query_string": {
            "query": "{{query_string}}",
            "default_field": "{{default_field}}"
          }
        }
      },
      "params": {
        "query_string": "*",
        "default_field": "*"
      }
    },
    "dictionary": {
      "properties": {
        "query_string": {
          "type": "string"
        },
        "default_field": {
          "type": "string",
          "enum": [
            "title",
            "description"
          ]
        },
        "additionalProperties": false
      },
      "required": [
        "query_string"
      ]
    }
  }
}

当指定上述dictionary参数时，搜索应用程序搜索 API 将执行以下参数验证：

它只接受query_string和default_field参数
它验证query_string和default_field是否都是字符串
它只接受default_field，如果它的值是title或description

如果参数无效，则搜索应用程序搜索 API 将返回错误。

POST _application/search_application/my-app/_search
{
  "params": {
    "default_field": "author",
    "query_string": "Jane"
  }
}

在上面的示例中，default_field 参数的值无效，因此 Elasticsearch 将返回一个错误：

{
  "error": {
    "root_cause": [
      {
        "type": "validation_exception",
        "reason": 'Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];',
        "stack_trace": ...
      }
    ],
    "type": "validation_exception",
    "reason": 'Validation Failed: 1: $.default_field: does not have a value in the enumeration [title, description];',
    "stack_trace": ...
  },
  "status": 400
}

获取搜索应用程序

edit

此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试功能不受正式发布功能的支持服务级别协议的约束。

检索有关搜索应用程序的信息。

请求

edit

GET _application/search_application/

先决条件

edit

需要 manage_search_application 集群权限。

路径参数

edit

<name>: （必需，字符串）

响应代码

edit

400: 未提供名称。
404 (Missing resources): 未找到与名称匹配的搜索应用程序。

示例

edit

以下示例获取名为 my-app 的搜索应用程序：

GET _application/search_application/my-app/

一个示例响应：

{
  "name": "my-app",
  "indices": [ "index1", "index2" ],
  "updated_at_millis": 1682105622204,
  "template": {
    "script": {
      "source": {
        "query": {
          "query_string": {
            "query": "{{query_string}}",
            "default_field": "{{default_field}}"
          }
        }
      },
      "lang": "mustache",
      "options": {
        "content_type": "application/json;charset=utf-8"
      },
      "params": {
        "query_string": "*",
        "default_field": "*"
      }
    }
  }
}

列出搜索应用程序

edit

此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试功能不受正式发布功能的支持服务级别协议的约束。

返回有关搜索应用程序的信息。

请求

edit

GET _application/search_application/

先决条件

edit

需要 manage_search_application 集群权限。

路径参数

edit

q: (可选, 字符串) 使用Lucene查询字符串语法进行查询，以返回仅匹配该查询的搜索应用程序。
size: (可选，整数) 要检索的最大结果数。
from: (可选，整数) 从第一个结果开始的偏移量。

响应代码

edit

示例

edit

以下示例列出了所有已配置的搜索应用程序：

GET _application/search_application/

以下示例查询名称以 app 开头的三个搜索应用程序：

GET _application/search_application?from=0&size=3&q=app*

一个示例响应：

{
  "count": 2,
  "results": [
    {
      "name": "app-1",
      "updated_at_millis": 1690981129366
    },
    {
      "name": "app-2",
      "updated_at_millis": 1691501823939
    }
  ]
}

删除搜索应用程序

edit

此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试功能不受正式发布功能的支持服务级别协议的约束。

删除一个搜索应用程序及其关联的别名。附加到搜索应用程序的索引不会被删除。

请求

edit

DELETE _application/search_application/

先决条件

edit

需要 manage_search_application 集群权限。还需要对包含在搜索应用中的所有索引具有管理权限。

路径参数

edit

<name>: （必需，字符串）

响应代码

edit

400: 未提供名称。
404 (Missing resources): 未找到与名称匹配的搜索应用程序。

示例

edit

以下示例删除了名为 my-app 的搜索应用程序：

DELETE _application/search_application/my-app/

搜索应用程序搜索

edit

此功能处于测试阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试功能不受正式发布功能的支持服务级别协议的约束。

给定指定的查询参数，使用与搜索应用程序关联的搜索模板或未指定时使用默认模板生成并执行Elasticsearch查询。未指定的模板参数将分配其默认值（如果适用）。

请求

edit

POST _application/search_application//_search

先决条件

edit

需要对搜索应用程序的后备别名具有读取权限。

路径参数

edit

typed_keys: (可选，布尔值) 如果为 true，聚合和建议器的名称将在响应中以其各自类型为前缀。默认为 false。

请求体

edit

params: (可选，字符串到对象的映射) 用于生成与搜索应用程序关联的搜索模板中的Elasticsearch查询的查询参数。如果在搜索模板中使用的参数未在params中指定，则将使用该参数的默认值。

搜索应用程序可以配置为验证搜索模板参数。有关更多信息，请参见put search application API中的dictionary参数。

响应代码

edit

400

传递给搜索模板的参数无效。示例包括：

缺少必需的参数
参数数据类型无效
参数值无效

404

搜索应用程序不存在。

示例

edit

以下示例对一个名为 my-app 的搜索应用程序执行搜索，该应用程序使用来自文本搜索示例的搜索模板：

POST _application/search_application/my-app/_search
{
  "params": {
    "query_string": "my first query",
    "text_fields": [
      {"name": "title", "boost": 5},
      {"name": "description", "boost": 1}
    ]
  }
}

生成的 Elasticsearch 查询将如下所示：

{
  "from": 0,
  "size": 10,
  "query": {
    "multi_match": {
      "query": "my first query",
      "fields": [
        "description^1.0",
        "title^5.0"
      ]
    }
  },
  "explain": false
}

在这种情况下，请求中未指定 from、size 和 explain 参数，因此使用搜索模板中指定的默认值。

预期的响应是从生成的并执行的Elasticsearch查询中获得的搜索结果。响应格式与Elasticsearch搜索API使用的格式相同：

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.8630463,
    "hits": ...
  }
}

渲染搜索应用程序查询

edit

此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。

给定指定的查询参数，使用与搜索应用程序关联的搜索模板生成一个Elasticsearch查询，如果没有指定模板，则使用默认模板。未指定的模板参数将被分配其默认值（如果适用）。返回通过调用搜索应用程序搜索生成的特定Elasticsearch查询。

请求

edit

POST _application/search_application//_render_query

先决条件

edit

需要对搜索应用程序的后备别名具有读取权限。

请求体

edit

params: (可选，字符串到对象的映射) 用于生成与搜索应用程序关联的搜索模板中的Elasticsearch查询的查询参数。如果在搜索模板中使用的参数未在params中指定，则将使用该参数的默认值。

搜索应用程序可以配置为验证搜索模板参数。有关更多信息，请参见put search application API中的dictionary参数。

响应代码

edit

400

传递给搜索模板的参数无效。示例包括：

缺少必需的参数
参数数据类型无效
参数值无效

404

搜索应用程序不存在。

示例

edit

以下示例为名为 my-app 的搜索应用程序生成查询，该应用程序使用来自文本搜索示例的搜索模板：

POST _application/search_application/my-app/_render_query
{
  "params": {
    "query_string": "my first query",
    "text_fields": [
      {"name": "title", "boost": 5},
      {"name": "description", "boost": 1}
    ]
  }
}

一个示例响应：

{
  "from": 0,
  "size": 10,
  "query": {
    "multi_match": {
      "query": "my first query",
      "fields": [
        "description^1.0",
        "title^5.0"
      ]
    }
  },
  "explain": false
}

在这种情况下，请求中未指定 from、size 和 explain 参数，因此使用搜索模板中指定的默认值。

搜索应用程序API

搜索应用程序接口

放置搜索应用程序

请求

先决条件

路径参数

响应代码

示例

获取搜索应用程序

请求

先决条件

路径参数

响应代码

示例

列出搜索应用程序

请求

先决条件

路径参数

响应代码

示例

删除搜索应用程序

请求

先决条件

路径参数

响应代码

示例

搜索应用程序搜索

请求

先决条件

路径参数

请求体

响应代码

示例

渲染搜索应用程序查询

请求

先决条件

请求体

响应代码

示例