查询脚本上下文

此 API 用于获取 Easysearch 中所有可用的脚本上下文（Script Contexts）信息。脚本上下文定义了脚本可以在哪些场景中使用以及可以使用哪些功能。

API #

GET /_script_context

API 的作用 #

返回所有可用的脚本上下文信息，包括每个上下文的名称、方法以及方法的参数信息。这对于开发者了解在脚本中可以使用哪些上下文和功能非常有用。

脚本上下文定义了脚本的执行环境，例如：

评分脚本：用于自定义评分
字段脚本：用于文档字段操作
聚合脚本：用于聚合计算
更新脚本：用于更新操作
排序脚本：用于自定义排序

API 的参数 #

此 API 没有路由参数和查询字符串参数。

请求示例 #

# 查询所有脚本上下文
GET /_script_context

响应示例 #

{
  "contexts": [
    {
      "name": "score",
      "methods": [
        {
          "name": "execute",
          "return_type": "double",
          "params": [
            {
              "type": "QueryShardContext",
              "name": "context"
            },
            {
              "type": "Doc",
              "name": "doc"
            },
            {
              "type": "double",
              "name": "score"
            }
          ]
        },
        {
          "name": "setDocument",
          "return_type": "void",
          "params": [
            {
              "type": "Doc",
              "name": "doc"
            }
          ]
        },
        {
          "name": "getDocument",
          "return_type": "Doc",
          "params": []
        }
      ]
    },
    {
      "name": "field",
      "methods": [
        {
          "name": "execute",
          "return_type": "Object",
          "params": [
            {
              "type": "FieldValueLookup",
              "name": "lookup"
            },
            {
              "type": "Map<String,Object>",
              "name": "params"
            }
          ]
        }
      ]
    },
    {
      "name": "aggs",
      "methods": [
        {
          "name": "execute",
          "return_type": "Object",
          "params": [
            {
              "type": "AggregationScript.LeafFactory",
              "name": "leafFactory"
            },
            {
              "type": "Map<String,Object>",
              "name": "params"
            }
          ]
        }
      ]
    },
    {
      "name": "update",
      "methods": [
        {
          "name": "execute",
          "return_type": "void",
          "params": [
            {
              "type": "UpdateScript",
              "name": "ctx"
            }
          ]
        }
      ]
    },
    {
      "name": "filter",
      "methods": [
        {
          "name": "execute",
          "return_type": "boolean",
          "params": [
            {
              "type": "Doc",
              "name": "doc"
            }
          ]
        },
        {
          "name": "setDocument",
          "return_type": "void",
          "params": [
            {
              "type": "Doc",
              "name": "doc"
            }
          ]
        },
        {
          "name": "getDocument",
          "return_type": "Doc",
          "params": []
        }
      ]
    }
  ]
}

响应字段说明 #

字段	类型	描述
`contexts`	array	脚本上下文数组
`contexts.name`	string	上下文名称，如 score、field、aggs、update 等
`contexts.methods`	array	该上下文支持的方法列表
`contexts.methods.name`	string	方法名称
`contexts.methods.return_type`	string	方法的返回类型
`contexts.methods.params`	array	方法参数列表
`contexts.methods.params.type`	string	参数的数据类型
`contexts.methods.params.name`	string	参数的名称

常见脚本上下文 #

上下文名称	描述	使用场景
`score`	评分脚本	自定义查询评分
`field`	字段脚本	文档字段映射和计算
`aggs`	聚合脚本	聚合计算中的自定义逻辑
`update`	更新脚本	更新操作中的文档修改
`filter`	过滤脚本	自定义过滤逻辑
`sort`	排序脚本	自定义排序逻辑
`bucket_sort`	分桶排序脚本	聚合分桶排序
`constant_score`	常量评分脚本	返回固定评分值
`bool`	布尔组合脚本	布尔查询中的脚本

方法类型说明 #

execute 方法 #

每个上下文必须有的主方法，用于执行脚本的主要逻辑。

getter/setter 方法 #

某些上下文提供的方法，用于获取或设置文档对象：

setDocument(Doc doc)：设置要操作的文档
getDocument()：获取当前文档对象

使用场景 #

开发参考：了解可用的脚本上下文及其功能
脚本编写：根据上下文的方法签名编写正确的脚本
调试辅助：验证脚本上下文的参数和返回类型
版本兼容性：检查不同版本中上下文的差异

脚本语言支持 #

Easysearch 主要支持 Painless 脚本语言，它是默认且推荐的脚本语言。其他脚本语言的支持情况可以通过查询脚本语言 API 查看。

示例：使用不同上下文 #

评分脚本 (score) #

{
  "query": {
    "function_score": {
      "script_score": {
        "script": {
          "source": "doc['popularity'].value * params.factor",
          "params": {
            "factor": 1.5
          }
        }
      }
    }
  }
}

更新脚本 (update) #

POST /my-index/_update/1
{
  "script": {
    "source": "ctx._source.counter += params.increment",
    "params": {
      "increment": 1
    }
  }
}

聚合脚本 (aggs) #

{
  "aggs": {
    "average_price": {
      "avg": {
        "script": {
          "source": "doc.price.value * params.tax_rate",
          "params": {
            "tax_rate": 1.2
          }
        }
      }
    }
  }
}

注意事项 #

此 API 只支持 GET 方法
不需要任何参数
返回的上下文列表取决于集群配置和安装的插件
脚本上下文定义了脚本的可访问变量和方法
编写脚本时需要根据上下文的方法签名正确使用