Table Of Contents

7.6. C++

7.6.1. Quick Reference

Return Type Name Arguments
api_buffer;
bool api_buffer::operator==() (const api_buffer & other) const;
bool api_buffer::operator!=() (const api_buffer & other) const;
const char * api_buffer::data() (void) const;
qdb_size_t api_buffer::size() (void) const;
api_buffer_ptr;
const_iterator;
bool const_iterator::operator==() (const const_iterator & other) const;
bool const_iterator::operator!=() (const const_iterator & other) const;
bool const_iterator::operator++() (void);
bool const_iterator::operator--() (void);
const value_type & const_iterator::operator*() (void) const;
const value_type * const_iterator::operator->() (void) const;
qdb_error_t const_iterator::last_error() (void) const;
bool const_iterator::valid() (void) const;
void const_iterator::close() (void);
const_reverse_iterator;
bool const_reverse_iterator::operator==() (const const_reverse_iterator & other) const;
bool const_reverse_iterator::operator!=() (const const_reverse_iterator & other) const;
bool const_reverse_iterator::operator++() (void);
bool const_reverse_iterator::operator--() (void);
const value_type & const_reverse_iterator::operator*() (void) const;
const value_type * const_reverse_iterator::operator->() (void) const;
qdb_error_t const_reverse_iterator::last_error() (void) const;
bool const_reverse_iterator::valid() (void) const;
void const_reverse_iterator::close() (void);
handle;
qdb_error_t handle::attach_tag() (const char * alias, const char * tag);
const_iterator handle::begin() (void);
qdb_error_t handle::blob_put() (const char * alias, const char * content, qdb_size_t content_length, qdb_time_t expiry_time);
qdb_error_t handle::blob_update() (const char * alias, const char * content, qdb_size_t content_length, qdb_time_t expiry_time);
qdb_error_t handle::blob_get_noalloc() (const char * alias, char * content, qdb_size_t * content_length);
api_buffer_ptr handle::blob_get() (const char * alias, qdb_error_t & error);
api_buffer_ptr handle::blob_get_and_remove() (const char * alias, qdb_error_t & error);
api_buffer_ptr handle::blob_get_and_update() (const char * alias, const char * update_content, qdb_size_t update_content_length, qdb_time_t expiry_time, qdb_error_t & error);
api_buffer_ptr handle::blob_compare_and_swap() (const char * alias, const char * new_value, qdb_size_t new_value_length, const char * comparand, qdb_size_t comparand_length, qdb_time_t expiry_time, qdb_error_t & error);
qdb_error_t handle::blob_remove_if() (const char * alias, const char * comparand, qdb_size_t comparand_length);
void handle::close() (void);
qdb_error_t handle::connect() (const char * uri);
bool handle::connected() (void) const;
qdb_error_t handle::detach_tag() (const char * alias, const char * tag);
const_iterator handle::end() (void);
qdb_error_t handle::expires_at() (const char * alias, qdb_time_t expiry_time);
qdb_error_t handle::expires_from_now() (const char * alias, qdb_time_t expiry_delta);
qdb_error_t handle::get_expiry_time() (const char * alias, qdb_time_t & expiry_time);
qdb_error_t handle::get_location() (const char * alias, remote_node & location);
std::vector<std::string> handle::get_tagged() (const char * tag, qdb_error_t & error);
std::vector<std::string> handle::get_tags() (const char * alias, qdb_error_t & error);
qdb_error_t handle::get_type() (const char * alias, qdb_entry_type_t * entry_type);
qdb_error_t handle::int_get() (const char * alias, qdb_int_t * number);
qdb_error_t handle::int_put() (const char * alias, qdb_int_t number, qdb_time_t expiry_time);
qdb_error_t handle::int_update() (const char * alias, qdb_int_t number, qdb_time_t expiry_time);
qdb_error_t handle::int_add() (const char * alias, qdb_int_t addend, qdb_int_t * result = NULL);
qdb_error_t handle::has_tag() (const char * alias, const char * tag);
std::string handle::node_config() (const char * uri, qdb_error_t & error);
std::string handle::node_status() (const char * uri, qdb_error_t & error);
std::string handle::node_topology() (const char * uri, qdb_error_t & error);
handle & handle::operator=() (handle && h);
qdb_error_t handle::purge_all() (void);
const_reverse_iterator handle::rbegin() (void);
qdb_error_t handle::remove() (const char * alias);
const_reverse_iterator handle::rend() (void);
qdb_size_t handle::run_batch() (qdb_operation_t * operations, qdb_size_t operation_count);
std::vector<batch_result> handle::run_batch() (const std::vector<batch_request> & requests, qdb_size_t & success_count);
qdb_error_t handle::run_transaction() (qdb_operation_t * operations, qdb_size_t operation_count, qdb_size_t & fail_index);
qdb_error_t handle::set_compression() (qdb_compression_t comp_level);
qdb_error_t handle::set_timeout() (int timeout);
qdb_error_t handle::stop_node() (const char * uri, const char * reason);
qdb_error_t handle::trim_all() (void);
handle_ptr;
std::string make_error_string() (qdb_error_t err);
api_buffer_ptr make_api_buffer_ptr() (qdb_handle_t h, const char * data, qdb_size_t length);

