Working with Collections

The 3.x API SDKs all work with all features of Collections and Scopes.

The Collections feature in Couchbase Server 7.x is fully implemented in the 3.x API versions of the Couchbase SDKs.

When working with versions earlier than 7.0, the defaultcollection is used from the SDK.

Sample Application

The Travel Sample Application has been updated with a motivating example for Collections - a multi-tenanted travel application. Imagine that we are providing a white-label Flight and Hotel booking service to multiple travel agents. Each tenant agent will get the same underlying service, but interact only with their own data.

The travel-sample bucket has been split into Scopes for multiple tenant travel agents (for example tenant_agent_00, tenant_agent_01, …) and a shared inventory which is further subdivided into Collections such as hotels and airports.

Read more about the new travel-sample Data Model.

The app is currently implemented for the following SDKs:

Example code

In the following example, we will use NULL for default collection, which covers the whole Bucket. To use named Collections (and Scopes), just substitute the Collection (and Scope) name for NULL.

static void store_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPSTORE *resp)
{
    const char *key;
    size_t nkey;
    uint64_t cas;
    lcb_respstore_key(resp, &key, &nkey);
    lcb_respstore_cas(resp, &cas);
    printf("status: %s, key: %.*s, CAS: 0x%" PRIx64 "\n",
       lcb_strerror_short(lcb_respstore_status(resp)), (int)nkey, key, cas);
}

lcb_install_callback3(instance, LCB_CALLBACK_STORE, (lcb_RESPCALLBACK)store_callback);

lcb_STATUS rc;
lcb_CMDSTORE *cmd;
const char *collection = NULL, *scope = NULL;
size_t collection_len = 0, scope_len = 0;
const char *key = "my-document";
const char *value = "{\"name\": \"mike\"}";
rc = lcb_cmdstore_create(&cmd, LCB_STORE_UPSERT);
rc = lcb_cmdstore_collection(cmd, scope, scope_len, collection, collection_len);
rc = lcb_cmdstore_key(cmd, key, strlen(key));
rc = lcb_cmdstore_value(cmd, value, strlen(value));
rc = lcb_store(instance, NULL, cmd);
rc = lcb_cmdstore_destroy(cmd);
rc = lcb_wait(instance);

static void get_callback(lcb_INSTANCE *instance, int cbtype, const lcb_RESPGET *resp)
{
    const char *key, *value;
    size_t nkey, nvalue;
    uint64_t cas;
    lcb_respget_key(resp, &key, &nkey);
    lcb_respget_value(resp, &value, &nvalue);
    lcb_respget_cas(resp, &cas);
    printf("status: %s, key: %.*s, CAS: 0x%" PRIx64 "\n",
       lcb_strerror_short(lcb_respget_status(resp)), (int)nkey, key, cas);
    printf("value:\n%s\n", (int)nvalue, value);
}

lcb_install_callback3(instance, LCB_CALLBACK_GET, (lcb_RESPCALLBACK)get_callback);

lcb_STATUS rc;
lcb_CMDGET *cmd;
const char *collection = NULL, *scope = NULL;
size_t collection_len = 0, scope_len = 0;
const char *key = "my-document";
rc = lcb_cmdget_create(&cmd);
rc = lcb_cmdget_collection(cmd, scope, scope_len, collection, collection_len);
rc = lcb_cmdget_key(cmd, key, strlen(key));
rc = lcb_get(instance, NULL, cmd);
rc = lcb_cmdget_destroy(cmd);
rc = lcb_wait(instance);