quasardb C API: Batch 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 | Enumerations | Functions
Batch functions

## Data Structures
struct | int_put_update_t
| The required parameters for an integer operation within a batch. More...
struct | blob_put_update_t
| The required parameters for a blob put or update operations within a batch. More...
struct | qdb_operation_t
| A single operation containing all parameters to execute the operation in a batch or in a transaction. More...

## Enumerations
enum | qdb_operation_type_t { qdb_op_uninitialized = -1, qdb_op_blob_get = 0, qdb_op_blob_put = 1, qdb_op_blob_update = 2, qdb_op_blob_cas = 4, qdb_op_blob_get_and_update = 5, qdb_op_has_tag = 8, qdb_op_int_put = 9, qdb_op_int_update = 10, qdb_op_int_get = 11, qdb_op_int_add = 12, qdb_op_get_entry_type = 13, qdb_op_value_get = 14 }
| An enumeration of possible operation type. More...

## Functions
QDB_API_LINKAGE qdb_error_t | qdb_init_operations (qdb_operation_t *operations, size_t operation_count)
| Initializes an array of qdb_operation_t. More...
QDB_API_LINKAGE size_t | qdb_run_batch (qdb_handle_t handle, qdb_operation_t *operations, size_t operation_count)
| Runs the operations in batch. More...
QDB_API_LINKAGE qdb_error_t | qdb_run_transaction (qdb_handle_t handle, qdb_operation_t *operations, size_t operation_count, size_t *failed_index)
| Runs the operations in a single transaction. More...

## Detailed Description

## Enumeration Type Documentation

enum qdb_operation_type_t

An enumeration of possible operation type.

Operations are used by batches and transactions.

Enumerator
qdb_op_uninitialized | Unitialized value.
qdb_op_blob_get | A blob get operation.
qdb_op_blob_put | A blob put operation.
qdb_op_blob_update | A blob update operation.
qdb_op_blob_cas | A blob compare and swap operation.
qdb_op_blob_get_and_update | A blob get and update.
qdb_op_has_tag | Tag existence test operation.
qdb_op_int_put | An integer put operation.
qdb_op_int_update | An integer update operation.
qdb_op_int_get | An integer get operation.
qdb_op_int_add | An integer increase/decrease operation.
qdb_op_get_entry_type | Entry type check.
qdb_op_value_get | A value get operation.

## Function Documentation

QDB_API_LINKAGE qdb_error_t qdb_init_operations | ( | qdb_operation_t * | operations,
|  | size_t | operation_count
| ) |  |

Initializes an array of qdb_operation_t.

Use this function to make sure all the fields of the operation structure are properly initialized to their default values.

After this function has been called, the user must then set the required parameter for each operation.

Parameters

  operations | A pointer to an array of operations
  operation_count | The number of elements in the array of operations

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_operation_t

QDB_API_LINKAGE size_t qdb_run_batch | ( | qdb_handle_t | handle,
|  | qdb_operation_t * | operations,
|  | size_t | operation_count
| ) |  |

Runs the operations in batch.

When operations are run in batch the order of execution is optimized for speed and each operation is run independently.

Running operations is batch is generally the best way to achieve a very high level of performance, especially for bulk loading of data. That's because batches minimize network communication and organize the order of execution for maximum throughput.

If one or several operations within the batch fail, the rest of the batch isn't affected.

If one or several operations within the batch is ill-formed, the whole batch will be aborted. An ill formed operation is for example an operation missing a parameter.

Each operation will result a result according to its type.

After a batch has been run (successful or not), the user must call qdb_release on the operations pointer to release all API-allocated buffers.

For an ordered, transactional "all or nothing" behavior use qdb_run_transaction.

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  operations | A pointer to a correctly constructed array of operations
  operation_count | The number of elements in the array of operations

Returns
  The number of successful operations in the batch.

See Also
  qdb_operation_t, qdb_run_transaction, qdb_release

QDB_API_LINKAGE qdb_error_t qdb_run_transaction | ( | qdb_handle_t | handle,
|  | qdb_operation_t * | operations,
|  | size_t | operation_count,
|  | size_t * | failed_index
| ) |  |

Runs the operations in a single transaction.

Operations that run in a transaction will be executed ordered to preserve the logic of the transaction and if an error occurred the previously executed operations will be rolled back.

The operation is committed if and only if all operations have been successful.

The result of the transaction is not visible by other clients until it has been committed.

After a transaction has been run (successful or not), the user must call qdb_release on operations to release all API-allocated buffers.

Use transactions when integrity and order is paramount. For maximum performances consider using batches (qdb_run_batch).

Parameters

  handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  operations | A pointer to a correctly constructed array of operations
  operation_count | The number of elements in the array of operations
  failed_index | A pointer to the index of the first failed operation

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_operation_t, qdb_run_batch, qdb_release