7.6.2. Introduction

The quasardb C++ API is a wrapper around the C API that brings convenience and flexibility without sacrificing performance. Because the behaviour is similar to the C API, you may wish to familiarize yourself with the C API before working with the C++ API (see C).

7.6.3. Installing

The C++ API package is qdb-capi-<version>, and can be downloaded from the Bureau 14 download site. All information regarding the Bureau 14 download site is in your welcome e-mail. The contents of the C++ API package are:

\qdb-capi-<version>
      \doc        // This documentation
      \example    // C and C++ API examples
      \include    // C and C++ header files
      \lib        // QDB API shared libraries

All functions, typedefs and enums are made available in the include/qdb/client.hpp header file. All classes and methods reside in the qdb namespace.

Both the C and C++ header files must be linked into the client executable. No other linking is required.

7.6.4. The handle object

The handle object is non-copiable. Move semantics are supported through rvalue references but must be enabled by setting the QDBAPI_RVALUE_SUPPORT macro to 1. For example:

#define QDBAPI_RVALUE_SUPPORT 1
#include <qdb/client.hpp>

Handle objects can be used directly with the C API thanks to the overload of the cast operator. They will evaluate to false when not initialized:

qdb::handle h;
// some code...
if (!h) // true if h isn't initialized
{
    // ...
}

// initialization and connection

// removes the entry "myalias" if it exists
qdb_error_t r = qdb_remove(h, "myalias");
if (r != qdb_e_ok)
{
    // error management
}

Caution

Calling qdb_close() on a handle leads to undefined behaviour. Generally speaking it is advised to use the handle object’s methods rather than the C API functions. The cast operator is provided for compatibility only.

Handle objects can also be encapsulated in smart pointers. A definition as handle_ptr is available. This requires a compiler with std::shared_ptr support.

7.6.5. The api_buffer object

The api_buffer object is designed to be used via a smart pointer - whose definition is provided - and is returned by methods from the handle object. It is possible to access the managed buffer directly (read-only) and query its size (see api_buffer::data() and api_buffer::size()).

7.6.6. Connecting to a cluster

The connection requires a handle object and is done with the handle::connect() method:

qdb::handle h;
qdb_error_t r = h.connect("qdb://127.0.0.1:2836");

Handle::connect will both initialize the handle and connect to the cluster. If the connection fails, the handle will be reset. Note that when the handle object goes out of scope, the connection will be terminated and the handle will be released.

Caution

Concurrent calls to connect on the same handle object leads to undefined behaviour.

7.6.7. Adding and getting data to and from a cluster

Although you may use the handle object with the C API, using the handle object’s methods is recommended. For example, to put and get an entry, the C++ way:

const char in_data[10];

qdb_error_t r = h.put("entry", in_data, 0);
if (r != qdb_e_ok)
{
    // error management
}

// ...

char out_data[10];
qdb_error_t r = h.get("entry", out_data, 10);
if (r != qdb_e_ok)
{
    // error management
}

The largest difference between the C and C++ get calls are their memory allocation lifetimes. The C call qdb_get() allocates a buffer of the needed size and must be explicitly freed. The C++ handle.get() method uses uses smart pointers to manage allocations lifetime.

In C, you would write:

char * allocated_content = 0;
qdb_size_t allocated_content_length = 0;
r = qdb_get(handle, "entry", &allocated_content, &allocated_content_length);
if (r != qdb_e_ok)
{
    // error management
}

// ...
// later
// ...

qdb_free_buffer(allocated_content);

In C++, you allocate an api_buffer_ptr and it is released when its reference count reaches zero, like a smart pointer:

