Tagging operations

Data Structures
struct	qdb_const_tag_iterator_t
	An iterator to iterate on the entries matching a certain tag. More...

Functions
QDB_API_LINKAGE qdb_error_t	qdb_attach_tag (qdb_handle_t handle, const char *alias, const char *tag)
	Adds a tag to an entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_attach_tags (qdb_handle_t handle, const char *alias, const char *const *tags, size_t tag_count)
	Adds a collection of tags to a single entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_has_tag (qdb_handle_t handle, const char *alias, const char *tag)
	Tests if an entry has the request tag. More...
QDB_API_LINKAGE qdb_error_t	qdb_detach_tag (qdb_handle_t handle, const char *alias, const char *tag)
	Removes a tag from an entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_detach_tags (qdb_handle_t handle, const char *alias, const char *const *tags, size_t tag_count)
	Removes a collection of tags from a single entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_get_tagged (qdb_handle_t handle, const char *tag, const char ***aliases, size_t *alias_count)
	Retrieves all entries that have the specified tag. More...
QDB_API_LINKAGE qdb_error_t	qdb_get_tagged_count (qdb_handle_t handle, const char *tag, qdb_uint_t *count)
	Computes the count of all entries matching the specified tag, up to the configured max cardinality. More...
QDB_API_LINKAGE qdb_error_t	qdb_get_tagged_approximate_count (qdb_handle_t handle, const char *tag, qdb_uint_t *count)
	Computes the approximate count of all entries matching the specified tag, up to the configured max cardinality. More...
QDB_API_LINKAGE qdb_error_t	qdb_get_tags (qdb_handle_t handle, const char *alias, const char ***tags, size_t *tag_count)
	Retrieves all the tags of an entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_tag_iterator_begin (qdb_handle_t handle, const char *tag, qdb_const_tag_iterator_t *iterator)
	Creates an iterator that will point to the first entry having the the specified tag. More...
QDB_API_LINKAGE qdb_error_t	qdb_tag_iterator_next (qdb_const_tag_iterator_t *iterator)
	Advance a previously initialized iterator to the next entry. More...
QDB_API_LINKAGE qdb_error_t	qdb_tag_iterator_close (qdb_const_tag_iterator_t *iterator)
	Releases all API-allocated resources during a previous iteration. More...

Detailed Description

Function Documentation

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

Consider using qdb_attach_tags if you are adding several tags to the same entry.

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

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_attach_tags, qdb_has_tag, qdb_detach_tag, qdb_get_tagged, qdb_get_tags

QDB_API_LINKAGE qdb_error_t qdb_attach_tags	(	qdb_handle_t	handle,
		const char *	alias,
		const char *const *	tags,
		size_t	tag_count
	)

Adds a collection of tags to a single entry.

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

The function will ignore existing tags.

The entry must exist.

The tag may or may not exist.

Consider using qdb_attach_tag if you are adding a single tag.

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 to which the tags must be added.
tags	A pointer to an array of null-terminated UTF-8 strings representing the tags to add to the entry
tag_count	The count of tags to add to the entry.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_attach_tag, qdb_has_tag, qdb_detach_tags, qdb_get_tagged, qdb_get_tags

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

Consider using qdb_detach_tags if you are removing several tags at once.

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 to which the tag must be remove.
tag	A pointer to a null-terminated UTF-8 string representing the tag to remove.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_detach_tags, qdb_get_tagged, qdb_get_tags

QDB_API_LINKAGE qdb_error_t qdb_detach_tags	(	qdb_handle_t	handle,
		const char *	alias,
		const char *const *	tags,
		size_t	tag_count
	)

Removes a collection of tags from a single entry.

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

The entry must exist.

The tags must exist.

Consider using qdb_detach_tag if you are removing a single tag.

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 to which the tags must be removed.
tags	A pointer to an array of null-terminated UTF-8 strings representing the tags to remove.
tag_count	The count of tags to remove to the entry.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_detach_tag, qdb_get_tagged, qdb_get_tags

QDB_API_LINKAGE qdb_error_t qdb_get_tagged	(	qdb_handle_t	handle,
		const char *	tag,
		const char ***	aliases,
		size_t *	alias_count
	)

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.

Parameters

	handle	A valid handle previously initialized by qdb_open or qdb_open_tcp.
	tag	A pointer to a null-terminated UTF-8 string representing the tag for which to search entries.
[out]	aliases	A pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries having the requested tag.
[out]	alias_count	A pointer to an integer that will receive the number of returned aliases.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tags, qdb_tag_iterator_begin, qdb_release

QDB_API_LINKAGE qdb_error_t qdb_get_tagged_approximate_count	(	qdb_handle_t	handle,
		const char *	tag,
		qdb_uint_t *	count
	)

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

Parameters

	handle	A valid handle previously initialized by qdb_open or qdb_open_tcp.
	tag	A pointer to a null-terminated UTF-8 string representing the tag for which to search entries.
[out]	count	A pointer to an integer that will receive the count of tags

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tags, qdb_get_tagged, qdb_option_set_max_cardinality

QDB_API_LINKAGE qdb_error_t qdb_get_tagged_count	(	qdb_handle_t	handle,
		const char *	tag,
		qdb_uint_t *	count
	)

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

Parameters

	handle	A valid handle previously initialized by qdb_open or qdb_open_tcp.
	tag	A pointer to a null-terminated UTF-8 string representing the tag for which to search entries.
[out]	count	A pointer to an integer that will receive the count of tags

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tags, qdb_get_tagged, qdb_option_set_max_cardinality

QDB_API_LINKAGE qdb_error_t qdb_get_tags	(	qdb_handle_t	handle,
		const char *	alias,
		const char ***	tags,
		size_t *	tag_count
	)

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.

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 to which the tag must be added.
[out]	tags	A pointer to an array of null-terminated UTF-8 string that will list the tags of the entry
[out]	tag_count	A pointer to an integer that will receive the number of returned tags.

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tagged, qdb_release

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

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

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tagged, qdb_get_tags, qdb_run_batch

QDB_API_LINKAGE qdb_error_t qdb_tag_iterator_begin	(	qdb_handle_t	handle,
		const char *	tag,
		qdb_const_tag_iterator_t *	iterator
	)

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.

Parameters

	handle	A valid handle previously initialized by qdb_open or qdb_open_tcp.
	tag	A pointer to a null-terminated UTF-8 string representing the tag on which iteration is requested
[out]	iterator	A pointer to an uninitialized qdb_const_tag_iterator_t

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tagged, qdb_tag_iterator_next, qdb_tag_iterator_close

QDB_API_LINKAGE qdb_error_t qdb_tag_iterator_close

(

qdb_const_tag_iterator_t *

iterator

)

Releases all API-allocated resources during a previous iteration.

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

Parameters

[in,out]

iterator

A pointer to an initialized qdb_const_tag_iterator_t

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_tag_iterator_begin

QDB_API_LINKAGE qdb_error_t qdb_tag_iterator_next

(

qdb_const_tag_iterator_t *

iterator

)

Advance a previously initialized iterator to the next entry.

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.

Parameters

[in,out]

iterator

A pointer to an initialized qdb_const_tag_iterator_t

Returns

A qdb_error_t code indicating success or failure.

See Also

qdb_get_tagged, qdb_tag_iterator_begin, qdb_tag_iterator_close