quasardb C API: General client functions

quasardb C API

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
General client functions

## Data Structures
struct | qdb_string_t
| A structure representing a character string of the given length. More...
struct | qdb_timespec_t
| A structure representing an elapsed time since epoch (cross-platform equivalent of timespec structure) More...
struct | qdb_remote_node_t
| A structure representing the address of a quasardb node. More...
struct | qdb_id_t
| A cluster-wide unique identifier. More...
struct | qdb_entry_metadata_t
| A structure representing the metadata of an entry in the database. More...

## Macros
#define | qdb_never_expires ((qdb_time_t)0u)
| An arbitrary time value representing the "no expiration" time value. More...
#define | qdb_preserve_expiration ((qdb_time_t)0xFFFFFFFFFFFFFFFFULL)
| An arbitrary time value representing the "preserve existing expiration" time value. More...

## Typedefs
typedef enum qdb_limits_t | qdb_limits_t
| An enumeration of API limits.
typedef long long | qdb_time_t
| A cross-platform type that represents a time value. More...
typedef size_t | qdb_size_t
| An alias for size_t.
typedef int64_t | qdb_int_t
| A cross-platform type that represents a signed 64-bit integer.
typedef struct qdb_handle_internal * | qdb_handle_t
| An opaque handle to internal API-allocated structures needed for maintaining connection to a cluster.
typedef struct qdb_direct_handle_internal * | qdb_direct_handle_t
| An opaque handle to internal API-allocated structures needed for maintaining a direct connection to a cluster.

## Enumerations
enum | qdb_limits_t { qdb_l_max_alias_length = 1024, qdb_l_alias_max_length = qdb_l_max_alias_length, qdb_l_max_user_name_length = 120, qdb_max_user_name_length = qdb_l_max_user_name_length }
| An enumeration of API limits. More...
enum | qdb_protocol_t { qdb_p_tcp = 0 }
| An enumeration of allowed network protocols. More...
enum | qdb_entry_type_t { qdb_entry_uninitialized = -1, qdb_entry_blob = 0, qdb_entry_integer = 1, qdb_entry_hset = 2, qdb_entry_tag = 3, qdb_entry_deque = 4, qdb_entry_stream = 5, qdb_entry_ts = 6 }
| A enumeration representing possible entries type. More...
enum | qdb_compact_options_t { qdb_compact_full = 0, qdb_compact_piecewise = 1 }
| An enumeration of compact options. More...

## Functions
QDB_API_LINKAGE const char * | qdb_version (void)
| Returns a null-terminated string describing the API version. More...
QDB_API_LINKAGE const char * | qdb_build (void)
| Returns a null-terminated string describing the exact API build. More...
QDB_API_LINKAGE qdb_error_t | qdb_open (qdb_handle_t *handle, qdb_protocol_t proto)
| Creates a qdb_handle_t. No connection will be established. More...
QDB_API_LINKAGE qdb_handle_t | qdb_open_tcp (void)
| Creates a TCP/IP qdb_handle_t. No connection will be established. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_last_error (qdb_handle_t handle, qdb_error_t *error, qdb_string_t *message)
| Describes the last error code returned from the given handle. More...
QDB_API_LINKAGE qdb_error_t | qdb_connect (qdb_handle_t handle, const char *uri)
| Binds the client instance to a quasardb cluster and connect to at least one node within. More...
QDB_API_LINKAGE qdb_error_t | qdb_close (qdb_handle_t handle)
| Closes the handle previously opened with qdb_open or qdb_open_tcp. More...
QDB_API_LINKAGE qdb_error_t | qdb_copy_alloc_buffer (qdb_handle_t handle, const void *source_buffer, qdb_size_t source_buffer_size, const void **dest_buffer)
| Creates a clone of a buffer using API's high-performance memory allocator. More...
QDB_API_LINKAGE void | qdb_release (qdb_handle_t handle, const void *buffer)
| Releases an API-allocated buffer. More...
QDB_API_LINKAGE qdb_error_t | qdb_remove (qdb_handle_t handle, const char *alias)
| Removes an entry from the cluster, regardless of its type. More...
QDB_API_LINKAGE qdb_error_t | qdb_expires_at (qdb_handle_t handle, const char *alias, qdb_time_t expiry_time)
| Sets the absolute expiration time of an entry, if the type supports expiration. More...
QDB_API_LINKAGE qdb_error_t | qdb_expires_from_now (qdb_handle_t handle, const char *alias, qdb_time_t expiry_delta)
| Sets the expiration time of an entry, relative to the current time of the client, if the type supports expiration. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_expiry_time (qdb_handle_t handle, const char *alias, qdb_time_t *expiry_time)
| Retrieves the absolute expiration time of the given entry. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_location (qdb_handle_t handle, const char *alias, qdb_remote_node_t *location)
| Returns the primary node of an entry. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_type (qdb_handle_t handle, const char *alias, qdb_entry_type_t *entry_type)
| Gets the type of an entry, if it exists. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_metadata (qdb_handle_t handle, const char *alias, qdb_entry_metadata_t *entry_metadata)
| Gets the meta-information about an entry, if it exists. More...
QDB_API_LINKAGE qdb_error_t | qdb_get_metadata_by_id (qdb_handle_t handle, const qdb_id_t *reference, qdb_entry_metadata_t *entry_metadata)
| Gets the meta-information about an entry, if it exists. More...
QDB_API_LINKAGE qdb_error_t | qdb_purge_all (qdb_handle_t handle, int timeout_ms)
| Removes irremediably all data from all the nodes of the cluster. More...
QDB_API_LINKAGE qdb_error_t | qdb_trim_all (qdb_handle_t handle, int timeout_ms)
| Trims all data on all the nodes of the cluster. More...
QDB_API_LINKAGE qdb_error_t | qdb_cluster_compact (qdb_handle_t handle, qdb_compact_options_t options, int timeout_ms)
| Compacts all data in the persistence layer on all the nodes of the cluster. More...
QDB_API_LINKAGE qdb_error_t | qdb_purge_cache (qdb_handle_t handle, int timeout_ms)
| Removes all cached data from all the nodes of the cluster. More...
QDB_API_LINKAGE qdb_error_t | qdb_wait_for_stabilization (qdb_handle_t handle, int timeout_ms)
| Wait for all nodes of the cluster to be stabilized. More...
QDB_API_LINKAGE qdb_error_t | qdb_cluster_endpoints (qdb_handle_t handle, qdb_remote_node_t **endpoints, qdb_size_t *endpoints_count)
| Retrieve a sorted array of endpoints. More...
QDB_API_LINKAGE qdb_error_t | qdb_cluster_reload_user_config (qdb_handle_t handle)
| Reload user configuration from file. More...
QDB_API_LINKAGE const char * | qdb_error (qdb_error_t error)
| Translates an error code into an English error message. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_copy_results (qdb_handle_t handle, const qdb_query_result_t *result, qdb_query_result_t **result_copy)
| Creates a clone of a query result. More...
QDB_API_LINKAGE qdb_error_t | qdb_tag_iterator_copy (const qdb_const_tag_iterator_t *original, qdb_const_tag_iterator_t *copy)
| Clones a previously initialized tag iterator. More...

## Detailed Description

## Macro Definition Documentation

#define qdb_never_expires ((qdb_time_t)0u)

An arbitrary time value representing the "no expiration" time value.

See Also
  qdb_time_t

#define qdb_preserve_expiration ((qdb_time_t)0xFFFFFFFFFFFFFFFFULL)

An arbitrary time value representing the "preserve existing expiration" time value.

See Also
  qdb_time_t

## Typedef Documentation

qdb_time_t

A cross-platform type that represents a time value.

See Also
  qdb_expires_at

Remarks
  qdb_time_t MUST be 64-bit large. The API will probably not link otherwise.

## Enumeration Type Documentation

enum qdb_compact_options_t

An enumeration of compact options.

See Also
  qdb_cluster_compact

Enumerator
qdb_compact_full | Compact the entire database in a single operation.
qdb_compact_piecewise | Compact the database one slice at a time (reduces peak disk usage during compaction)

enum qdb_entry_type_t

A enumeration representing possible entries type.

Enumerator
qdb_entry_uninitialized | Uninitialized value.
qdb_entry_blob | Binary large object (blob).
qdb_entry_integer | Signed 64-bit integer.
qdb_entry_hset | Distributed hash set.
qdb_entry_tag | Tag.
qdb_entry_deque | Distributed double-entry queue (deque).
qdb_entry_stream | Distributed binary stream.
qdb_entry_ts | Distributed time series.

enum qdb_limits_t

An enumeration of API limits.

