libcouchbase provides a well defined API for
accessing the data stored in a Couchbase cluster. A summary of the
supported methods are listed in
Table 3.1, “C Client Library Method Summary”.
Table 3.1. C Client Library Method Summary
| API Call | lcb_arithmetic (lcb_t instance, const void* cookie, const void* key, size_t nkey, int64_t delta, time_t exptime, bool create, uint64_t initial) | ||
| Asynchronous | no | ||
| Description | Spool an arithmetic operation to the cluster. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
int64_t delta | The delta to increment/decrement | ||
time_t exptime | The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
bool create | Should the key be created if it does not exist? | ||
uint64_t initial | The initial value for the key if created | ||
| Errors | |||
LCB_ETMPFAIL | No vbucket configuration available | ||
LCB_SUCCESS | Command successfully scheduled | ||
| API Call | lcb_arithmetic_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, int64_t delta, time_t exptime, bool create, uint64_t initial) | ||
| Asynchronous | no | ||
| Description | Spool an arithmetic operation to the cluster, but use another key to locate the server. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* hashkey | This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey "user" for the two data keys "user:name" and "user:birthdate". Note that not all clients support this option so it may not be interoperable between clients. | ||
size_t nhashkey | The number of bytes in the alternative key | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
int64_t delta | The delta to increment/decrement | ||
time_t exptime | The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
bool create | Should the key be created if it does not exist? | ||
uint64_t initial | The initial value for the key if created | ||
| Errors | |||
LCB_ETMPFAIL | No vbucket configuration available | ||
LCB_SUCCESS | Command successfully scheduled | ||
| API Call | lcb_connect (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Initiate a connect attempt to the Couchbase cluster to get the serverlist. Please note that this method is asynchronous, so you need to call lcb_wait to wait for the method to compete. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| Errors | |||
LCB_NETWORK_ERROR | If an IO error occurred | ||
LCB_SUCCESS | Command successfully scheduled | ||
LCB_UNKNOWN_HOST | Failed to lookup host name | ||
| API Call | lcb_create (const char* host, const char* user, const char* passwd, const char* bucket, lcb_io_ops_t* iops) | ||
| Asynchronous | no | ||
| Description | lcb_create allocates and initializes an instance of lcb. No connection attempt is at this time. host may be specified as "host:port" and is the REST interface port for the cluster (default: "localhost:8091"). user and password are the username/password combination you want to authenticate as. bucket specifies the bucket you would like to connect to. opps is the io operation structure to use (see lcb_create_io_ops). The bucket name and the username are commonly the same. | ||
| Returns | lcb_t (
The handle to the couchbase instance.
) | ||
| Arguments | |||
const char* host | Hostname | ||
const char* user | Username | ||
const char* passwd | Password | ||
const char* bucket | Bucket name | ||
lcb_io_ops_t* iops | I/O operation structure | ||
| Errors | |||
lcb_t | an instance of lcb on success | ||
NULL | on failure | ||
| API Call | lcb_destroy (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | lcb_destory release all allocated resources and invalidates the lcb instance. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_disable_timings (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Stop recording of timing metrics and release all resources allocated for timing metrics. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_enable_timings (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Start recording of timing metrics for operations against the cluster. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_flush (lcb_t instance, const void* cookie) | ||
| Asynchronous | no | ||
| Description | lcb_flush may be used to remove all key/value pairs from the entire cluster. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
| Errors | |||
LCB_ETMPFAIL | No vbucket configuration available | ||
LCB_SUCCESS | Command successfully scheduled | ||
| API Call | lcb_get_cookie (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Each libcochbase instance may have a single pointer (cookie) associated with it. libcouchbaes_get_cookie retrieves this cookie. | ||
| Returns | const void* (
Pointer to data
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_get_last_error (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Returns the last error that was seen within libcoubhase | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_get_timings (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Retrieve the timing metrics from lcb. TODO fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_mget (lcb_t instance, const void* cookie, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp) | ||
| Asynchronous | no | ||
| Description | Get a number of values from the cache. You need to run the event loop yourself to retrieve the data. You might want to alter the expiry time for the object you're fetching, and to do so you should specify the new expiry time in the exp parameter. To use an ordinary mget use NULL for the exp parameter. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
size_t num_keys | Number of keys | ||
const void * const* keys | Pointer to the array of keys | ||
const size_t* nkeys | Pointer to the array with the length of the keys | ||
const time_t* exp | Pointer to the expiry time | ||
| API Call | lcb_mget_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp) | ||
| Asynchronous | no | ||
| Description | Get a number of values from the cache. You need to run the event loop yourself (or call lcb_execute) to retrieve the data. You might want to alter the expiry time for the object you're fetching, and to do so you should specify the new expiry time in the exp parameter. To use an ordinary mget use NULL for the exp parameter. lcb_mget_by_key differs from lcb_mget that you may use another key to look up the server to retrieve the objects from. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* hashkey | This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey "user" for the two data keys "user:name" and "user:birthdate". Note that not all clients support this option so it may not be interoperable between clients. | ||
size_t nhashkey | The number of bytes in the alternative key | ||
size_t num_keys | Number of keys | ||
const void * const* keys | Pointer to the array of keys | ||
const size_t* nkeys | Pointer to the array with the length of the keys | ||
const time_t* exp | Pointer to the expiry time | ||
| API Call | lcb_mtouch (lcb_t instance, const void* cookie, size_t num_keys, const void * const* keys, const size_t* nkeys, const time_t* exp) | ||
| Asynchronous | no | ||
| Description | Touch (set expiration time) on a number of values in the cache You need to run the event loop yourself (or call lcb_wait) to retrieve the results of the operations. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
size_t num_keys | Number of keys | ||
const void * const* keys | Pointer to the array of keys | ||
const size_t* nkeys | Pointer to the array with the length of the keys | ||
const time_t* exp | Pointer to the expiry time | ||
| API Call | lcb_mtouch_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void * const* keys, const size_t* nkeys, const time_t* exp) | ||
| Asynchronous | no | ||
| Description | Touch (set expiration time) on a number of values in the cache You need to run the event loop yourself (or call lcb_wait) to retrieve the results of the operations. lcb_mtouch_by_key differs from lcb_mtouch that you may use another key to look up the server for the keys. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* hashkey | This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey "user" for the two data keys "user:name" and "user:birthdate". Note that not all clients support this option so it may not be interoperable between clients. | ||
size_t nhashkey | The number of bytes in the alternative key | ||
const void * const* keys | Pointer to the array of keys | ||
const size_t* nkeys | Pointer to the array with the length of the keys | ||
const time_t* exp | Pointer to the expiry time | ||
| API Call | lcb_remove (lcb_t instance, const void* cookie, const void* key, size_t nkey, uint64_t cas) | ||
| Asynchronous | no | ||
| Description | Spool a remove operation to the cluster. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
uint64_t cas | The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously. | ||
| API Call | lcb_remove_by_key (lcb_t instance, const void* cookie, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, uint64_t cas) | ||
| Asynchronous | no | ||
| Description | Spool a remove operation to the cluster. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* hashkey | This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey "user" for the two data keys "user:name" and "user:birthdate". Note that not all clients support this option so it may not be interoperable between clients. | ||
size_t nhashkey | The number of bytes in the alternative key | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
uint64_t cas | The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously. | ||
| API Call | lcb_server_stats (lcb_t instance, const void* cookie, const void* key, size_t nkey) | ||
| Asynchronous | no | ||
| Description | Request server statistics. Without a key specified the server will respond with a "default" set of statistical information. Each statistic is returned in its own packet (key contains the name of the statistical item and the body contains the value in ASCII format). The sequence of return packets is terminated with a packet that contains no key and no value. The command will signal about transfer completion by passing NULL as the server endpoint and 0 for key length. Note that key length will be zero when some server responds with error. In the latter case server endpoint argument will indicate the server address. | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
| API Call | lcb_set_arithmetic_callback (lcb_t instance, lcb_error_callback callback) | ||
| Asynchronous | no | ||
| Description | Specify the callback to be used for all arithmetic operations. The callback will be called whenever the operation completes, and the parameters to the callback will describe the result of the operation. | ||
| Returns | | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
lcb_error_callback callback | The callback function | ||
| API Call | lcb_set_cookie (lcb_t instance, const void* cookie) | ||
| Asynchronous | no | ||
| Description | Each libcochbase instance may have a single pointer (cookie) associated with it. | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
| API Call | lcb_set_error_callback (lcb_t instance, lcb_error_callback callback) | ||
| Asynchronous | no | ||
| Description | Set the callback function to be used by lcb to report errors back to the client. Due to the asyncronous nature of lcb errors may occur outside of the normal access pattern and such problems will be reported through this error handler. | ||
| Returns | | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
lcb_error_callback callback | The callback function | ||
| API Call | lcb_set_flush_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_get_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_remove_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_stat_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_storage_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_tap_deletion_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_tap_flush_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_tap_mutation_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_tap_opaque_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_tap_vbucket_set_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_set_touch_callback (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_store (lcb_t instance, const void* cookie, lcb_storage_t store_operation, const void* key, size_t nkey, const void* bytes, size_t nbytes, flags, time_t exptime, uint64_t cas) | ||
| Asynchronous | no | ||
| Description | Spool a store operation to the cluster. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
lcb_storage_t store_operation | The kind of storage operation (set/replace/add etc.) | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
const void* bytes | A pointer to a memory area containing data | ||
size_t nbytes | Number of bytes used | ||
flags | |||
time_t exptime | The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
uint64_t cas | The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously. | ||
| API Call | lcb_store_by_key (lcb_t instance, const void* cookie, lcb_storage_t store_operation, const void* hashkey, size_t nhashkey, const void* key, size_t nkey, const void* bytes, size_t nbytes, flags, time_t exptime, uint64_t cas) | ||
| Asynchronous | no | ||
| Description | Spool a store operation to the cluster. The operation may be sent immediately, but you won't be sure (or get the result) until you run the event loop (or call lcb_wait). | ||
| Returns | lcb_error_t (
lcb instance
) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
const void* cookie | This is a cookie the client may attach to all requests that will be included in all callbacks. It is not required and may be NULL if you have no need for it. | ||
lcb_storage_t store_operation | The kind of storage operation (set/replace/add etc.) | ||
const void* hashkey | This alternate hashkey allows a client application to group a set of unique keys together to a given server though the keys themselves may be unique. For example, you may wish to use the hashkey "user" for the two data keys "user:name" and "user:birthdate". Note that not all clients support this option so it may not be interoperable between clients. | ||
size_t nhashkey | The number of bytes in the alternative key | ||
const void* key | An identifier in the database | ||
size_t nkey | Number of bytes in the key | ||
const void* bytes | A pointer to a memory area containing data | ||
size_t nbytes | Number of bytes used | ||
flags | |||
time_t exptime | The expiry time for the object. Values larger than 30*24*60*60 seconds (30 days) are interpreted as absolute times (from the epoch). | ||
uint64_t cas | The cas value for an object is guaranteed to be unique for each value of a given key. This value is used to provide simple optimistic concurrency control when multiple clients or threads try to update an item simultaneously. | ||
| API Call | lcb_strerror (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Convert the error code to human readable form. @todo fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_cluster (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_filter_create (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | tap filters are on the client side only, so data still needs to be transferred across the network @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_filter_destroy (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | Invalidate the filter.. @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_filter_get_backfill (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_filter_get_keys_only (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||
| API Call | lcb_tap_filter_set_backfill (lcb_t instance) | ||
| Asynchronous | no | ||
| Description | @fixme | ||
| Returns | (none) | ||
| Arguments | |||
lcb_t instance | The handle to the couchbase instance. | ||