qdb_error_t r = qdb_e_ok;
qdb::api_buffer_ptr allocated_content = h.get("entry", r);
if (r != qdb_e_ok)
{
    // error management
}

7.6.8. Closing a connection

A connection can be explicitly closed and the handle released with the handle::close() method:

h.close();

Note that when the handle object is destroyed, handle::close() is automatically called.

Caution

The usage of qdb_close() with handle object results in undefined behaviour.

7.6.9. Expiry

Expiry is set with handle::expires_at() and expires_from_now(). It is obtained with handle::get_expiry_time(). Expiry time is always in seconds, either relative to epoch (January 1st, 1970 00:00 UTC) when using handle::expires_at() or relative to the call time when using expires_from_now().

Danger

The behavior of expires_from_now() is undefined if the time zone or the clock of the client computer is improperly configured.

To set the expiry time of an entry to 1 minute, relative to the call time:

char content[100];

// ...

r = h.put("myalias", content, sizeof(content), 0);
if (r != qdb_error_ok)
{
    // error management
}

r = h.expires_from_now("myalias", 60);
if (r != qdb_error_ok)
{
    // error management
}

To prevent an entry from ever expiring:

r = h.expires_at("myalias", 0);
if (r != qdb_error_ok)
{
    // error management
}

By default, entries do not expire. To obtain the expiry time of an existing entry:

qdb_time_t expiry_time = 0;
r = h.get_expiry_time("myalias", &expiry_time);
if (r != qdb_error_ok)
{
    // error management
}

7.6.10. Batch operations

Batch operations are used similarly as in C, except a method handle::run_batch() is provided for convenience.

7.6.11. Iteration

Iteration on the cluster’s entries can be done forward and backward.

An STL-like iterator API is provided which is compatible with STL algorithms:

// forward loop
std::for_each(h.begin(), h.end(), [](const qdb::const_iterator::value_type & v)
{
    // work on the entry
    // v.first is an std::string refering to the entry's alias
    // v.second is qdb::api_buffer_ptr with the entry's content
});

// backward loop
std::for_each(h.rbegin(), h.rend(), [](const qdb::const_reverse_iterator::value_type & v) { /* work on the entry */ });

There is however a significant difference with regular STL iterators: since entries are accessed remotely, an error may prevent the next entry from being retrieved, in which case the iterator will be considered to have reached the “end” of the iteration.

It is however possible to query the last error through the last_error() member function. The qdb_e_alias_not_found indicates the normal end of the iteration whereas other error statuses indicate that the iteration could not successfully complete. It is up to the programmer to decide what to do in case of error.

Iterators’ value is a std::pair<std::string, qdb::api_buffer_ptr> which makes the manipulation of iterator associated data safe in most scenarii. Associated resources will be freed automatically through RAII.

The iterator api may throw the std::bad_alloc exception should a memory allocation fail.

Note

Although each entry is returned only once, the order in which entries are returned is undefined.

7.6.12. Exceptions

The quasardb C++ API does not throw any exception on its behalf, however situations such as low memory conditions may cause exceptions to be thrown.

7.6.13. Reference

namespace qdb

Typedefs

typedef qdb::shared_ptr<handle>::type handle_ptr

Functions

std::string make_error_string(qdb_error_t error)

Variables

const qdb_time_t never_expires = qdb_never_expires
const qdb_time_t preserve_expiration = qdb_preserve_expiration
class handle

Public Functions

const_iterator begin()

STLesque iterators with a twist,.

Return
A forward iterator pointing to the first entry in the cluster.

const_iterator end()

End iterator.

Return
A forward iterator pointing beyond the last entry in the cluster.

const_reverse_iterator rbegin()

Constant reverse begin iterator.

Return
A reverse iterator pointing to the last entry in the cluster.

const_reverse_iterator rend()

Constant reverse end iterator.

Return
A reverse iterator pointing before the first entry in the cluster.

void close()

Closes the handle and release all associated resources.

Warning
Not thread-safe

bool connected() const

Determines if the handle is connected or not.

Return
True if the handle is connected, false otherwise

qdb_error_t set_timeout(int timeout_ms)

Sets the timeout, for all operations.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • timeout_ms: The timeout in milliseconds

qdb_error_t set_compression(qdb_compression_t comp_level)

Sets the compression level for all network calls.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • comp_level: The compression level.

qdb_error_t connect(const char *uri)

