Data interfaces

Functions
kv_error_t	kv_table_put (kv_store_t *store, const char *table_name, const kv_row_t *row, kv_version_t **new_version)
	Puts a row into a table, overwriting any existing row. More...
kv_error_t	kv_table_put_with_options (kv_store_t *store, const char *table_name, const kv_row_t *row, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Puts a row to a table using options, overwriting any existing row. More...
kv_error_t	kv_table_put_if_absent (kv_store_t *store, const char *table_name, const kv_row_t *row, kv_version_t **new_version)
	Puts a row to a table but only if the row does not exist. More...
kv_error_t	kv_table_put_if_absent_with_options (kv_store_t *store, const char *table_name, const kv_row_t *row, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Puts a row to a table but only if the row does not exist using options. More...
kv_error_t	kv_table_put_if_present (kv_store_t *store, const char *table_name, const kv_row_t *row, kv_version_t **new_version)
	Puts a row to a table but only if the row already exists. More...
kv_error_t	kv_table_put_if_present_with_options (kv_store_t *store, const char *table_name, const kv_row_t *row, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Puts a row to a table but only if the row already exists. More...
kv_error_t	kv_table_put_if_version (kv_store_t *store, const char *table_name, const kv_row_t *row, const kv_version_t *if_version, kv_version_t **new_version)
	Puts a row to a table but only if the version of the existing row matches the if_version argument. More...
kv_error_t	kv_table_put_if_version_with_options (kv_store_t *store, const char *table_name, const kv_row_t *row, const kv_version_t *if_version, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Puts a row to a table but only if the version of the existing row matches the if_version argument using options. More...
kv_error_t	kv_table_get (kv_store_t *store, const char *table_name, const kv_row_t *key, kv_row_t **rowp)
	Returns a row associated with the primary key from a table, it uses the store's default consistency policy and timeout value. More...
kv_error_t	kv_table_get_with_options (kv_store_t *store, const char *table_name, const kv_row_t *key, const kv_read_options_t *options, kv_result_t **resultp)
	Returns a row associated with the primary key from a table using options. More...
kv_int_t	kv_table_delete (kv_store_t *store, const char *table_name, const kv_row_t *key)
	Deletes a row associated with the primary key from a table. More...
kv_int_t	kv_table_delete_with_options (kv_store_t *store, const char *table_name, const kv_row_t *key, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Deletes a row associated with the primary key from a table using options. More...
kv_int_t	kv_table_delete_if_version (kv_store_t *store, const char *table_name, const kv_row_t *key, const kv_version_t *if_version)
	Deletes a row from a table but only if its version matches the one specified in if_version. More...
kv_int_t	kv_table_delete_if_version_with_options (kv_store_t *store, const char *table_name, const kv_row_t *key, const kv_version_t *if_version, const kv_write_options_t *options, kv_return_row_version_enum choice, kv_result_t **resultp)
	Deletes a row from a table but only if its version matches the one specified in if_version using options. More...
kv_error_t	kv_table_multi_get (kv_store_t *store, const char *table_name, const kv_row_t *key, kv_boolean_t keyonly, const kv_field_range_t *range, const char **included_tables, const kv_read_options_t *options, kv_iterator_t **iteratorp)
	Returns the rows associated with a partial primary key. The range argument can be used to further limit the rows that are retrieved, the included_tables argument can be used to retrieve the rows from its child and ancestor tables. More...
kv_int_t	kv_table_multi_delete (kv_store_t *store, const char *table_name, const kv_row_t *key, const kv_field_range_t *range, const char **included_tables, const kv_write_options_t *options)
	Deletes multiple rows from a table in an atomic operation. More...
kv_error_t	kv_table_iterator (kv_store_t *store, const char *table_name, const kv_row_t *key, kv_boolean_t keyonly, const kv_field_range_t *range, const char **included_tables, kv_direction_enum direction, const kv_read_options_t *options, kv_long_t max_results, kv_iterator_t **iteratorp)
	Returns an iterator over the rows associated with a primary key. More...
kv_error_t	kv_table_iterator_multi (kv_store_t *store, const char *table_name, kv_row_t **keys, kv_boolean_t keyonly, const kv_field_range_t *range, const char **included_tables, kv_direction_enum direction, const kv_read_options_t *options, kv_long_t max_results, kv_iterator_t **iteratorp)
	Returns an iterator over the rows represented by primary keys. More...
kv_error_t	kv_index_iterator (kv_store_t *store, const char *table_name, const char *index_name, const kv_row_t *key, kv_boolean_t keyonly, const kv_field_range_t *range, const char **included_tables, kv_direction_enum direction, const kv_read_options_t *options, kv_long_t batch_size, kv_iterator_t **iteratorp)
	Returns an iterator over the rows associated with an index key. More...
kv_error_t	kv_iterator_next (kv_iterator_t *iterator)
	Advances the iterator to the next result. More...
const kv_result_t *	kv_iterator_get_result (kv_iterator_t *iterator)
	Returns the result at the iterator's current position. More...
kv_int_t	kv_iterator_size (const kv_iterator_t *iterator)
void	kv_release_iterator (kv_iterator_t **iteratorp)
	Releases the resources used by the iterator handle. More...
kv_error_t	kv_table_execute_operations (kv_store_t *store, const kv_operations_t *list, const kv_write_options_t *options, kv_operation_results_t **resultsp)
	Executes a sequence of operations in a single transaction. More...

Detailed Description

This chapter describes the functions used to perform data read and writes on table in the store. Mainly it contains functions:

• Perform read or write a single row at a time on a table.
• Perform read or write many rows on a table in a single operation.
• Create iterators to walk over some or all of the rows of table(s).
• Perform multiple write operations that are organized in a single sequence of operations. These sequences are performed under a single transaction that effectively offers serializable isolation.

Function Documentation

kv_error_t kv_index_iterator	(	kv_store_t *	store,
		const char *	table_name,
		const char *	index_name,
		const kv_row_t *	key,
		kv_boolean_t	keyonly,
		const kv_field_range_t *	range,
		const char **	included_tables,
		kv_direction_enum	direction,
		const kv_read_options_t *	options,
		kv_long_t	batch_size,
		kv_iterator_t **	iteratorp
	)

Returns an iterator over the rows associated with an index key.

Returning only key fields vs full rows can be significantly faster as it only reads the index itself and does not need to fetch the row from the primary database. In this case specifying keyonly means that the fields returned are both those from the index key itself plus the primary key fields.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	index_name	The index name.
[in]	key	The index key for the operation. It may be partial or complete. If the key has no fields set the entire index is matched.
[in]	keyonly	Set to KV_TRUE if the method should return only primary key and index key data, KV_FALSE to return entire rows.
[in]	range	The range is used to restrict the selected rows to those matching a range of field values for the first unspecified field in the target key. It is created using kv_create_field_range() function. If a complete primary key is given, this argument must be NULL.
[in]	included_tables	An null-terminated array of strings which specifies the full names of child and ancestor tables for which rows are selected by the operation, use NULL if only rows from the target table are of interest. The target table must not appear in this list.
[in]	direction	The direction parameter specifies the order in which rows are returned by the iterator.
[in]	options	The read options used for the operation, it is created using kv_create_read_options(). If it is NULL, then default configuration is used.
[in]	batch_size	The batch_size parameter provides the suggested number of rows to fetch during each network round trip. If only the first or last row is desired, passing a value of one (1) is recommended. If zero, an internally determined default is used.
[out]	iteratorp	The output iterator handle, it must be freed using kv_release_iterator().

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

const kv_result_t* kv_iterator_get_result

(

kv_iterator_t *

iterator

)

Returns the result at the iterator's current position.

Note

The returned result is owned by the iterator and released implicitly when it is released.

Parameters

[in]

iterator

The iterator handle.

Returns

A result

kv_error_t kv_iterator_next

(

kv_iterator_t *

iterator

)

Advances the iterator to the next result.

Parameters

[in]

iterator

The iterator handle.

Returns

KV_SUCCESS if there is an element, KV_NO_SUCH_OBJECT if there are no more elements. If the return value is neither of these it indicates the error that has occurred.

kv_int_t kv_iterator_size

(

const kv_iterator_t *

iterator

)

Returns the number of items contained in the iterator. This function can only be used with iterators returned by the kv_table_multi_get(). The iterators returned by other functions, such as kv_table_iterator() or kv_index_iterator(), are not usable by this function and if used, will return an error.

Parameters

[in]

iterator

The iterator handle.

Returns

the number of items in result set.

void kv_release_iterator

(

kv_iterator_t **

iteratorp

)

Releases the resources used by the iterator handle.

Parameters

[in]

iteratorp

The pointer to the iterator handle to release.

kv_int_t kv_table_delete	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key
	)

Deletes a row associated with the primary key from a table.

Note

This is the simplified version of the function that uses default values for most of delete options. For a more complete version that lets you use non-default values, use kv_table_delete_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.

Returns

1 if the row exists and delete successfully, 0 if no row deleted, or an error code (a negative number) on failure.

kv_int_t kv_table_delete_if_version	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_version_t *	if_version
	)

Deletes a row from a table but only if its version matches the one specified in if_version.

Note

This is the simplified version of the function that uses default values for most of delete options. For a more complete version that lets you use non-default values, use kv_table_delete_if_version_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.
[in]	if_version	The version to match.

Returns

1 if the row existed and its version matched and delete successfully, 0 if no row deleted, or an error code (a negative number) on failure.

kv_int_t kv_table_delete_if_version_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_version_t *	if_version,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Deletes a row from a table but only if its version matches the one specified in if_version using options.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.
[in]	if_version	The version to match.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	The output result structure that must be freed using kv_release_result(). If the parameter is NULL, then return row choice KV_RETURN_ROW_NONE is used.

Returns

1 if the row existed and its version matched and delete successfully, 0 if no row deleted, or an error code (a negative number) on failure.

kv_int_t kv_table_delete_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Deletes a row associated with the primary key from a table using options.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key used to look up the row to be deleted.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	The output result structure that must be freed using kv_release_result(). If the parameter is NULL, then return row choice KV_RETURN_ROW_NONE is used.

Returns

1 if the row exists and delete successfully, 0 if no row deleted, or an error code (a negative number) on failure.

kv_error_t kv_table_execute_operations	(	kv_store_t *	store,
		const kv_operations_t *	list,
		const kv_write_options_t *	options,
		kv_operation_results_t **	resultsp
	)

Executes a sequence of operations in a single transaction.

Parameters

[in]	store	The store handle.
[in]	list	A list of table operations.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[out]	resultsp	The output list of operations result. Each element in the results list describes the results of executing one of the operations in the sequence of operations, it should be freed using kv_release_operation_results().

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_table_get	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		kv_row_t **	rowp
	)

Returns a row associated with the primary key from a table, it uses the store's default consistency policy and timeout value.

Note

For a more complete version that lets you use non-default read options, use kv_table_get_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key of the row.
[out]	rowp	The output row structure if found, it must be released using kv_release_row().

Returns

KV_SUCCESS on success, or KV_ROW_NOT_FOUND if the row doesn't exist, or an error code (a negative number) on failure.

kv_error_t kv_table_get_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_read_options_t *	options,
		kv_result_t **	resultp
	)

Returns a row associated with the primary key from a table using options.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key of the row.
[in]	options	The read options used for the operation, it is created using kv_create_read_options(). If it is NULL, then default configuration is used.
[out]	resultp	The output result structure, it must be released using kv_release_result().

Returns

KV_SUCCESS on success, or KV_ROW_NOT_FOUND if the row doesn't exist, or an error code (a negative number) on failure.

kv_error_t kv_table_iterator	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		kv_boolean_t	keyonly,
		const kv_field_range_t *	range,
		const char **	included_tables,
		kv_direction_enum	direction,
		const kv_read_options_t *	options,
		kv_long_t	max_results,
		kv_iterator_t **	iteratorp
	)

Returns an iterator over the rows associated with a primary key.

The primary key for the operation may be partial or complete shard key. Iterations using a complete shard key are much faster than full table iterations.

Returning only key fields vs full rows can be significantly faster as it avoids reading the records themselves. If only key information is required, specify a key-only get using the keyonly parameter.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key for the operation. It may be partial or complete. If the key contains a partial shard key the iteration goes to all partitions in the store. If the key contains a complete shard key the operation is restricted to the target partition. If the key has no fields set the entire table is matched.
[in]	keyonly	Set to KV_TRUE if the method should return only primary keys, KV_FALSE to return entire rows.
[in]	range	The range is used to restrict the selected rows to those matching a range of field values for the first unspecified field in the target key. It is created using kv_create_field_range() function. If a complete primary key is given, this argument must be NULL.
[in]	included_tables	An null-terminated array of strings which specifies the full names of child and ancestor tables for which rows are selected by the operation, use NULL if only rows from the target table are of interest. The target table must not appear in this list.
[in]	direction	The direction parameter specifies the order in which rows are returned by the iterator.
[in]	options	The read options used for the operation, it is created using kv_create_read_options(). If it is NULL, then default configuration is used.
[in]	max_results	The maximum number of results returned in the iterator call.
[out]	iteratorp	The output iterator handle, it must be freed using kv_release_iterator().

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_table_iterator_multi	(	kv_store_t *	store,
		const char *	table_name,
		kv_row_t **	keys,
		kv_boolean_t	keyonly,
		const kv_field_range_t *	range,
		const char **	included_tables,
		kv_direction_enum	direction,
		const kv_read_options_t *	options,
		kv_long_t	max_results,
		kv_iterator_t **	iteratorp
	)

