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 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_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_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 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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation