分词器插件

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

前提条件

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

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

  说明

  如果您使用的系统不支持 yum，可以通过其他方式安装上述依赖项，例如手动下载 RPM 包或使用其他包管理工具。

• 已部署正常运行的 OceanBase 数据库集群。

• 具备系统租户权限，用于修改配置参数和重启集群。

操作步骤

步骤一：安装开发环境

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

1. 安装基础编译工具。

   安装了编译 C/C++ 程序所需的基本工具和库。

   yum install -y cmake make glibc-devel glibc-headers gcc gcc-c++
   

2. 配置 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
      

3. 安装插件开发套件。

   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，您可以根据业务需求修改该文件以实现自定义的分词逻辑。

步骤三：编译和安装插件

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

   在样例代码的根目录下，您会找到一个 CMakeLists.txt 文件。该文件中使用 "TODO" 标记了需要修改的内容，包括以下部分：

   • PLUGIN_NAME：当前插件的名称，也是项目和生成的动态链接库的名称。请将其修改为您需要的名称。
   • SOURCES：实现文件列表，可以包含 C 或 C++ 源文件。当您新增实现文件时，请在此处添加文件路径。注意不要将头文件列入此列表。

2. 执行编译。

   执行下面的步骤进行编译：

   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 目录）下生成动态链接库文件。

3. 复制编译产物。

   编译完成后，会在 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 获取）。

4. 加载插件。

   使用系统租户登录 OceanBase 数据库，修改配置参数 plugins_load 以加载插件：

   ALTER SYSTEM SET plugins_load='libexample_ftparser.so';
   

5. 重启集群，使插件生效。

   • 使用 OceanBase 部署工具（OBD）管理的 OceanBase 集群，可以使用以下命令重启集群。

     obd cluster restart <cluster_name>
     

     请将 <cluster_name> 替换为实际的集群名称。

   • 使用 OceanBase 云平台（OCP）管理的集群，可以在 OCP 上直接重启集群。

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

   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 的表示是内置分词器。

步骤四：测试分词器插件

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

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

2. 向表中插入测试数据。

   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.');
   

3. 查询包含关键词 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
   

4. 查询包含关键词 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
   

5. 测试分词得分。

   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