Returns an iterator over the rows represented by primary keys.

The supplied primary keys may be partial or complete, they must contain all of the fields defined for the table's shard key. Iterations using a complete shard key are much faster than full table iterations.

Returning only key fields vs full rows can be significantly faster as it avoids reading the records themselves. If only key information is required, specify a key-only get using the keyonly parameter.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	keys	A NULL terminated array of primary keys for the operation. They may be partial or complete and must contain all of the fields defined for the table's shard key.
[in]	keyonly	Set to KV_TRUE if the method should return only primary keys, KV_FALSE to return entire rows.
[in]	range	The range is used to restrict the selected rows to those matching a range of field values for the first unspecified field in the target key. It is created using kv_create_field_range() function. If a complete primary key is given, this argument must be NULL.
[in]	included_tables	An null-terminated array of strings which specifies the full names of child and ancestor tables for which rows are selected by the operation, use NULL if only rows from the target table are of interest. The target table must not appear in this list.
[in]	direction	The direction parameter specifies the order in which rows are returned by the iterator.
[in]	options	The read options used for the operation, it is created using kv_create_read_options(). If it is NULL, then default configuration is used.
[in]	max_results	The maximum number of results returned in the iterator call.
[out]	iteratorp	The output iterator handle, it must be freed using kv_release_iterator().

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_int_t kv_table_multi_delete	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		const kv_field_range_t *	range,
		const char **	included_tables,
		const kv_write_options_t *	options
	)