Enumerator
qdb_l_max_alias_length | The maximum allowed length for aliases.
qdb_l_alias_max_length | Deprecated: Please use qdb_l_max_alias_length.
qdb_l_max_user_name_length | The maximum allowed length of a user name.
qdb_max_user_name_length | Deprecated: Please use qdb_l_max_user_name_length.

enum qdb_protocol_t

An enumeration of allowed network protocols.

See Also
  qdb_open

Enumerator
qdb_p_tcp | Uses TCP/IP to communicate with the cluster. This is currently the only supported network protocol.

## Function Documentation

QDB_API_LINKAGE const char* qdb_build | ( | void |  | ) |

Returns a null-terminated string describing the exact API build.

Returns
  A static, null-terminated string describing the exact API build. The buffer is API managed and should not be freed or written to by the caller.

QDB_API_LINKAGE qdb_error_t qdb_close | ( | qdb_handle_t | handle | ) |

Closes the handle previously opened with qdb_open or qdb_open_tcp.

This results in terminating all connections and releasing all internal buffers, including buffers which may have been allocated as or a result of batch operations or get operations.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.

Returns
  A qdb_error_t code indicating success or failure.

Attention
  API-allocated buffers may be released by this call. For example, the buffer allocated by qdb_blob_get may be released by this call.

QDB_API_LINKAGE qdb_error_t qdb_cluster_compact | ( | qdb_handle_t | handle,
|  | qdb_compact_options_t | options,
|  | int | timeout_ms
| ) |  |

Compacts all data in the persistence layer on all the nodes of the cluster.

This function will request each nodes to compact files on disk. Because this operation is I/O and CPU intensive, it is not recommended to run it when the cluster is heavily used.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  options | Options for the compaction operation.
  timeout_ms | A timeout value, in milliseconds.

Returns
  A qdb_error_t code indicating success or failure.

Attention
  This function impacts the performance of the cluster.

See Also
  qdb_trim_all

QDB_API_LINKAGE qdb_error_t qdb_cluster_endpoints | ( | qdb_handle_t | handle,
|  | qdb_remote_node_t ** | endpoints,
|  | qdb_size_t * | endpoints_count
| ) |  |

Retrieve a sorted array of endpoints.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  [out] | endpoints | A pointer to a qdb_remote_node_t array that will receive the addresses of the nodes of the cluster
  [out] | endpoints_count | A pointer that will be filled with number of nodes in the array

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_cluster_reload_user_config | ( | qdb_handle_t | handle | ) |

Reload user configuration from file.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_connect | ( | qdb_handle_t | handle,
|  | const char * | uri
| ) |  |

Binds the client instance to a quasardb cluster and connect to at least one node within.

Quasardb URI are in the form `qdb://<address>:<port>` where `<address>` is either an IPv4 or IPv6 (surrounded with square brackets), or a domain name. It is recommended to specify multiple addresses should the designated node be unavailable.

URI examples:

- `qdb://myserver.org:2836` - Connects to myserver.org on the port 2836
- `qdb://127.0.0.1:2836` - Connects to the local IPv4 loopback on the port 2836
- `qdb://myserver1.org:2836,myserver2.org:2836` - Connects to myserver1.org or myserver2.org on the port 2836
- `qdb://[::1]:2836` - Connects to the local IPv6 loopback on the port 2836

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  uri | A pointer to a null-terminated UTF-8 string representing the URI of the quasardb cluster to connect to.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_open, qdb_open_tcp

Attention
  Make sure all the addresses in the URI belong to the same cluster

QDB_API_LINKAGE qdb_error_t qdb_copy_alloc_buffer | ( | qdb_handle_t | handle,
|  | const void * | source_buffer,
|  | qdb_size_t | source_buffer_size,
|  | const void ** | dest_buffer
| ) |  |

Creates a clone of a buffer using API's high-performance memory allocator.

The allocated buffer has to be released later with qdb_release.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | source_buffer | A pointer to a buffer to clone
  | source_buffer_size | The size of the buffer to clone
  [out] | dest_buffer | A pointer to a a pointer of an API-allocated buffer whose content will be a copy of the source buffer

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE const char* qdb_error | ( | qdb_error_t | error | ) |

Translates an error code into an English error message.

Parameters

  error | The qdb_error_t code outputted by another function

Returns
  A static, null-terminated string describing the error. The buffer is API managed and should not be freed or written to by the caller.

