AerospikeC客户端手册———用户定义函数—应用UDF到记录

应用UDF到记录

Aerospike C客户端API提供aerospike_key_apply()来应用一个用户定义函数到数据库中某记录。

在使用aerospike_key_apply()操作前，包含被应用函数的UDF模块，必须首先注册到Aerospike服务器。请参见【注册用户定义函数】章节来学习如何使用C API注册，或阅读【aql手册】学习如何使用外部工具注册。

下面的代码引用自示例目录【examples/basic_examples/get】，由Aerospike C客户端安装包自带。

请先阅读【创建连接】章节内容，理解如何建立与集群的连接。

定义UDF

函数bin_transform定义在名称为“basice_udf“的模块中。

function bin_transform(record, bin_name, x, y)
    record[bin_name] = (record[bin_name] * x) + y
    aerospike:update(record)
    return record[bin_name]
end

此函数是个有三个参数的简单算法，三 个参数名称分别为”bin_name“、”x“、”y“。它在由“bin_name”指定的bin上执行运算并更新记录数据，然后返回这个bin的运算结果值。

初始化记录键（KEY）

当在记录上应用用户定义函数时，需要通过键（key）在数据库中标识这条记录。下面我们为示例代码创建一个键。用来做键的是字符串（string）”test-key"，数据所在的namespace名称为“test”、set名称为“test-set”。其它数据类型也可用作键，比如：整型（integer）或二进制大对象块（blob）。

as_key key;
as_key_init_str(&key, "test", "test-set", "test-key");

传递参数给UDF

用户定义函数”bin_transform“，要求一个字符串型（string）参数和两个整型（integer）参数，因此需要填充一个参数列表。

as_arraylist args;
as_arraylist_inita(&args, 3);
as_arraylist_append_str(&args, "test-bin-2");
as_arraylist_append_int64(&args, 4);
as_arraylist_append_int64(&args, 400);

在记录上应用UDF

使用记录键，现在可在数据库的指定记录上调用用户定义函数：

as_val * result = NULL;
if (aerospike_key_apply(&as, &err, NULL, &key, "mymodule", "add", 
    (as_list *) &args, &result) != AEROSPIKE_OK) {
    fprintf(stderr, "err(%d) %s at [%s:%d]\n", err.code, err.message, err.file, err.line);
}

UDF函数bin_trransform()的返回值将在参数对象result中返回。

若记录键对应的记录不存在，当UDF函数被发现则返回AEROSPIKE_ERR_RECORD_NOT_FOUND，否则返回UDF运行时错误，错误细节在as_error的成员域中返回。

清理资源

当不再需要返回的结果时，应释放它及其相关资源：

as_val_destroy(&result);

同时，也就清理参数列表：

as_arraylist_destroy(&args);

在这里记录键不需要显式销毁，因为它及其成员均创建于栈。