分词器插件

分词器插件

更新时间：2026-08-14 11:48:11

编辑

本文将介绍如何在 OceanBase Database AI 安装和使用分词器插件。分词器插件可用于全文索引功能，支持自定义分词逻辑以满足特定业务需求。

注意

当前分词器插件为实验特性，暂不建议在生产环境使用。

前提条件

在安装和使用分词器插件之前，请确保以下条件已满足：

操作系统支持 yum 包管理工具。

说明

如果您使用的系统不支持 yum，可以通过其他方式安装上述依赖项，例如手动下载 RPM 包或使用其他包管理工具。
已部署正常运行的 OceanBase Database AI 集群。
具备系统租户权限，用于修改配置参数和重启集群。

操作步骤

步骤一：安装开发环境

分词器插件的开发需要 C/C++ 编译环境以及 OceanBase 提供的插件开发工具包。执行以下命令安装 C/C++ 开发环境和 OceanBase 插件开发包：

安装基础编译工具。

安装了编译 C/C++ 程序所需的基本工具和库。
```
yum install -y cmake make glibc-devel glibc-headers gcc gcc-c++
```
配置 OceanBase 软件源。

添加 OceanBase 的官方软件源，以便后续通过 yum 安装 OceanBase 相关的工具和依赖。
1. 安装 yum-utils 工具。
```
yum install -y yum-utils
```
2. 添加 OceanBase 软件源。
```
yum-config-manager --add-repo https://mirrors.aliyun.com/oceanbase/OceanBase.repo
```
安装插件开发套件。
```
yum install -y oceanbase-plugin-dev-kit
```
安装完成后，可以在 /usr/share/examples/ObPlugin/ftparser 目录下看到 OceanBase 分词器插件样例代码文件 space_ftparser.cpp。
```
ls /usr/share/examples/ObPlugin/ftparser
```
返回结果如下：
```
CMakeLists.txt  space_ftparser.cpp
```

步骤二：获取开发模板

复制 OceanBase 分词器插件样例代码 space_ftparser.cpp 到自己的开发目录下，即可以修改 space_ftparser.cpp 文件开发自己的分词器插件。

示例如下：

[root@xxx packages]# cp /usr/share/examples/ObPlugin/ftparser/* /home/admin/test_plugin_dev

[root@xxx packages]# ls /home/admin/test_plugin_dev

返回结果如下：

CMakeLists.txt  space_ftparser.cpp

样例代码的核心文件是 space_ftparser.cpp，您可以根据业务需求修改该文件以实现自定义的分词逻辑。

步骤三：编译和安装插件

修改构建配置（CMakeLists.txt）。

在样例代码的根目录下，您会找到一个 CMakeLists.txt 文件。该文件中使用 "TODO" 标记了需要修改的内容，包括以下部分：
- PLUGIN_NAME：当前插件的名称，也是项目和生成的动态链接库的名称。请将其修改为您需要的名称。
- SOURCES：实现文件列表，可以包含 C 或 C++ 源文件。当您新增实现文件时，请在此处添加文件路径。注意不要将头文件列入此列表。
执行编译。

执行下面的步骤进行编译：
1. 切换到工作目录。
```
cd /your/work/path/ftparser
```
  切换到您的分词器插件开发目录。请将 /your/work/path/ftparser 替换为实际的开发目录路径。
2. 创建构建目录。
```
mkdir -p build
```
  创建一个名为 build 的目录，用于存放编译过程中生成的中间文件和最终产物。-p 参数确保即使目录已存在也不会报错。
3. 进入构建目录。
```
cd build
```
  进入刚刚创建的 build 目录。后续的编译操作将在该目录下进行，以保持源码目录的整洁。
4. 配置构建环境。
```
cmake ..
```
  运行 cmake 命令，读取上一级目录中的 CMakeLists.txt 文件，生成编译所需的 Makefile 文件。.. 表示 CMakeLists.txt 文件位于上一级目录中。
5. 编译源码。
```
make
```
  运行 make 命令，根据生成的 Makefile 文件编译源码，生成动态链接库文件（例如 libexample_ftparser.so）。
  
  编译成功后，会在当前目录（即 build 目录）下生成动态链接库文件。
复制编译产物。

编译完成后，会在 build 目录下生成动态链接库文件（例如 libexample_ftparser.so）。将该文件复制到 OceanBase 集群中每个 Observer 节点的 plugin_dir 目录下。
```
cp libexample_ftparser.so /path/to/plugin_dir/
```
将生成的动态链接库文件复制到 OceanBase 的插件目录。请将 /path/to/plugin_dir/ 替换为实际的 plugin_dir 路径（可通过查询系统参数 plugin_dir 获取）。
加载插件。

使用系统租户登录 OceanBase Database AI，修改配置参数 plugins_load 以加载插件：
```
ALTER SYSTEM SET plugins_load='libexample_ftparser.so';
```
重启集群，使插件生效。
- 使用 OceanBase 部署工具（OBD）管理的 OceanBase 集群，可以使用以下命令重启集群。
```
obd cluster restart <cluster_name>
```
  请将 <cluster_name> 替换为实际的集群名称。