QDB_API_LINKAGE qdb_error_t qdb_expires_at | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_time_t | expiry_time
| ) |  |

Sets the absolute expiration time of an entry, if the type supports expiration.

Blobs and integers can have an expiration time and will be automatically removed by the cluster when they expire.

The absolute expiration time is the Unix epoch, that is, the number of milliseconds since 1 January 1970, 00:00:00 UTC. To use a relative expiration time (that is expiration relative to the time of the call), use qdb_expires_from_now.

To remove the expiration time of an entry, specify the value qdb_never_expires as `expiry_time` parameter.

Values in the past are refused, but the cluster will have a certain tolerance to account for clock skews.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  expiry_time | The new, absolute UTC expiration time.

Returns
  A qdb_error_t code indicating success or failure.

Attention
  It is an error to specify an expiration in the past, although the cluster has a certain tolerance to account for clock synchronization

See Also
  qdb_expires_from_now

QDB_API_LINKAGE qdb_error_t qdb_expires_from_now | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_time_t | expiry_delta
| ) |  |

Sets the expiration time of an entry, relative to the current time of the client, if the type supports expiration.

Blobs and integers can have an expiration time and will automatically be removed by the cluster when they expire.

The expiration is relative to the current time of the machine.

To remove the expiration time of an entry or to use an absolute expiration time use qdb_expires_at.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  expiry_delta | The number of milliseconds, relative to the current time, after which the entry should expire.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_expires_at

QDB_API_LINKAGE qdb_error_t qdb_get_expiry_time | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_time_t * | expiry_time
| ) |  |

Retrieves the absolute expiration time of the given entry.

The returned expiration time is the Unix epoch, UTC.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | expiry_time | A pointer to an expiry time which will be set to the expiration of the entry if the call is successful.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_expires_from_now
  qdb_expires_at
  qdb_get_metadata

QDB_API_LINKAGE qdb_error_t qdb_get_last_error | ( | qdb_handle_t | handle,
|  | qdb_error_t * | error,
|  | qdb_string_t * | message
| ) |  |

Describes the last error code returned from the given handle.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  [out] | error | An optional pointer to a qdb_error_t that will be set to the error code of the last API call with the given handle.
  [out] | message | An optional pointer to a qdb_string_t that will store a message describing the last API call with the given handle. The buffer is API managed and should not be freed or written to by the caller. It's invalidated by subsequent API calls.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_get_location | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_remote_node_t * | location
| ) |  |

Returns the primary node of an entry.

The exact location of an entry should be assumed random and users should not bother about its location as the API will transparently locate the best node for the requested operation.

This function is intended for higher level APIs that need to optimize transfers and potentially push computation close to the data.

This function allocates memory for the null terminated address string call qdb_release on the location structure to release memory.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | location | A pointer to a qdb_remote_node_t structure that will receive the address of the primary node of the entry if successful.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE qdb_error_t qdb_get_metadata | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_entry_metadata_t * | entry_metadata
| ) |  |

Gets the meta-information about an entry, if it exists.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | entry_metadata | A pointer to a qdb_entry_metadata_t that will receive the metadata of the entry if successful.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_get_metadata_by_id | ( | qdb_handle_t | handle,
|  | const qdb_id_t * | reference,
|  | qdb_entry_metadata_t * | entry_metadata
| ) |  |

Gets the meta-information about an entry, if it exists.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | reference | A pointer to a structure representing the internal reference of the entry.
  [out] | entry_metadata | A pointer to a qdb_entry_metadata_t that will receive the metadata of the entry if successful.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_get_type | ( | qdb_handle_t | handle,
|  | const char * | alias,
|  | qdb_entry_type_t * | entry_type
| ) |  |

Gets the type of an entry, if it exists.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.
  [out] | entry_type | A pointer to a qdb_entry_type_t that will receive the type of the entry if successful.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_get_metadata

QDB_API_LINKAGE qdb_error_t qdb_open | ( | qdb_handle_t * | handle,
|  | qdb_protocol_t | proto
| ) |  |

Creates a qdb_handle_t. No connection will be established.

Parameters

  [out] | handle | A pointer to a qdb_handle_t that will be ready to connect to a cluster.
  | proto | The protocol to use.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_connect, qdb_open_tcp, qdb_protocol_t

QDB_API_LINKAGE qdb_handle_t qdb_open_tcp | ( | void |  | ) |

