Kronuz/Xapiand 文档脚本功能深度解析

脚本功能概述

Kronuz/Xapiand 提供了强大的脚本功能，允许用户在搜索请求或文档操作过程中执行自定义逻辑。这项功能特别适用于需要动态计算字段值、自定义评分或执行复杂数据处理的场景。

脚本语言支持

系统目前采用 ChaiScript 作为脚本执行引擎。ChaiScript 是一种嵌入式脚本语言，专为 C++ 设计，具有以下特点：

• 语法简洁直观，类似 JavaScript
• 直接与 C++ 对象交互的高效性
• 类型安全的脚本执行环境

基础脚本示例

让我们从一个简单但实用的例子开始 - 文档序列号自动递增：

PUT /twitter/user/John
{
  "_script": "_doc.serial = _old_doc.serial + 1"
}

这个脚本实现了：

1. 首次创建文档时初始化 serial 字段
2. 后续更新时自动递增 serial 值

字段访问方式：

• 点表示法：_doc.serial
• 数组表示法：_doc["serial"]

两种方式效果相同，开发者可根据场景选择更易读的形式。

脚本结构详解

完整的脚本定义支持两种格式：

完整格式

"_script": {
  "_type": "script",
  "_chai": {
    "_name": "自定义脚本名称",
    "_body": "脚本内容",
    "_params": {
      "参数1": 值1,
      "参数2": 值2
    }
  }
}

简写格式

"_script": "直接写脚本内容"

性能优化技巧

脚本缓存机制

系统会自动缓存编译后的脚本，关键特性：

• 默认缓存容量：100 个脚本
• 无时间过期策略
• 仅当脚本内容变更时重新编译

参数化脚本实践

不良实践（硬编码值）：

{
  "_script": "_doc.value *= 2"
}

推荐实践（参数化）：

{
  "_script": {
    "_value": "_doc.value *= factor",
    "_params": {
      "factor": 2
    }
  }
}

参数化优势：

1. 避免重复编译
2. 提高脚本复用性
3. 动态调整行为无需修改脚本

高级功能：外部脚本

对于复杂或需要复用的脚本，可以存储在专门的文档中：

1. 首先创建脚本文档：

PUT /scripts/math_operations
{
  "_recurse": false,
  "multiply": {
    "_chai": {
      "_body": "_doc.value *= factor",
      "_params": {
        "factor": 1
      }
    }
  }
}

2. 在其他文档中引用：

PUT /data/records
{
  "value": 5,
  "_script": {
    "_type": "foreign/object",
    "_foreign": "scripts/math_operations.multiply",
    "_params": {
      "factor": 3
    }
  }
}

外部脚本优势：

• 集中管理业务逻辑
• 一处修改，多处生效
• 更好的版本控制

预定义变量

脚本执行时可访问以下系统变量：

变量名	描述
_doc	当前处理的文档对象
_old_doc	更新/删除前的旧文档对象
_method	触发脚本的HTTP方法(GET/PUT等)

最佳实践建议

1. 避免复杂计算：脚本执行会影响性能，复杂逻辑建议在索引前处理
2. 参数优先：尽量使用参数而非硬编码值
3. 适度使用：文档量大的情况下，脚本操作可能成为性能瓶颈
4. 外部脚本：复用率高的逻辑建议提取为外部脚本
5. 测试验证：生产环境使用前充分测试脚本逻辑

通过合理利用Xapiand的脚本功能，开发者可以实现高度灵活的数据处理逻辑，同时保持系统的良好性能。