Deletes multiple rows from a table in an atomic operation.

The key used may be partial but must contain all of the fields that are in the shard key.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key for the operation. It may be partial or complete but must contain at least the fields in the table's shard key.
[in]	range	The range is used to restrict the selected rows to those matching a range of field values for the first unspecified field in the target key. It is created using kv_create_field_range() function. If a complete primary key is given, this argument must be NULL.
[in]	included_tables	An null-terminated array of strings which specifies the full names of child and ancestor tables for which rows are selected by the operation, use NULL if only rows from the target table are of interest. The target table must not appear in this list.
[in]	options	The write options used for this operations, or NULL to use default configuration. It is created using kv_create_write_options().

Returns

the num of rows delete from the table, 0 if no row deleted, or an error code (a negative number) on failure.

kv_error_t kv_table_multi_get	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	key,
		kv_boolean_t	keyonly,
		const kv_field_range_t *	range,
		const char **	included_tables,
		const kv_read_options_t *	options,
		kv_iterator_t **	iteratorp
	)

Returns the rows associated with a partial primary key. The range argument can be used to further limit the rows that are retrieved, the included_tables argument can be used to retrieve the rows from its child and ancestor tables.

Rows are returned in primary key order. The key used must contain all of the fields defined for the table's shard key. This method will return all matching keys or rows, it should be used with caution because it could result in errors due to running out of memory if the results cannot all be held in memory at one time.

Returning only key fields vs full rows can be significantly faster as it avoids reading the records themselves. If only key information is required, specify a key-only get using the keyonly parameter.

You can use kv_iterator_size() on the returned kv_iterator_t to get the number of items contained in the iterator.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	key	The primary key for the operation. It may be partial or complete but must contain at least the fields in the table's shard key.
[in]	keyonly	Set to KV_TRUE if the method should return only primary keys, KV_FALSE to return entire rows.
[in]	range	The range is used to restrict the selected rows to those matching a range of field values for the first unspecified field in the target key. It is created using kv_create_field_range() function. If a complete primary key is given, this argument must be NULL.
[in]	included_tables	An null-terminated array of strings which specifies the full names of child and ancestor tables for which rows are selected by the operation, use NULL if only rows from the target table are of interest. The target table must not appear in this list.
[in]	options	The read options used for the operation, it is created using kv_create_read_options(). If it is NULL, then default configuration is used.
[out]	iteratorp	The output iterator handle, it must be freed using kv_release_iterator().

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_table_put	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		kv_version_t **	new_version
	)

