Sphinx UDF example


Many databases and search engines allow you to customize your queries using your own so called “user defined functions” or UDF. Sphinx and Manticore are not exceptions. There’s a long section in documentation about this – https://docs.manticoresearch.com/latest/html/extending.html#udfs-user-defined-functions

Here I want to give just a quick example of how you can make a UDF which enables some fucntionality which can be really useful in some cases, but missing out of the box – sleep() function.

First of all create the code of your UDF in C:

[snikolaev@dev01 ~]$ cat sleep.c
#include </home/snikolaev/./manticore_gitlab/src/sphinxudf.h>

int sleep_ver() {

sphinx_int64_t sleep ( SPH_UDF_INIT * init, SPH_UDF_ARGS * args, char * error_flag ) {
	usleep(*args->arg_values[0] * 1000000);

As you can see it has only 2 functions:

  • sleep_ver() returning just current SPH_UDF_VERSION from the included sphinxudf.h
  • and sleep() which does the job – sleeps the number of seconds provided in argument #1

HINT: Make sure your file has extension “.c”, not “.cpp”, otherwise it may not work.

Next you need to build your library:

[snikolaev@dev01 ~]$ gcc sleep.c -shared -o sleep.so -g -fPIC
[snikolaev@dev01 ~]$

You now have sleep.so which includes your function:

[snikolaev@dev01 ~]$ ls -la sleep.so
-rwx--x--x 1 snikolaev snikolaev 8209 Sep 10 04:37 sleep.so

Next make sure you specify in your config where searchd should look for UDFs using plugin_dir directive:

plugin_dir = /home/snikolaev

Now run your searchd and create the function:

mysql> create function sleep returns int soname 'sleep.so';
Query OK, 0 rows affected (0.00 sec)

HINT: if you do not want to do it every time you start searchd you can put the command to a file:

[snikolaev@dev01 ~]$ cat state.sql

and use

sphinxql_state = state.sql

in the searchd section of your config so it runs the command on start.

Once you have the function registered in the searchd you can use it:

mysql> select sleep(1);
| sleep(1) |
| 0 |
1 row in set (1.00 sec)

If you have any questions about Sphinx UDFs don’t hesitate to ask us on our forum or in our public slack channel.

Leave a Reply