Initializes all required resources and connect to a remote host.

Connects to the remote host in TCP if a connection is already opened, it will be closed the internal handle will be updated if and only if the connection is successful

Return
A qdb_error_t code indicating success or failure.
Remark
Not thread-safe
Parameters
  • uri: A pointer to a null-terminated string in the format qdb://host:port[,host:port].

qdb_error_t blob_put(const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)

Adds an entry to the quasardb server. If the entry already exists the method will fail and will return qdb_e_alias_already_exists.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias to create.
  • content: A pointer to a buffer that represents the entry’s content to be added to the server.
  • content_length: The length of the entry’s content, in bytes.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch

qdb_error_t int_get(const char *alias, qdb_int_t *number)

Retrieves the value of an integer. The integer must already exist.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias.
  • number: The value of the retrieved qdb_int_t.

qdb_error_t int_put(const char *alias, qdb_int_t number, qdb_time_t expiry_time)

Creates a new integer. Errors if the integer already exists.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias.
  • number: The value of the retrieved qdb_int_t.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch

qdb_error_t int_update(const char *alias, qdb_int_t number, qdb_time_t expiry_time)

Updates an existing integer or creates one if it does not exist.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias.
  • number: The value of the retrieved qdb_int_t.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch

qdb_error_t int_add(const char *alias, qdb_int_t addend, qdb_int_t *result = NULL)

Atomically addes the value to the integer. The integer must already exist.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias.
  • addend: The value that will be added to the existing qdb_int_t.
  • result: A pointer that will be updated to point to the new qdb_int_t.

qdb_error_t blob_update(const char *alias, const void *content, qdb_size_t content_length, qdb_time_t expiry_time)

Updates an entry on the quasardb server.

If the entry already exists, the content will be updated. If the entry does not exist, it will be created. The handle must be initialized and connected (see :func:connect).

Return
A qdb_error_t code indicating success or failure.
Warning
This function is experimental.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias to update.
  • content: A pointer to a buffer buffer that represents the entry’s content to be updated to the server.
  • content_length: The length of the entry’s content, in bytes.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch

qdb_error_t blob_get_noalloc(const char *alias, void *content, qdb_size_t *content_length)

Retrieves an entry’s content from the quasardb server. The caller is responsible for allocating and freeing the provided buffer.

If the entry does not exist, the method will fail and return qdb_e_alias_not_found

If the buffer is not large enough to hold the data, the function will fail and return qdb_e_buffer_too_small. content_length will nevertheless be updated with entry size so that the caller may resize its buffer and try again.