Puts a row into a table, overwriting any existing row.

Note

This is the simplified version of the function that uses default values for most of put options. For a more complete version that lets you use non-default values, use kv_table_put_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written. All primary key fields must be present.
[out]	new_version	A pointer to an output parameter that holds the version of the new row. Set this to NULL if this information is not of interest. The returned value will be NULL if this function produces a non-zero return code. It must be freed using kv_release_version();

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.

kv_error_t kv_table_put_if_absent	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		kv_version_t **	new_version
	)

Puts a row to a table but only if the row does not exist.

Note

This is the simplified version of the function that uses default values for most of put options. For a more complete version that lets you use non-default values, use kv_table_put_if_absent_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[out]	new_version	A pointer to an output parameter that holds the version of the new row. Set this to NULL if this information is not of interest. The returned value will be NULL if this function produces a non-zero return code. It must be freed using kv_release_version();

Returns

KV_SUCCESS on success, or KV_ROW_ALREADY_EXISTS if an existing row is present, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_if_absent_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Puts a row to a table but only if the row does not exist using options.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	A pointer to an output result structure that must be freed using kv_release_result(). If no return information is desired, set this to NULL.

Returns

KV_SUCCESS on success, or KV_ROW_ALREADY_EXISTS if an existing row is present, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_if_present	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		kv_version_t **	new_version
	)

Puts a row to a table but only if the row already exists.

Note

This is the simplified version of the function that uses default values for most of put options. For a more complete version that lets you use non-default values, use kv_table_put_if_present_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[out]	new_version	A pointer to an output parameter that holds the version of the new row. Set this to NULL if this information is not of interest. The returned value will be NULL if this function produces a non-zero return code. It must be freed using kv_release_version();

Returns

KV_SUCCESS on success, or KV_ROW_NOT_FOUND if there is no existing row, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_if_present_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Puts a row to a table but only if the row already exists.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	A pointer to an output result structure that must be freed using kv_release_result(). If no return information is desired, set this to NULL.

Returns

KV_SUCCESS on success, or KV_ROW_NOT_FOUND if there is no existing row, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_if_version	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_version_t *	if_version,
		kv_version_t **	new_version
	)

Puts a row to a table but only if the version of the existing row matches the if_version argument.

Note

This is the simplified version of the function that uses default values for most of put options. For a more complete version that lets you use non-default values, use kv_table_put_if_version_with_options().

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	if_version	The version to match.
[out]	new_version	A pointer to an output parameter that holds the version of the new row. Set this to NULL if this information is not of interest. The returned value will be NULL if this function produces a non-zero return code. It must be freed using kv_release_version();

Returns

KV_SUCCESS on success, or KV_VERSION_NOT_MATCH or NULL if the versions do not match, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_if_version_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_version_t *	if_version,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Puts a row to a table but only if the version of the existing row matches the if_version argument using options.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	if_version	The version to match.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	A pointer to an output result structure that must be freed using kv_release_result(). If no return information is desired, set this to NULL.

Returns

KV_SUCCESS on success, or KV_VERSION_NOT_MATCH or NULL if the versions do not match, or an error code (a negative number) if put is unsuccessful.

kv_error_t kv_table_put_with_options	(	kv_store_t *	store,
		const char *	table_name,
		const kv_row_t *	row,
		const kv_write_options_t *	options,
		kv_return_row_version_enum	choice,
		kv_result_t **	resultp
	)

Puts a row to a table using options, overwriting any existing row.

Parameters

[in]	store	The store handle
[in]	table_name	The name of the target table.
[in]	row	The row to be written.
[in]	options	The write options used for this operation, it is created using kv_create_write_options(). If it is NULL, then default configuration is used.
[in]	choice	The return row choice, specifies whether to return the row value, version, both or neither.
[out]	resultp	A pointer to an output result structure that must be freed using kv_release_result(). If no return information is desired, set this to NULL.

Returns

KV_SUCCESS on success, and an error code (a negative number) on failure.