Creates a TCP/IP qdb_handle_t. No connection will be established.

Returns
  An initialized qdb_handle_t, ready to connect, in case of success, NULL in case of failure.

See Also
  qdb_connect, qdb_open

QDB_API_LINKAGE qdb_error_t qdb_purge_all | ( | qdb_handle_t | handle,
|  | int | timeout_ms
| ) |  |

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

This function is useful when quasardb is used as a cache and is not the golden source.

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.

By default cluster does not allow this operation and the function returns a qdb_e_operation_disabled error.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  timeout_ms | A timeout value, in milliseconds.

Returns
  A qdb_error_t code indicating success or failure.

Attention
  Use this function at your own risk. This function causes irremediable data loss.

QDB_API_LINKAGE qdb_error_t qdb_purge_cache | ( | qdb_handle_t | handle,
|  | 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.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  timeout_ms | A timeout value, in milliseconds.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_query_copy_results | ( | qdb_handle_t | handle,
|  | const qdb_query_result_t * | result,
|  | qdb_query_result_t ** | result_copy
| ) |  |

Creates a clone of a query result.

The allocated results have to be released later with qdb_release.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | result | A pointer to a buffer to clone
  [out] | result_copy | A pointer to a a pointer that will receive API-allocated results whose content will be a copy of the source results

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE void qdb_release | ( | qdb_handle_t | handle,
|  | const void * | buffer
| ) |  |

Releases an API-allocated buffer.

Failure to properly call this function may result in excessive memory usage. Most operations that return a content (e.g. batch operations, qdb_blob_get, qdb_blob_get_and_update, qdb_blob_compare_and_swap...) will allocate a buffer for the content and will not release the allocated buffer until you either call this function or close the handle.

The function will be able to release any kind of buffer allocated by a quasardb API call, whether it's a single buffer, an array or an array of buffers.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  buffer | A pointer to an API-allocated buffer to release. The behavior for non API buffers is undefined.

QDB_API_LINKAGE qdb_error_t qdb_remove | ( | qdb_handle_t | handle,
|  | const char * | alias
| ) |  |

Removes an entry from the cluster, regardless of its type.

This call will remove the entry, whether it is a blob, integer, deque, or hset. It will properly untag the entry. If the entry spawns on multiple entries or nodes (deques and hsets), all blocks will be properly removed.

The call is ACID, regardless of the type of the entry and a transaction will be created if need be.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  alias | A pointer to a null-terminated UTF-8 string representing the alias of the entry.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_tag_iterator_copy | ( | const qdb_const_tag_iterator_t * | original,
|  | qdb_const_tag_iterator_t * | copy
| ) |  |

Clones a previously initialized tag iterator.

Copies the state of the original iterator to a new iterator. Both iterators can be independently operated afterwards. The cloned iterator will have to be closed with qdb_tag_iterator_close.

Parameters

  | original | The original iterator to copy, source.
  [out] | copy | An uninitialized iterator to be set, destination.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_tag_iterator_begin, qdb_tag_iterator_close

QDB_API_LINKAGE qdb_error_t qdb_trim_all | ( | qdb_handle_t | handle,
|  | int | timeout_ms
| ) |  |

Trims all data on all the nodes of the cluster.

quasardb uses Multi-Version Concurrency Control (MVCC) as a foundation of its transaction engine. It will automatically clean up old versions as entries are accessed.

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.

Entries that are not accessed may not be cleaned up, resulting in increasing disk usage.

This function will request each node to trim all entries and release unused memory. Because this operation is I/O and CPU intensive, it is not recommended to run it when the cluster is heavily used.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  timeout_ms | A timeout value, in milliseconds.

Returns
  A qdb_error_t code indicating success or failure.

Attention
  This function impacts the performance of the cluster.

See Also
  qdb_cluster_compact

QDB_API_LINKAGE const char* qdb_version | ( | void |  | ) |

Returns a null-terminated string describing the API version.

Returns
  A static, null-terminated string describing the API version. The buffer is API managed and should not be freed or written to by the caller.

QDB_API_LINKAGE qdb_error_t qdb_wait_for_stabilization | ( | qdb_handle_t | handle,
|  | int | timeout_ms
| ) |  |

Wait for all nodes of the cluster to be stabilized.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  timeout_ms | A timeout value, in milliseconds.

Returns
  A qdb_error_t code indicating success or failure.