quasardb C API: Query related 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 | Typedefs | Enumerations | Functions
Query related functions

## Data Structures
struct | qdb_point_result_t
| A variadic structure holding the result type as well as the result value. More...
struct | qdb_query_result_t
| Holds the result of a query. More...
struct | qdb_query_experimental_column_t
| Holds a column of an experimental query. More...
struct | qdb_query_experimental_result_t
| Holds the result of an experimental query. More...
struct | qdb_query_arrow_result_t
| Holds the result of a query in Arrow format. More...

## Typedefs
typedef enum qdb_query_result_value_type_t | qdb_query_result_value_type_t
| The type of a result.
typedef enum qdb_query_continuous_mode_type_t | qdb_query_continuous_mode_type_t
| The continuous query mode.
typedef struct qdb_dedup_handle_internal * | qdb_dedup_handle_t
| An opaque handle to internal API-allocated structures needed for deduplicating query results.
typedef struct qdb_query_cont_internal * | qdb_query_cont_handle_t
| An opaque handle to internal API-allocated structures needed for managing a continuous query.
typedef int | qdb_query_cont_callback_t (void *, qdb_error_t, const qdb_query_result_t *)
| A callback used by qdb_query_continuous. The first parameter of the callback will receive the context given when calling qdb_query_continuous The second parameter is the error result of the operation The third parameter are the new results for the query since the callback has been last called. More...

## Enumerations
enum | qdb_query_result_value_type_t
| The type of a result.
enum | qdb_query_continuous_mode_type_t
| The continuous query mode.

## Functions
QDB_API_LINKAGE qdb_error_t | qdb_query_find (qdb_handle_t handle, const char *query, const char ***aliases, size_t *alias_count)
| Retrieves all entries' aliases that match the specified find query. More...
QDB_API_LINKAGE qdb_error_t | qdb_query (qdb_handle_t handle, const char *query, qdb_query_result_t **result)
| Run the provided query and creates a table directory with the results. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_experimental (qdb_handle_t handle, const char *query, qdb_query_experimental_result_t **result)
| Run the provided query to return a table. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_to_arrow (qdb_handle_t handle, const qdb_query_result_t *result, qdb_query_arrow_result_t **result_copy)
| Copies a query result to the Arrow format. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_experimental_to_arrow (qdb_handle_t handle, const qdb_query_experimental_result_t *result, qdb_query_arrow_result_t **result_copy)
| Copies a query result to the Arrow format. More...
QDB_API_LINKAGE qdb_error_t | qdb_init_query_dedup (qdb_handle_t handle, qdb_dedup_handle_t *dedup_handle)
| Creates a qdb_dedup_handle_t. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_dedup (qdb_dedup_handle_t dedup_handle, const qdb_query_result_t *result, qdb_query_result_t **dedup_result)
| Deduplicates query results. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_dedup_prune (qdb_dedup_handle_t dedup_handle, const qdb_ts_range_t *range)
| Removes previously seen rows from the given deduplication handler. More...
QDB_API_LINKAGE qdb_error_t | qdb_query_continuous (qdb_handle_t handle, const char *query, qdb_query_continuous_mode_type_t mode, qdb_query_cont_callback_t cb, void *cb_context, qdb_query_cont_handle_t *cont_handle)
| Continuously and efficiently query the server with the given query. More...

## Detailed Description

## Typedef Documentation

qdb_query_cont_callback_t

A callback used by qdb_query_continuous. The first parameter of the callback will receive the context given when calling qdb_query_continuous The second parameter is the error result of the operation The third parameter are the new results for the query since the callback has been last called.

See Also
  qdb_query_continuous

## Function Documentation

QDB_API_LINKAGE qdb_error_t qdb_init_query_dedup | ( | qdb_handle_t | handle,
|  | qdb_dedup_handle_t * | dedup_handle
| ) |  |

Creates a qdb_dedup_handle_t.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  [out] | dedup_handle | A pointer to a qdb_dedup_handle_t that will be ready for deduplicating query results. It must be released later with qdb_release.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE qdb_error_t qdb_query | ( | qdb_handle_t | handle,
|  | const char * | query,
|  | qdb_query_result_t ** | result
| ) |  |

Run the provided query and creates a table directory with the results.

For the complete grammar, please refer to the documentation.

Queries are transactional.

The complexity of this function is dependent on the complexity of the query.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | query | A pointer to a null-terminated UTF-8 string representing the query to perform.
  [out] | result | A pointer to a pointer of qdb_query_result_t that will receive the results. It must be released later with qdb_release.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release, qdb_option_set_client_max_parallelism

QDB_API_LINKAGE qdb_error_t qdb_query_continuous | ( | qdb_handle_t | handle,
|  | const char * | query,
|  | qdb_query_continuous_mode_type_t | mode,
|  | qdb_query_cont_callback_t | cb,
|  | void * | cb_context,
|  | qdb_query_cont_handle_t * | cont_handle
| ) |  |

Continuously and efficiently query the server with the given query.

A continuous query receives results in a callback asynchronously as they are available on the server. This API uses push notifications from the server to minimize data exchange and resource usage.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | query | A pointer to a null-terminated UTF-8 string representing the query to perform. Any valid QuasarDB query is supported.
  | mode | The mode of the query. Full will return all values at every call whereas new values will only deliver updates values.
  | cb | A pointer to a function that will be called when new data is available
  | cb_context | An opaque pointer to any client managed structure to pass to the callback. May be null if no context is needed.
  [out] | cont_handle | A handle to the continuous query handle. Updates to the query will be received until qdb_release is called on this handle.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE qdb_error_t qdb_query_dedup | ( | qdb_dedup_handle_t | dedup_handle,
|  | const qdb_query_result_t * | result,
|  | qdb_query_result_t ** | dedup_result
| ) |  |

Deduplicates query results.

Rows already seen by previous calls to qdb_query_dedup for the given deduplication handler will not be included in the deduplicated results.

Parameters

  | dedup_handle | A valid deduplication handle previously initialized by qdb_init_query_dedup.
  | result | A pointer to a qdb_query_result_t that holds the results from a previous call to qdb_query. Results given to a deduplication filter must all come from the same query, but different ranges or where clauses are allowed.
  [out] | dedup_result | A pointer to a pointer of qdb_query_result_t that will receive the deduplicated results. It must be released later with qdb_release.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE qdb_error_t qdb_query_dedup_prune | ( | qdb_dedup_handle_t | dedup_handle,
|  | const qdb_ts_range_t * | range
| ) |  |

Removes previously seen rows from the given deduplication handler.

Parameters

  dedup_handle | A valid deduplication handle previously initialized by qdb_init_query_dedup. If the $timestamp special column hasn't been selected all rows are removed.
  range | A pointer to a qdb_ts_range_t (interval) for which rows should be removed.

Returns
  A qdb_error_t code indicating success or failure.

QDB_API_LINKAGE qdb_error_t qdb_query_experimental | ( | qdb_handle_t | handle,
|  | const char * | query,
|  | qdb_query_experimental_result_t ** | result
| ) |  |

Run the provided query to return a table.

Currently only supports querying some columns of a timeseries.

Queries are transactional.

The complexity of this function is dependent on the complexity of the query.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | query | A pointer to a null-terminated UTF-8 string representing the query to perform.
  [out] | result | A pointer to a pointer of qdb_query_result_t that will receive the results. It must be released later with qdb_release.

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

Warning
  This function is still under development. Performance and compatibility are not guaranteed.

QDB_API_LINKAGE qdb_error_t qdb_query_experimental_to_arrow | ( | qdb_handle_t | handle,
|  | const qdb_query_experimental_result_t * | result,
|  | qdb_query_arrow_result_t ** | result_copy
| ) |  |

Copies a query result to the Arrow format.

The allocated results have to be released later with qdb_release.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | result | A pointer to a query result to clone
  [out] | result_copy | A pointer to a a pointer that will receive API-allocated results whose content will be a copy of the source results

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release

QDB_API_LINKAGE qdb_error_t qdb_query_find | ( | qdb_handle_t | handle,
|  | const char * | query,
|  | const char *** | aliases,
|  | size_t * | alias_count
| ) |  |

Retrieves all entries' aliases that match the specified find query.

For the complete grammar, please refer to the documentation.

Queries are transactional.

The complexity of this function is dependent on the complexity of the query.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | query | A pointer to a null-terminated UTF-8 string representing the query to perform.
  [out] | aliases | A pointer to an array of null-terminated UTF-8 string that will list the aliases of the entries matching the query.
  [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_release

QDB_API_LINKAGE qdb_error_t qdb_query_to_arrow | ( | qdb_handle_t | handle,
|  | const qdb_query_result_t * | result,
|  | qdb_query_arrow_result_t ** | result_copy
| ) |  |

Copies a query result to the Arrow format.

The allocated results have to be released later with qdb_release.

Parameters

  | handle | A valid handle previously initialized by qdb_open or qdb_open_tcp.
  | result | A pointer to a query result to clone
  [out] | result_copy | A pointer to a a pointer that will receive API-allocated results whose content will be a copy of the source results

Returns
  A qdb_error_t code indicating success or failure.

See Also
  qdb_release