DDL execution

Functions
kv_error_t	kv_table_execute_sync (kv_store_t *store, const char *statement, kv_statement_result_t **resultp)
	Synchronously executes a table statement. More...
kv_error_t	kv_table_execute (kv_store_t *store, const char *statement, kv_future_t **futurep)
	Asynchronously executes a table statement. More...
kv_error_t	kv_get_future (kv_store_t *store, const kv_execution_id_t *id, kv_future_t **futurep)
	Constructs a future handle using the execution id. More...
kv_error_t	kv_refresh_tables (kv_store_t *store)
	Refreshes cached information about the tables. This method is required before using any tables that had been modified. More...

Detailed Description

This chapter describes the functions used to perform DDL statement execution in synchronous or asynchronous modes.

Function Documentation

kv_error_t kv_get_future	(	kv_store_t *	store,
		const kv_execution_id_t *	id,
		kv_future_t **	futurep
	)

Constructs a future handle using the execution id.

Parameters

[in]	store	The store handle.
[in]	id	The execution id, it is initialized using kv_future_get_execution_id().
[out]	futurep	The output kv_future_t structure, it should be freed using kv_release_future().

Returns

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

kv_error_t kv_refresh_tables

(

kv_store_t *

store

)

Refreshes cached information about the tables. This method is required before using any tables that had been modified.

Parameters

[in]

store

The store handle.

Returns

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

kv_error_t kv_table_execute	(	kv_store_t *	store,
		const char *	statement,
		kv_future_t **	futurep
	)

Asynchronously executes a table statement.

Currently, table statementscan be used to create or modify tables and indices. The operation is asynchronous and may not be finished when the method returns.

An Execution future structure is returned and can be used to get information about the status of the operation, or to await completion of the operation.

For example:

  const char *statement = "CREATE TABLE users (id INTEGER, name STRING, \
age INTEGER, PRIMARY KEY(id)";
  kv_future_t *future = NULL;
  const kv_statement_result_t *result = NULL;
  kv_error_t ret;

  // Create a table
  ret = kv_table_execute(store, statement, &future);
  if (ret != KV_SUCCESS) {
     fprintf(stderr, "Error: %s", kv_get_last_error(store));
     return -1;
  }

  // Wait for the operation to finish
  ret = kv_future_get(future, &result);
  if (ret != KV_SUCCESS) {
     fprintf(stderr, "Error: %s", kv_get_last_error(store));
  }
  kv_release_future(&future);

If the statement is a data definition or administrative operation, and the store is currently executing an operation that is the logical equivalent of the action specified by the statement, the method will return an kv_future_t structure that serves as a handle to that operation, rather than starting a new invocation of the command. The caller can use the kv_future_t structure to await the completion of the operation.

  // process A starts an index creation
  kv_future_t *futureA = NULL;
  kv_table_execute(store, "CREATE INDEX age ON users(age)", &futureA);

  // process B starts the same index creation. If the index creation is
  // still running, futureA and futureB will refer to the same operation
  kv_future_t *futureB = NULL;
  kv_table_execute(store, "CREATE INDEX age ON users(age)", &futureB);

Parameters

[in]	store	The store handle.
[in]	statement	The statement text to execute.
[out]	futurep	The output kv_future_t structure, it should be freed using kv_release_future().

Returns

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

See also

kv_future_get(), kv_future_get_with_timeout(), kv_future_cancel()

kv_error_t kv_table_execute_sync	(	kv_store_t *	store,
		const char *	statement,
		kv_statement_result_t **	resultp
	)

Synchronously executes a table statement.

The method will only return when the statement has finished. Has the same semantics as kv_table_execute(), but offers synchronous behavior as a convenience kv_table_execute_sync() is the equivalent of:

  kv_future_t *future = NULL;
  kv_statement_result_t *result = NULL;
  kv_table_execute(store, statement, &future);
  kv_future_get(future, &result);

When kv_table_execute_sync() returns, statement execution will have terminated, and the resulting Statement result will provide information about the outcome.

Parameters

[in]	store	The store handle.
[in]	statement	The table statement text to execute.
[out]	resultp	The output statement execution result, it should be freed using kv_release_statement_result().

Returns

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

See also

kv_table_execute()