The handle must be initialized and connected (see :func:connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias to be retrieved.
  • content: A pointer to an user allocated buffer that will receive the entry’s content.
  • content_length: A pointer to a qdb_size_t initialized with the length of the destination buffer, in bytes. It will be updated with the length of the retrieved content, even if the buffer is not large enough to hold all the data.

size_t run_batch(qdb_operation_t *operations, size_t operation_count)

Runs the provided operations in batch on the cluster. The operations are run in arbitrary order.

It is preferred to use the std::vector version of run_batch where possible.

Return
The number of successful operations
Parameters
  • operations: Pointer to an array of qdb_operation_t
  • operation_count: Size of the array, in entry count

qdb_error_t run_transaction(qdb_operation_t *operations, size_t operation_count, size_t &fail_index)

Runs the provided operations as a transaction on the cluster. The operations are run in the provided order. If any operation fails, all previously run operations are rolled back.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • operations: Pointer to an array of qdb_operation_t
  • operation_count: Size of the array, in entry count
  • fail_index: The index in the operations array for the operation that failed.

api_buffer_ptr blob_get(const char *alias, qdb_error_t &error)

Retrieves an entry’s content from the quasardb server.

If the entry does not exist, the function will fail and update error to qdb_e_alias_not_found

The function will allocate a buffer large enough to hold the entry’s content.

The handle must be initialized and connected (see connect).

Return
An api_buffer_ptr holding the entry content, if it exists, a null pointer otherwise.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias whose content is to be retrieved.
  • error: A reference to an error that will receive the result of the operation.

api_buffer_ptr blob_get_and_remove(const char *alias, qdb_error_t &error)

Atomically gets an entry from the quasardb server and removes it. If the entry does not exist, the function will fail and update error to qdb_e_alias_not_found.

The function will allocate a buffer large enough to hold the entry’s content.

The handle must be initialized and connected (see connect).

Return
An api_buffer_ptr holding the entry content, if it exists, a null pointer otherwise.
Parameters
  • alias: A pointer to a null-terminated string representing the entry’s alias whose content is to be retrieved.
  • error: A reference to an error that will receive the result of the operation.

api_buffer_ptr blob_get_and_update(const char *alias, const void *update_content, qdb_size_t update_content_length, qdb_time_t expiry_time, qdb_error_t &error)

Atomically gets and updates(in this order) the entry on the quasardb server.The entry must already exist.

The handle must be initialized and connected(see :func:connect).

Return
An api_buffer_ptr holding the entry content, if it exists, a null pointer otherwise.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias to update.
  • update_content: A pointer to a buffer that represents the entry’s content to be updated to the server.
  • update_content_length: The length of the buffer, in bytes.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch
  • error: A reference to an error that will receive the result of the operation.

api_buffer_ptr blob_compare_and_swap(const char *alias, const void *new_value, qdb_size_t new_value_length, const void *comparand, qdb_size_t comparand_length, qdb_time_t expiry_time, qdb_error_t &error)

Atomically compares the entry with comparand and updates it to new_value if, and only if, they match.Always return the original value of the entry.

The handle must be initialized and connected(see :func:connect).

Return
An api_buffer_ptr holding the entry content, if it exists, a null pointer otherwise.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias to compare to.
  • new_value: A pointer to a buffer that represents the entry’s content to be updated to the server in case of match.
  • new_value_length: The length of the buffer, in bytes.
  • comparand: A pointer to a buffer that represents the entry’s content to be compared to.
  • comparand_length: The length of the buffer, in bytes.
  • expiry_time: The absolute expiry time of the entry, in seconds, relative to epoch
  • error: A reference to an error that will receive the result of the operation.

qdb_error_t expires_at(const char *alias, qdb_time_t expiry_time)

Sets the expiry time of an existing entry from the quasardb cluster.A value of zero means the entry never expires.

The handle must be initialized and connected(see connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias for which the expiry must be set.
  • expiry_time: Absolute time after which the entry expires

qdb_error_t expires_from_now(const char *alias, qdb_time_t expiry_delta)

Sets the expiry time of an existing entry from the quasardb cluster. A value of zero means the entry expires as soon as possible.

The handle must be initialized and connected(see :func:connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias for which the expiry must be set.
  • expiry_delta: Time in seconds, relative to the call time, after which the entry expires

qdb_error_t get_expiry_time(const char *alias, qdb_time_t &expiry_time)

Retrieves the expiry time of an existing entry. A value of zero means the entry never expires.

The handle must be initialized and connected(see connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias for which the expiry must be get.
  • expiry_time: : A pointer to a qdb_time_t that will receive the absolute expiry time.

qdb_error_t get_location(const char *alias, remote_node &location)

Retrieves an array of locations where the entry is stored in the cluster.

The handle must be initialized(see qdb_open and qdb_open_tcp) and the connection established(see qdb_connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias.
  • location: A pointer to a qdb_remote_node_t that will receive the entry locations.

qdb_error_t get_metadata(const char *alias, qdb_entry_metadata_t *entry_metadata)

Retrieves the type of the entry.

The handle must be initialized(see qdb_open and qdb_open_tcp) and the connection established(see qdb_connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias.
  • entry_metadata: : A pointer to a qdb_entry_metadata_t that will receive the entry locations.

std::string node_status(const char *uri, qdb_error_t &error)

Obtains a node status as a JSON string.

The handle must be initialized and connected(see : func : connect).

Return
The status of the node as a JSON string.
Parameters
  • uri: A pointer to a null - terminated string in the format qdb://host:port
  • error: A reference to an error code that will be updated according to the success of the operation

std::string node_config(const char *uri, qdb_error_t &error)

Obtains a node configuration as a JSON string.

The handle must be initialized and connected(see : func : connect).

Return
The configuration of the node as a JSON string.
Parameters
  • uri: A pointer to a null - terminated string in the format qdb://host:port
  • error: A reference to an error code that will be updated according to the success of the operation

std::string node_topology(const char *uri, qdb_error_t &error)

Obtains a node topology as a JSON string.

The handle must be initialized and connected(see : func : connect).

Return
The topology of the node as a JSON string.
Parameters
  • uri: A pointer to a null - terminated string in the format qdb://host:port
  • error: A reference to an error code that will be updated according to the success of the operation

qdb_error_t node_stop(const char *uri, const char *reason)

Stops the node designated by its host and port number. This stop is generally effective a couple of seconds after it has been issued, enabling inflight calls to complete successfully.

The handle must be initialized and connected(see :func:connect).

Return
A qdb_error_t code indicating success or failure.
Warning
This function is meant for very specific use cases and its usage is discouraged.
Parameters
  • uri: A pointer to a null - terminated string in the format qdb://host:port.
  • reason: A pointer to a null - terminated string detailling the reason for the stop that will appear in the remote node’s log.

qdb_error_t remove(const char *alias)

Removes an entry from the quasardb server. If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

The handle must be initialized and connected(see connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias to delete.

qdb_error_t blob_remove_if(const char *alias, const void *comparand, qdb_size_t comparand_length)

Removes an entry from the quasardb server if it matches comparand. The operation is atomic. If the entry does not exist, the function will fail and return qdb_e_alias_not_found.

The handle must be initialized and connected(see :func:connect).

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null - terminated string representing the entry’s alias to delete.
  • comparand: A pointer to a buffer that represents the entry’s content to be compared to.
  • comparand_length: The length of the buffer, in bytes.

std::vector<std::string> blob_scan(const void *pattern, qdb_size_t pattern_length, qdb_int_t max_count, qdb_error_t &error)

Scans blobs for a given pattern.

Return
A vector of size atmost pattern_length of blob aliases matching the pattern
Warning
Experimental function.
Parameters
  • pattern: A const void pointer representing the string to scan
  • pattern_length: The length of the pattern
  • max_count: The maximum number of results to fetch
  • error: A reference to qdb_error_t error.

std::vector<std::string> blob_scan_regex(const char *pattern, qdb_int_t max_count, qdb_error_t &error)

Scans blobs for a given regex pattern.

Return
A vector of size atmost pattern_length of blob aliases matching the pattern
Warning
Experimental function.
Parameters
  • pattern: A const void pointer representing the string to scan
  • max_count: The maximum number of results to fetch
  • error: A reference to qdb_error_t error.

std::vector<std::string> prefix_get(const char *prefix, qdb_int_t max_count, qdb_error_t &error)

Retrieves the list of all entries matching the provided prefix.

A prefix-based search will enable you to find all entries matching a provided prefix.

This function return the list of aliases. It’s up to the user to query the content associated with every entry, if needed.

Return
A vector of string aliases matching the prefix pattern
Parameters
  • prefix: A pointer to a null-terminated UTF-8 string representing the desired prefix
  • max_count: An integer limiting the number of results returned by the function
  • error: A reference to qdb_error_t error.

qdb_uint_t prefix_count(const char *prefix, qdb_error_t &error)

Retrieves the count of all entries matching the provided prefix.

A prefix-based count counts all entries matching a provided prefix.

Return
A count of aliases matching the prefix
Parameters
  • prefix: A pointer to a null-terminated UTF-8 string representing the desired prefix.
  • error: A reference to qdb_error_t error.

std::vector<std::string> suffix_get(const char *suffix, qdb_int_t max_count, qdb_error_t &error)

Retrieves the list of all entries matching the provided suffix.

A suffix-based search will enable you to find all entries matching a provided suffix.

This function return the list of aliases. It’s up to the user to query the content associated with every entry, if needed.

Return
A vector of string aliases matching the suffix pattern
Parameters
  • suffix: A pointer to a null-terminated UTF-8 string representing the desired suffix
  • max_count: An integer limiting the number of results returned by the function
  • error: A reference to qdb_error_t error.

qdb_uint_t suffix_count(const char *suffix, qdb_error_t &error)

Retrieves the count of all entries matching the provided suffix.

A suffix-based count counts all entries matching a provided suffix.

Return
A count of aliases matching the suffix
Parameters
  • suffix: A pointer to a null-terminated UTF-8 string representing the desired suffix.
  • error: A reference to qdb_error_t error.

qdb_error_t attach_tag(const char *alias, const char *tag)

Adds a tag to an entry.

Tagging an entry enables you to search for entries based on their tags. Tags scale across nodes.

The entry must exist.

The tag may or may not exist.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated UTF-8 string representing the alias of the entry to which the tag must be added.
  • tag: A pointer to a null-terminated UTF-8 string representing the tag to add to the entry

qdb_error_t has_tag(const char *alias, const char *tag)

Tests if an entry has the request tag.

Tagging an entry enables you to search for entries based on their tags. Tags scale across nodes.

The entry must exist.

If you need to test several entries and/or several tags, consider using a batch for maximum performance.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated UTF-8 string representing the alias of the entry to which the tag must be tested.
  • tag: A pointer to a null-terminated UTF-8 string representing the tag for which presence must be tested

qdb_error_t detach_tag(const char *alias, const char *tag)

Removes a tag from an entry.

Tagging an entry enables you to search for entries based on their tags. Tags scale across nodes.

The entry must exist.

The tag must exist.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • alias: A pointer to a null-terminated UTF-8 string representing the alias of the entry to which the tag must be remove.
  • tag: A pointer to a null-terminated UTF-8 string representing the tag to remove.

std::vector<std::string> get_tagged(const char *tag, qdb_error_t &error)

Retrieves all entries that have the specified tag.

Tagging an entry enables you to search for entries based on their tags. Tags scale across nodes.

The tag must exist.

The complexity of this function is constant.

Consider using qdb_tag_iterator_begin if you expect the number of entries to be very large.

Consider using iteration on tags for large tags.

Return
A std::vector containing the aliases tagged with the tag.
Parameters
  • tag: A pointer to a null-terminated UTF-8 string representing the tag for which to search entries.
  • error: A reference to qdb_error_t error.

qdb_uint_t get_tagged_count(const char *tag, qdb_error_t &error)

Computes the approximate count of all entries matching the specified tag, up to the configured max cardinality.

Return
Number of entries with the input tag
Parameters
  • tag: A pointer to a null-terminated UTF-8 string representing the tag for which to search entries.
  • error: A reference to qdb_error_t error.

std::vector<std::string> get_tags(const char *alias, qdb_error_t &error)

Retrieves all the tags of an entry.

Tagging an entry enables you to search for entries based on their tags. Tags scale across nodes.

The entry must exist.

Return
A std::vector containing the tags assigned to the alias.
Parameters
  • alias: A pointer to a null-terminated UTF-8 string representing the alias of the entry to which the tag must be added.
  • error: A reference to qdb_error_t error.

const_tag_iterator tag_begin(const char *tag)

Creates an iterator that will point to the first entry having the the specified tag.

The order in which iteration occurs is unspecified, but entries matching a tag will never appear twice.

Only forward iteration is currently supported.

Once iteration terminates, the caller is responsible for releasing API-allocated resources with qdb_tag_iterator_close

If you expect the number of entries to be very small, you might consider using qdb_get_tagged.

Return
A constant tag begin iterator
Parameters
  • tag: A pointer to a null-terminated UTF-8 string representing the tag on which iteration is requested

const_tag_iterator tag_end()

Creates an iterator that will point to the next to last entry having the specified tag.

Return
A constant tag end iterator

qdb_error_t purge_all(int timeout_ms)

Removes all the entries on all the nodes of the quasardb cluster. The function return when the command has been dispatched and executed on the whole cluster or an error occurred.

This call is * not* atomic; if the command cannot be dispatched on the whole cluster, it will be dispatched on as many nodes as possible and the function will return with a qdb_e_ok code.

The handle must be initialized and connected(see connect).

Return
A qdb_error_t code indicating success or failure.
Warning
This function is meant for very specific use cases and its usage is discouraged.

qdb_error_t trim_all(int timeout_ms)

Manually runs the garbage collector, removing stale versions of entries from the cluster. This may free a small portion of disk space or memory.

This call is not atomic: if the command cannot be dispatched on the whole cluster, it will be dispatched on as many nodes as possible and the function will return with a qdb_e_ok code.

The handle must be initialized(see qdb_open and qdb_open_tcp) and the connection established(see qdb_connect).

Return
A qdb_error_t code indicating success or failure.

qdb_error_t purge_cache(int timeout_ms)

Removes all cached data from all the nodes of the cluster.

This function is disabled on a transient cluster. Prefer purge_all in this case.

This call is not atomic: if the command cannot be dispatched on the whole cluster, it will be dispatched on as many nodes as possible and the function will return with a qdb_e_ok code.

Return
A qdb_error_t code indicating success or failure.
Parameters
  • timeout_ms: A timeout value, in milliseconds.

arrow_backPrevious
7.5. Performance profiling
Next arrow_forward
7.7. Go