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

在這裡記錄鍵不需要顯式銷毀，因為它及其成員均創建於棧。