Multiple operation: documentation clarification

Client Libraries C Client Library
1

Hi, the documentation states following (https://www.aerospike.com/docs/client/c/usage/kvs/multiops.html):

Read operations are performed after all other operations complete. The non-read operation order is defined by the application.

However, take a look into this code (modified map example), that performs 3 operations (read, map_increment, read):

int
main(int argc, char* argv[])
{
    // Parse command line arguments.
    if (! example_get_opts(argc, argv, EXAMPLE_BASIC_OPTS)) {
        exit(-1);
    }
    
    // Connect to the aerospike database cluster.
    aerospike as;
    example_connect_to_aerospike(&as);
    
    // Start clean.
    example_remove_test_record(&as);
    
    // Create hashmap of scores.
    as_hashmap scores;
    as_hashmap_init(&scores, 2);
    as_string  mkey1;
    as_integer mval1;
    as_string_init(&mkey1, "Bob", false);
    as_integer_init(&mval1, 1);
    as_hashmap_set(&scores, (as_val*)&mkey1, (as_val*)&mval1);
    as_string  mkey2;
    as_integer mval2;
    as_string_init(&mkey2, "Jim", false);
    as_integer_init(&mval2, 1);
    as_hashmap_set(&scores, (as_val*)&mkey2, (as_val*)&mval2);
    
    // Write scores to server.
    as_map_policy map_policy;
    as_map_policy_init(&map_policy);

    as_operations ops;
    as_operations_inita(&ops, 1);
    as_operations_add_map_put_items(&ops, map_bin_name, &map_policy, (as_map*)&scores);
    
    as_error err;
    as_record* rec = NULL;
    if (aerospike_key_operate(&as, &err, NULL, &g_key, &ops, &rec) != AEROSPIKE_OK) {
        LOG("aerospike_key_operate() returned %d - %s", err.code, err.message);
        example_cleanup(&as);
        exit(-1);
    }
    as_operations_destroy(&ops);
    as_record_destroy(rec);
    
    as_operations_inita(&ops, 3);

    as_operations_add_read(&ops, map_bin_name);
    
    as_string_init(&mkey1, "Bob", false);
    as_integer_init(&mval1, 1);
    as_operations_add_map_increment(&ops, map_bin_name, &map_policy, (as_val*)&mkey1, (as_val*)&mval1);

    as_operations_add_read(&ops, map_bin_name);

    rec = NULL;
    if (aerospike_key_operate(&as, &err, NULL, &g_key, &ops, &rec) != AEROSPIKE_OK) {
        LOG("aerospike_key_operate() returned %d - %s", err.code, err.message);
        example_cleanup(&as);
        exit(-1);
    }
    as_operations_destroy(&ops);

    as_record_iterator it;
    as_record_iterator_init(&it, rec);


    example_dump_record(rec);

    as_record_destroy(rec);

    // Cleanup and disconnect from the database cluster.
    example_cleanup(&as);
    LOG("map example successfully completed");
    return 0;
}

The operate function returns following results:

generation 2, ttl 2591492, 3 bins:
mapbin : {"Jim":1, "Bob":1}
mapbin : 2
mapbin : {"Jim":1, "Bob":2}

That’s a record with 3 bins, that are named “mabin” (all of them) with different types (MAP, INTEGER, MAP) that correspond (???) with added operation. I’ve took a look into other clients and it looks like this behavior is special for c client. Other clients returns record as ‘map-like’ object with unique ‘keys’.

I’ve found only one mention in the map example in following comment:

// Operations are returned in same order they are added.  Since there is only one operation in
// the aerospike_key_operate() call, the results are located in the first returned bin.

Could you please clarify and complete the documentation https://www.aerospike.com/docs/client/c/usage/kvs/multiops.html, C Client API: Key Operations?

Thanks!

2

Read operations are performed after all other operations complete. The non-read operation order is defined by the application.

This documentation is wrong. Operations are perform in-order regardless of read or write operation since version 3.6. We will fix.

3

Thanks, maybe little more description about returned record from as_key_operate would be worth it. Because a single comment line in an example is more descriptive then the documentation.

I have intuitively thought about a record like about some kind of a map (serialized to an array) - but it’s more like a multi-map (more bins with the same name are contained in a record). (And I’m not able to find anything about it in the documentation.)

4

Documentation has been updated.

https://www.aerospike.com/docs/client/c/usage/kvs/multiops.html