- 使用 OceanBase 云平台（OCP）管理的集群，可以在 OCP 上直接重启集群。

查看已安装的分词器插件。

select * from oceanbase.GV$OB_PLUGINS;

返回结果如下：

+-----------+----------+------------------+--------+----------+------------------------+-----------------+------------------+-------------------+-----------------------+---------------+---------------------------------------------+
| SVR_IP    | SVR_PORT | NAME             | STATUS | TYPE     | LIBRARY                | LIBRARY_VERSION | LIBRARY_REVISION | INTERFACE_VERSION | AUTHOR                | LICENSE       | DESCRIPTION                                 |
+-----------+----------+------------------+--------+----------+------------------------+-----------------+------------------+-------------------+-----------------------+---------------+---------------------------------------------+
| 127.0.0.1 |    55801 | ngram            | READY  | FTPARSER | NULL                   | 1.0.0           | NULL             | 0.1.0             | OceanBase Corporation | Mulan PubL v2 | This is a ngram fulltext parser plugin.     |
| 127.0.0.1 |    55801 | beng             | READY  | FTPARSER | NULL                   | 1.0.0           | NULL             | 0.1.0             | OceanBase Corporation | Mulan PubL v2 | This is a basic english parser plugin.      |
| 127.0.0.1 |    55801 | space            | READY  | FTPARSER | NULL                   | 1.0.0           | NULL             | 0.1.0             | OceanBase Corporation | Mulan PubL v2 | This is a default whitespace parser plugin. |
| 127.0.0.1 |    55801 | example_ftparser | READY  | FTPARSER | libexample_ftparser.so | 1.0.0           | NULL             | 0.1.0             | OceanBase Corporation | Mulan PSL v2  | This is an example ftparser.                |
+-----------+----------+------------------+--------+----------+------------------------+-----------------+------------------+-------------------+-----------------------+---------------+---------------------------------------------+

其中 LIBRARY 是 NULL 的表示是内置分词器。

步骤四：测试分词器插件

创建表并使用 WITH PARSER 子句指定分词器 example_ftparser。

CREATE TABLE t_example(
    c1 INT,
    c2 VARCHAR(200),
    c3 TEXT,
    FULLTEXT INDEX (c2, c3) WITH PARSER example_ftparser
);

向表中插入测试数据。

INSERT INTO t_example (c1, c2, c3) VALUES
    (1, 'Alice', 'Alice loves programming and enjoys long walks.'),
    (2, 'Bob', 'Bob is an avid reader and a coffee enthusiast.'),
    (3, 'Charlie', 'Charlie is a skilled musician who plays the guitar.'),
    (4, 'Diana', 'Diana is passionate about painting and arts.'),
    (5, 'Eve', 'Eve is a fitness coach and a healthy lifestyle advocate.');

查询包含关键词 loves 的记录。

SELECT * FROM t_example WHERE MATCH(c2, c3) AGAINST ('loves') > 0;

返回结果如下：

+------+-------+------------------------------------------------+
| c1   | c2    | c3                                             |
+------+-------+------------------------------------------------+
|    1 | Alice | Alice loves programming and enjoys long walks. |
+------+-------+------------------------------------------------+
1 row in set

查询包含关键词 reader 的记录。

SELECT * FROM t_example WHERE MATCH(c2, c3) AGAINST ('reader') > 0;

返回结果如下：

+------+------+------------------------------------------------+
| c1   | c2   | c3                                             |
+------+------+------------------------------------------------+
|    2 | Bob  | Bob is an avid reader and a coffee enthusiast. |
+------+------+------------------------------------------------+
1 row in set

测试分词得分。

SELECT c1, 
    MATCH (c2, c3) AGAINST ('he loves programming and reading') AS score,
    c2,
    c3
FROM t_example;

返回结果如下：

+------+--------------------+---------+----------------------------------------------------------+
| c1   | score              | c2      | c3                                                       |
+------+--------------------+---------+----------------------------------------------------------+
|    1 |  2.665294094128556 | Alice   | Alice loves programming and enjoys long walks.           |
|    2 | 0.2849740932642488 | Bob     | Bob is an avid reader and a coffee enthusiast.           |
|    3 |                  0 | Charlie | Charlie is a skilled musician who plays the guitar.      |
|    4 | 0.2989130434782609 | Diana   | Diana is passionate about painting and arts.             |
|    5 | 0.2722772277227723 | Eve     | Eve is a fitness coach and a healthy lifestyle advocate. |
+------+--------------------+---------+----------------------------------------------------------+
5 rows in set

注意

前提条件

说明

操作步骤

步骤一：安装开发环境

步骤二：获取开发模板

步骤三：编译和安装插件

步骤四：测试分词器插件