Aerospike C 客戶端最佳實踐：記錄操作完整指南

Aerospike 記錄模型概覽

Aerospike 中的「記錄」是資料庫儲存資料的基本單位，由中繼資料與多個 Bin（資料欄位） 組成。每個 Bin 擁有名稱與值，中繼資料包含版本號、TTL 等資訊。透過 Key（鍵） 定位記錄。

記錄初始化與記憶體管理

提供三種初始化函數，對應不同記憶體分配策略：

重要：無論哪種方式，不再使用時必須呼叫 as_record_destroy() 釋放資源（包含 Bin 值可能佔用的堆積記憶體）。

堆疊分配範例

as_record rec;
as_record_inita(&rec, 3);           // 預分配 3 個 Bin
as_record_set_int64(&rec, "a", 1);
as_record_set_int64(&rec, "b", 2);
as_record_set_int64(&rec, "c", 3);
as_record_destroy(&rec);            // 釋放資源

堆積分配範例

as_record *rec = as_record_new(10);
as_record_set_int64(rec, "a", 1);
as_record_set_int64(rec, "b", 2);
as_record_set_int64(rec, "c", 3);
as_record_destroy(rec);             // 釋放記錄與 Bin

存取 Bin 資料

Getter 函數：取得原生類型值

int64_t ibin = as_record_get_int64(rec, "ibin", 123); // 預設值 123
char *sbin = as_record_get_str(rec, "sbin");          // 字串指標

Getter 函數：取得複雜類型指標（需管理引用計數）

as_list *lbin = (as_list*)as_val_reserve(as_record_get_list(&rec, "lbin"));
as_record_destroy(&rec);  // 此時 lbin 仍有效，因引用計數 +1

int64_t i1 = as_arraylist_get_int64(lbin, 1);
int64_t i2 = as_arraylist_get_int64(lbin, 2);
as_list_destroy(lbin);    // 釋放 list 結構

警告：若未呼叫 as_val_reserve()，銷毀記錄後指標將指向無效記憶體，導致資料損壞。

設定 Bin 值

Setter 函數：原生類型

as_record_set_int64(rec, "ibin", 123);
as_record_set_str(rec, "sbin", "abc");
as_record_set_strp(rec, "spbin", strdup("ijk"), true); // true = 銷毀時釋放字串
as_record_set_raw(rec, "rbin", (uint8_t*)"xyz", 3);

Setter 函數：複雜類型（同樣需管理引用計數）

as_arraylist list;
as_arraylist_init(&list, 3);
as_arraylist_append_int64(&list, 1);
as_arraylist_append_int64(&list, 2);
as_arraylist_append_int64(&list, 3);

as_record rec;
as_record_inita(&rec, 1);
// 關鍵：as_val_reserve 增加引用計數，防止隨記錄銷毀而被釋放
as_record_set_list(&rec, "lbin", (as_list*)as_val_reserve(&list));
as_record_destroy(&rec);

// 記錄銷毀後 list 仍可用
int64_t i1 = as_arraylist_get_int64(&list, 1);
as_arraylist_destroy(&list);

中繼資料操作

世代編號

每次修改遞增，用於樂觀鎖。可手動設定預期版本：

rec->gen = 0;

生存時間

單位為秒，從當前時間起算：

rec->ttl = 3600 * 24; // 24 小時後過期

遍歷記錄所有 Bin

方式一：回調函數 as_record_foreach()

bool callback(const char *name, const as_val *value, void *udata) {
    as_integer *ivalue = as_integer_fromval(value);
    if (ivalue) {
        printf("%s = %d\n", name, as_integer_get(ivalue));
    } else {
        printf("%s is not an integer!\n", name);
    }
    return true; // 繼續遍歷
}

as_record rec;
as_record_inita(&rec, 3);
as_record_set_int64(&rec, "a", 1);
as_record_set_int64(&rec, "b", 2);
as_record_set_int64(&rec, "c", 3);
as_record_foreach(&rec, callback, NULL);

方式二：迭代器 as_record_iterator

as_record_iterator it;
as_record_iterator_init(&it, &rec);
while (as_record_iterator_has_next(&it)) {
    as_bin *bin = as_record_iterator_next(&it);
    char *name = as_bin_get_name(bin);
    as_val *value = (as_val*)as_bin_get_value(bin);
    as_integer *ivalue = as_integer_fromval(value);
    if (ivalue) {
        printf("%s = %d\n", name, as_integer_get(ivalue));
    }
}

讀取操作與記錄填充

讀取操作（aerospike_key_get、aerospike_key_select、aerospike_key_operate）接受 as_record ** 參數接收伺服器回傳資料：

• 傳入 NULL：客戶端自動從堆積分配記錄與足夠 Bin 空間，呼叫端需負責 as_record_destroy()
• 傳入已初始化記錄：
  • Bin 數 > 0：盡可能填充現有 Bin，超出部分忽略
  • Bin 數 = 0：自動從堆積分配足夠 Bin 空間

NULL 記錄範例

as_record *rec = NULL;
aerospike_key_get(&as, &err, NULL, &key, &rec);
// 使用 rec...
as_record_destroy(rec);

預先初始化記錄範例

as_record rec;
as_record_inita(&rec, 10); // 預留 10 個 Bin
aerospike_key_get(&as, &err, NULL, &key, &rec);
// 使用 rec...
as_record_destroy(&rec);