扩展

有关查询扩展器和评分函数扩展的详细信息

扩展现有的搜索和查询功能

RediSearch 支持扩展机制，就像 Redis 支持模块一样。目前，API 非常简单，并且还不支持在正在运行的服务器上动态加载扩展。相反，扩展必须用 C（或具有 C 接口的语言）编写，并编译成可以在启动时加载的动态库。

目前有两种扩展 API

查询扩展器，其作用是扩展查询标记（即词干提取器）。
评分函数，其作用是在查询时对搜索结果进行排名。

注册和加载扩展

扩展应编译成动态库文件（例如 .so 文件），并在初始化期间加载到 RediSearch 模块中。

编译

Extensions should be compiled and linked as dynamic libraries. An example Makefile for an extension [can be found here](https://github.com/RediSearch/RediSearch/blob/master/tests/ctests/ext-example/Makefile). 

That folder also contains an example extension that is used for testing and can be taken as a skeleton for implementing your own extension.

加载

Loading an extension is done by appending `EXTLOAD {path/to/ext.so}` after the `loadmodule` configuration directive when loading the RediSearch module. For example:

```sh
$ redis-server --loadmodule ./redisearch.so EXTLOAD ./ext/my_extension.so
```

This causes the RediSearch module to automatically load the extension and register its expanders and scorers.

初始化扩展

扩展的入口点是一个具有以下签名的函数

int RS_ExtensionInit(RSExtensionCtx *ctx);

加载扩展时，RediSearch 会查找此函数并调用它。此函数负责注册和初始化扩展器和评分器。

它应在出错时返回 REDISEARCH_ERR，在成功时返回 REDISEARCH_OK。

示例 init 函数

#include <redisearch.h> //must be in the include path

int RS_ExtensionInit(RSExtensionCtx *ctx) {

  /* Register  a scoring function with an alias my_scorer and no special private data and free function */
  if (ctx->RegisterScoringFunction("my_scorer", MyCustomScorer, NULL, NULL) == REDISEARCH_ERR) {
    return REDISEARCH_ERR;
  }

  /* Register a query expander  */
  if (ctx->RegisterQueryExpander("my_expander", MyExpander, NULL, NULL) ==
      REDISEARCH_ERR) {
    return REDISEARCH_ERR;
  }

  return REDISEARCH_OK;
}

调用自定义函数

执行查询时，可以通过指定具有给定别名的 SCORER 或 EXPANDER 参数来使用评分器或扩展器。例如

FT.SEARCH my_index "foo bar" EXPANDER my_expander SCORER my_scorer

注意：扩展器和评分器别名区分大小写。

查询扩展器 API

仅支持基本查询扩展，一次一个标记。扩展器可以决定使用任意数量的标记扩展任何给定标记，这些标记将在查询时间合并为并集。

扩展器的 API 如下

#include <redisearch.h> //must be in the include path

void MyQueryExpander(RSQueryExpanderCtx *ctx, RSToken *token) {
    ...
}

RSQueryExpanderCtx

RSQueryExpanderCtx 是一个上下文，其中包含扩展的私有数据和一个用于扩展查询的回调方法。它被定义为

typedef struct RSQueryExpanderCtx {

  /* Opaque query object used internally by the engine, and should not be accessed */
  struct RSQuery *query;

  /* Opaque query node object used internally by the engine, and should not be accessed */
  struct RSQueryNode **currentNode;

  /* Private data of the extension, set on extension initialization */
  void *privdata;

  /* The language of the query, defaults to "english" */
  const char *language;

  /* ExpandToken allows the user to add an expansion of the token in the query, that will be
   * union-merged with the given token in query time. str is the expanded string, len is its length,
   * and flags is a 32 bit flag mask that can be used by the extension to set private information on
   * the token */
  void (*ExpandToken)(struct RSQueryExpanderCtx *ctx, const char *str, size_t len,
                      RSTokenFlags flags);

  /* SetPayload allows the query expander to set GLOBAL payload on the query (not unique per token)
   */
  void (*SetPayload)(struct RSQueryExpanderCtx *ctx, RSPayload payload);

} RSQueryExpanderCtx;

RSToken

RSToken 表示要扩展的单个查询标记，并被定义为

/* A token in the query. The expanders receive query tokens and can expand the query with more query
 * tokens */
typedef struct {
  /* The token string - which may or may not be NULL terminated */
  const char *str;
  /* The token length */
  size_t len;
  
  /* 1 if the token is the result of query expansion */
  uint8_t expanded:1;

  /* Extension specific token flags that can be examined later by the scoring function */
  RSTokenFlags flags;
} RSToken;

评分函数 API

对于最终排名，评分函数会分析查询检索到的每篇文档，不仅考虑触发文档检索的术语，还会考虑元数据，例如其先前的得分、长度等。

由于评分函数针对每篇文档进行评估，可能达到数百万次，并且由于 redis 是单线程的，因此重要的是它尽可能快地工作并得到高度优化。

评分函数应用于每篇文档的每个潜在结果，并使用以下签名实现

double MyScoringFunction(RSScoringFunctionCtx *ctx, RSIndexResult *res,
                                    RSDocumentMetadata *dmd, double minScore);

RSScoringFunctionCtx 是一个上下文，它实现了一些帮助程序方法。

RSIndexResult 是包含文档 ID、频率、术语和偏移量的结果信息。

RSDocumentMetadata 是一个对象，其中包含有关文档的全局信息，例如其推定得分。

minScore 是将产生与搜索相关的结果的最小得分。它可用于在中途或之前甚至在开始之前停止处理。

函数的返回值是一个表示结果最终得分的double。返回 0 会导致对结果进行计数，但如果存在得分大于 0 的结果，则它们将显示在该结果之上。要完全过滤掉结果并将其不计入总数，评分器应返回特殊值RS_SCORE_FILTEROUT，该值在内部设置为负无穷大或 -1/0。

RSScoringFunctionCtx

这是一个包含以下成员的对象

void *privdata：一个指向在初始化时由扩展设置的对象的指针。
RSPayload payload*：一个由查询扩展器或客户端设置的 Payload 对象。
int GetSlop(RSIndexResult *res)*：一个回调方法，可产生查询词之间的总最小距离。这可用于优先考虑 slop 较小且词彼此更近的结果。

RSIndexResult

这是一个保存有关索引中当前结果的信息的对象，它是导致当前文档被视为有效结果的所有词的聚合。有关详细信息，请参见 redisearch.h。

RSDocumentMetadata

这是一个描述与当前查询无关的有关评分函数正在评估的文档的全局信息的对象。

示例查询扩展器

此示例查询扩展器使用术语 foo 扩展每个标记

#include <redisearch.h> //must be in the include path

void DummyExpander(RSQueryExpanderCtx *ctx, RSToken *token) {
    ctx->ExpandToken(ctx, strdup("foo"), strlen("foo"), 0x1337);  
}

示例评分函数

这是一个实际的评分函数，它计算文档的 TF-IDF，将其乘以文档分数，并将其除以 slop

#include <redisearch.h> //must be in the include path

double TFIDFScorer(RSScoringFunctionCtx *ctx, RSIndexResult *h, RSDocumentMetadata *dmd,
                   double minScore) {
  // no need to evaluate documents with score 0 
  if (dmd->score == 0) return 0;

  // calculate sum(tf-idf) for each term in the result
  double tfidf = 0;
  for (int i = 0; i < h->numRecords; i++) {
    // take the term frequency and multiply by the term IDF, add that to the total
    tfidf += (float)h->records[i].freq * (h->records[i].term ? h->records[i].term->idf : 0);
  }
  // normalize by the maximal frequency of any term in the document   
  tfidf /=  (double)dmd->maxFreq;

  // multiply by the document score (between 0 and 1)
  tfidf *= dmd->score;

  // no need to factor the slop if tfidf is already below minimal score
  if (tfidf < minScore) {
    return 0;
  }

  // get the slop and divide the result by it, making sure we prefer results with closer terms
  tfidf /= (double)ctx->GetSlop(h);
  
  return tfidf;
}

扩展