Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
range-query.h File Reference

Builder for queries that select a range of events from a time series. More...

Data Structures

struct  diffusion_time_series_range_query_params_s
 Structure supplied when issuing a diffusion_time_series_select_from request. More...
 

Typedefs

typedef struct
DIFFUSION_TIME_SERIES_RANGE_QUERY_T 
DIFFUSION_TIME_SERIES_RANGE_QUERY_T
 Opaque diffusion time series range query struct.
 
typedef struct
DIFFUSION_TIME_SERIES_QUERY_RESULT_T 
DIFFUSION_TIME_SERIES_QUERY_RESULT_T
 Opaque diffusion time series query result struct.
 
typedef int(* on_query_result_cb )(const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result, void *context)
 Callback when a range query result is received. More...
 
typedef struct
diffusion_time_series_range_query_params_s 
DIFFUSION_TIME_SERIES_RANGE_QUERY_PARAMS_T
 Structure supplied when issuing a diffusion_time_series_select_from request.
 

Enumerations

enum  DIFFUSION_QUERY_RESULT_STRUCTURE_T { VALUE_EVENT_STRUCTURE, EDIT_EVENT_STRUCTURE }
 Describes the structural properties of a query result. More...
 

Functions

bool diffusion_time_series_range_query_for_values (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform a value range query with the view range set to the entire time series. More...
 
bool diffusion_time_series_range_query_for_edits (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the view range set to the entire time series. More...
 
bool diffusion_time_series_range_query_edit_range (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform a value range query with the edit range set to the entire time series. More...
 
bool diffusion_time_series_range_query_all_edits (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the edit range that selects all edits in the entire time series. More...
 
bool diffusion_time_series_range_query_latest_edits (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the edit range that selects latest edits in the entire time series. More...
 
bool diffusion_time_series_range_query_from (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long sequence, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be an absolute sequence number. More...
 
bool diffusion_time_series_range_query_from_time (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, time_t t, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be an absolute sequence number. More...
 
bool diffusion_time_series_range_query_from_start (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be the start of the time series. More...
 
bool diffusion_time_series_range_query_from_last (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long count, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be a relative offset before the end of the time series. More...
 
bool diffusion_time_series_range_query_from_last_millis (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long time_span, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be a relative time from the timestamp of the last event in the time series. More...
 
bool diffusion_time_series_range_query_to (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long sequence, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at an absolute sequence number. More...
 
bool diffusion_time_series_range_query_to_time (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, time_t t, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at an absolute sequence number. More...
 
bool diffusion_time_series_range_query_to_start (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at the start of the time series. More...
 
bool diffusion_time_series_range_query_next (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long count, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a range of events following the anchor. More...
 
bool diffusion_time_series_range_query_next_millis (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long time_span, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a temporal range of events following the anchor. More...
 
bool diffusion_time_series_range_query_previous (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long count, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a range of events preceding the anchor. More...
 
bool diffusion_time_series_range_query_previous_millis (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long time_span, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a temporal range of events preceding the anchor. More...
 
bool diffusion_time_series_range_query_until_last (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long count, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end a number of events before the end of the time series. More...
 
bool diffusion_time_series_range_query_until_last_millis (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long time_span, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at a relative time from the timestamp of the last event in the time series. More...
 
bool diffusion_time_series_range_query_limit (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, long count, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to return at most count events. More...
 
bool diffusion_time_series_range_query_as (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query, DIFFUSION_DATATYPE *datatype, DIFFUSION_API_ERROR *error)
 Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with a different query value type. More...
 
DIFFUSION_TIME_SERIES_RANGE_QUERY_Tdiffusion_time_series_range_query_dup (const DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query)
 Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_RANGE_QUERY_T More...
 
void diffusion_time_series_range_query_free (DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query)
 Free a memory allocated DIFFUSION_TIME_SERIES_RANGE_QUERY_T More...
 
LIST_Tdiffusion_time_series_query_result_get_events (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Returns a list of DIFFUSION_TIME_SERIES_EVENT_Ts selected by the query. More...
 
long diffusion_time_series_query_result_get_selected_count (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Returns the number of events selected by the query. More...
 
int diffusion_time_series_query_result_is_complete (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Returns whether this result includes all events selected by the query. More...
 
DIFFUSION_QUERY_RESULT_STRUCTURE_T diffusion_time_series_query_result_structure (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Returns a description of the structure of the query result. More...
 
DIFFUSION_TIME_SERIES_QUERY_RESULT_Tdiffusion_time_series_query_result_merge (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result, const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *other)
 Merge this result with other, combining original events and edit events, to produce a DIFFUSION_TIME_SERIES_QUERY_RESULT_T of type VALUE_EVENT_STRUCTURE More...
 
DIFFUSION_TIME_SERIES_QUERY_RESULT_Tdiffusion_time_series_query_result_dup (const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_QUERY_RESULT_T More...
 
void diffusion_time_series_query_result_free (DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result)
 Free a memory allocated DIFFUSION_TIME_SERIES_QUERY_RESULT_T More...
 
bool diffusion_time_series_select_from (SESSION_T *session, const DIFFUSION_TIME_SERIES_RANGE_QUERY_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
 Specifies a logical start point within the topic tree. More...
 

Detailed Description

Builder for queries that select a range of events from a time series.

  • value range queries,
  • latest edits edit range queries, and
  • all edits edit range queries.

diffusion_time_series_range_query returns a default range query. Further queries with different parameters can be configured using the functions of this header file. Function calls can be chained together in a fluent manner to create a query. For example:

  // A value range query that selects up to 100 original events from the
  // start of a time series.
  DIFFUSION_TIME_SERIES_RANGE_QUERY_T *range_query = diffusion_time_series_range_query();
  diffusion_time_series_range_query_for_values(range_query, NULL);
  diffusion_time_series_range_query_from_start(range_query, NULL);
  diffusion_time_series_range_query_next(range_query, 100, NULL);
  

Creating value range queries

A value range query returns a merged view of part of a time series. This is the most common time series query and appropriate for most applications.

A value range query begins with the diffusion_time_series_range_query_for_values operator, followed by the view range. The view range determines the range of original events the time series that are of interest.

The events returned by the query are constrained by an optional edit range, introduced by the diffusion_time_series_range_query_edit_range operator. An event will only be included in the result if it is in the edit range. Let's consider some examples to see how the view range and the edit range interact.

Query Meaning
For each original event in the time series, either return the latest edit event or if it has no edit events, return the original event.
For each original event with a sequence number between 100 and 150 (inclusive), either return the latest edit event or if it has no edit events, return the original event.

For each original event with a sequence number between 100 and 150 (inclusive), return the latest edit event with a sequence number greater than or equal to 400.

The result of this query will not include any original events because there is no overlap between the view range and the edit range.

Value range queries can be further refined using the diffusion_time_series_range_query_limit and diffusion_time_series_range_query_as operators.

Creating edit range queries

An edit range query returns an unmerged view of a time series than can include both original events and the edit events that replace them. Edit range queries are rarely needed – value range queries satisfy most use cases.

An edit range query begins with the diffusion_time_series_range_query_for_edits operator, followed by the view range. The view range determines the range of original events the time series that are of interest. The result will only contain original events that are in the view range, and edit events for original events in the view range.

The events returned by the query are constrained by an optional edit range, introduced by the diffusion_time_series_range_query_latest_edits or diffusion_time_series_range_query_all_edits operators. An event will only be included in the result if it is in the edit range. Let's consider some example edit range queries.

Query Meaning
Return all events in a time series.
* diffusion_time_series_range_query_from(range_query, 100, NULL);
* diffusion_time_series_range_query_to(range_query, 150, NULL);
Return the original events with a sequence number between 100 and 150 (inclusive) and all edit events in the time series that refer to the original events.
Return the original events with a sequence number between 100 and 150 (inclusive) and the latest edit events in the time series that refer to the original events.

For each original event with a sequence number between 100 and 150, (inclusive) return all edit events with a sequence number greater than or equal to 400.

The result of this query will not include any original events because there is no overlap between the view range and the edit range.

Edit range queries can be further refined using the diffusion_time_series_range_query_limit and diffusion_time_series_range_query_as operators.

Range expressions

Range expressions are used to specify the view and edit ranges in value range and edit range queries. Each range expression has an anchor that determines where to start, and a span that determines where the range ends. Both anchor and span are inclusive – if an anchor or span falls on an event, the event is included in the result.

Both anchor and the span are optional. If the anchor is unspecified, the range begins at the start of the time series. If the span is unspecified, the range continues until the end of the time series.

Anchors

Anchor Meaning
Sets the anchor at an absolute sequence number.
Sets the anchor at the start of the time series.
Sets the anchor at an absolute time.
Sets the anchor at a relative offset before the end of the time series. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
Sets the anchor at a relative time before the timestamp of the last event of the time series.

An anchor point can be before the start or after the end of the time series.

Spans

Span Meaning
The range ends at an absolute sequence number. The sequence argument may be before or after the anchor.
The range ends at the start of the time series.
The range ends at an absolute time. The instant argument may be before or after the anchor.
The range ends at an event that is a relative number of events after the anchor. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
The range ends at an event that is a relative time after the anchor.
The range ends at an event that is a relative number of events before the anchor. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
The range ends at an event that is a relative time before the anchor.
The range ends at an event that is a relative number of events before the end of the time series. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
The range ends at an event that is a relative time before the timestamp of the last event of the time series.

A span can specify an end point that is before the start or after the end of the time series.

If the span specifies an end point after the anchor, the range includes the first event at or following the anchor and ends at the last event at or preceding the end point. If the span specifies an end point before the anchor, the range includes the first event at or preceding the anchor and ends at the last event at or after the end point.

Using the builder functions

Although the natural order of operators in a query is as shown in the syntax diagrams above, range query builder functions – those that return another range query – can be applied in any order with the following exceptions:

  • diffusion_time_series_range_query_edit_range only applies to value range queries, so cannot follow diffusion_time_series_range_query_for_edits without an intervening diffusion_time_series_range_query_for_values;
  • diffusion_time_series_range_query_latest_edits and diffusion_time_series_range_query_all_edits only apply to edit range queries, so cannot follow diffusion_time_series_range_query_for_values without an intervening diffusion_time_series_range_query_for_edits.

Each function overrides some configuration of the range query to which it is applied, as summarized in the following table.

Builder function Operator type Overridden configuration

Value range Overrides the existing query type to create a new value range query. Overrides the existing view range with a new view range that selects the entire time series. The existing edit range is copied unchanged.
Value range Overrides the existing query type to create a new edit range query that includes all edits. Overrides the existing view range with a new view range that selects the entire time series. The existing edit range is copied unchanged.
Edit range Overrides the existing edit range with a new edit range that selects the entire time series. The existing view range is copied unchanged.
Returns false and populates error if this is not a value range query.

Edit range

Overrides the existing edit range with a new edit range that selects the entire time series. The existing view range is copied unchanged.
Returns false and populates error if this is not an edit range query.



Anchor

Overrides the anchor of the current range.





Span Overrides the span of the current range.

Limit

Overrides the limit.

Query value type

Overrides the query value type.

Typedef Documentation

typedef int(* on_query_result_cb)(const DIFFUSION_TIME_SERIES_QUERY_RESULT_T *query_result, void *context)

Callback when a range query result is received.

Parameters
query_resultThe query result.
contextUser supplied context.
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Describes the structural properties of a query result.

Enumerator
VALUE_EVENT_STRUCTURE 

The result is ordered by the original event sequence number, presenting edit events instead of the original events they replace.

The original event sequence number of an event e is diffusion_time_series_event_get_sequence(diffusion_time_series_event_get_original_event(e)). It is equal to diffusion_time_series_event_get_sequence(e), if and only if e is an original event.

The result has the following properties:

  • The sequence of each event in the result is unique.
  • The original event sequence of each event in the result is unique.
  • The result is ordered by original event sequence. The original event sequence of each subsequent event in the result is greater than its predecessor.
  • If no events have been removed from the time series, the original event sequence of each subsequent event is one greater than its predecessor.
  • If an event is an original event, the query found no corresponding edit events.
  • If an event is an edit event, its timestamp attribute may lie outside the query range. Consequentially, the sequence and timestamp attributes of the events may be non-sequential.
EDIT_EVENT_STRUCTURE 

The result is presented in time series order.

The result has the following properties:

  • The sequence of each event in the result is unique.
  • The result is ordered by sequence. The sequence of each subsequent event in the result is greater than its predecessor.
  • Edit event timestamps may lie outside the query range.
  • The result can have multiple edit events for the same original event.

Function Documentation

DIFFUSION_TIME_SERIES_QUERY_RESULT_T* diffusion_time_series_query_result_dup ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_QUERY_RESULT_T

Parameters
query_resultThe query result to be copied.
Returns
a copy of a DIFFUSION_TIME_SERIES_QUERY_RESULT_T. NULL, if query_result is NULL.
void diffusion_time_series_query_result_free ( DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Free a memory allocated DIFFUSION_TIME_SERIES_QUERY_RESULT_T

Parameters
query_resultThe DIFFUSION_TIME_SERIES_QUERY_RESULT_T to be freed.
LIST_T* diffusion_time_series_query_result_get_events ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Returns a list of DIFFUSION_TIME_SERIES_EVENT_Ts selected by the query.

Parameters
query_resultThe range query result
Returns
a list of time series events selected by the query. If query_result is NULL, NULL will be returned.
long diffusion_time_series_query_result_get_selected_count ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Returns the number of events selected by the query.

Parameters
query_resultThe range query result
Returns
the number of events selected by the query. If query_result is NULL, -1 will be returned.
int diffusion_time_series_query_result_is_complete ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Returns whether this result includes all events selected by the query.

Equivalent to:

return diffusion_time_series_query_result_get_selected_count(result) == list_get_size(diffusion_time_series_query_result_get_events(result));
Parameters
query_resultThe range query result
Returns
1 if the query result is complete, 0 if it is not. -1 will be return if query_result is NULL.
DIFFUSION_TIME_SERIES_QUERY_RESULT_T* diffusion_time_series_query_result_merge ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result,
const DIFFUSION_TIME_SERIES_QUERY_RESULT_T other 
)

Merge this result with other, combining original events and edit events, to produce a DIFFUSION_TIME_SERIES_QUERY_RESULT_T of type VALUE_EVENT_STRUCTURE

The following rules are applied to calculate the result:

  • If this result and other have an event with equal sequence numbers, the event from other is selected.
  • An edit event is selected in place of its original event.
  • If there are multiple edit events of an original edit, the one with the highest sequence is selected.

The returned result implements diffusion_time_series_query_result_is_complete to return true and diffusion_time_series_query_result_get_selected_count to return the count of events in the stream, regardless of whether this result is complete.

Parameters
query_resultThe query result to be merged
otherThe query result to be merged
Returns
a merged query result. If query_result or other is NULL, then NULL will be returned.
DIFFUSION_QUERY_RESULT_STRUCTURE_T diffusion_time_series_query_result_structure ( const DIFFUSION_TIME_SERIES_QUERY_RESULT_T query_result)

Returns a description of the structure of the query result.

Parameters
query_resultThe range query result
Returns
a DIFFUSION_QUERY_RESULT_STRUCTURE_T that describes the structure of the result stream. -1 will be return if query_result is NULL.
bool diffusion_time_series_range_query_all_edits ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the edit range that selects all edits in the entire time series.

This operator can only be applied to edit range queries. If this operator is applied to a non-edit range query, false will be returned and error, if non-NULL, will be populated.

The default query returned by diffusion_time_series_range_query is a value range query. The diffusion_time_series_range_query_for_edits operator can be used to create an edit range query from a value range query.

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_as ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_DATATYPE datatype,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with a different query value type.

A query can only be evaluated successfully against time series topics with a compatible event data type. If a query function is called for a time series topic with an incompatible event data type, the on_error callback from the function call's DIFFUSION_TIME_SERIES_RANGE_QUERY_PARAMS_T will be invoked.

The default range query does not have a bound datatype value which means, by default, it is compatible with all time series value data types. When a value is received, the appropriate datatype 'read' function should be used to extract the type specific value.

Operator type: query value type

Parameters
range_queryThe range query to be mutated
datatypePointer to the datatype value. This can be NULL if the range query is required to be compatible with all time series value data types.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
DIFFUSION_TIME_SERIES_RANGE_QUERY_T* diffusion_time_series_range_query_dup ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query)

Returns a memory allocated copy of a DIFFUSION_TIME_SERIES_RANGE_QUERY_T

Parameters
range_queryThe range query to be copied.
Returns
a copy of a DIFFUSION_TIME_SERIES_RANGE_QUERY_T. NULL, if range_query is NULL.
bool diffusion_time_series_range_query_edit_range ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform a value range query with the edit range set to the entire time series.

This operator can only be applied to value range queries. If this operator is applied to a non-value range query, false will be returned and error, if non-NULL, will be populated.

The default query returned by diffusion_time_series_range_query is a value range query. The diffusion_time_series_range_query_for_values function can be used to create a value range query from an edit range query.

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_for_edits ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the view range set to the entire time series.

Operator type: value range

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_for_values ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform a value range query with the view range set to the entire time series.

Operator type: value range

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
void diffusion_time_series_range_query_free ( DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query)

Free a memory allocated DIFFUSION_TIME_SERIES_RANGE_QUERY_T

Parameters
range_queryThe DIFFUSION_TIME_SERIES_RANGE_QUERY_T to be freed.
bool diffusion_time_series_range_query_from ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  sequence,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be an absolute sequence number.

Operator type: anchor

Parameters
range_queryThe range query to be mutated
sequenceAbsolute sequence number specifying the anchor of the returned range
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_from_last ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  count,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be a relative offset before the end of the time series.

Operator type: anchor

Parameters
range_queryThe range query to be mutated
countSpecifies the anchor as a number of events before the end of the time series. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_from_last_millis ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  time_span,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be a relative time from the timestamp of the last event in the time series.

Operator type: anchor

Parameters
range_queryThe range query to be mutated
time_spanSpecifies anchor as a number of milliseconds relative to the timestamp of the latest event in the time series.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_from_start ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be the start of the time series.

There is a difference between diffusion_time_series_range_query_from_start(range_query, error) and diffusion_time_series_range_query_from(range_query, 0, error) if the range also ends before the first. For example:

diffusion_time_series_range_query_from_start(range_query, error);
diffusion_time_series_range_query_to_start(range_query, error);

is always empty, but

diffusion_time_series_range_query_from_start(range_query, error);
diffusion_time_series_range_query_to(range_query, 0, error);

includes the event with sequence number 0.

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_from_time ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
time_t  t,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the anchor of the current range configured to be an absolute sequence number.

Operator type: anchor

Parameters
range_queryThe range query to be mutated
tAbsolute time specifying the end of the range
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_latest_edits ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to perform an edit range query with the edit range that selects latest edits in the entire time series.

This operator can only be applied to edit range queries. If this operator is applied to a non-edit range query, false will be returned and error, if non-NULL, will be populated.

The default query returned by diffusion_time_series_range_query is a value range query. The diffusion_time_series_range_query_for_edits operator can be used to create an edit range query from a value range query.

Operator type: edit range

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_limit ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  count,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T to return at most count events.

If the query would otherwise select more than count events, only the latest count values (those with the highest sequence numbers) are returned.

diffusion_time_series_query_result_is_complete can be used to determine whether a query has returned an incomplete result.

Operator type: limit

Parameters
range_queryThe range query to be mutated
countThe maximum number of events to return
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_next ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  count,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a range of events following the anchor.

Operator type: span

Parameters
range_queryThe range query to be mutated
countSpecifies the end of the range of events to select following the anchor. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_next_millis ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  time_span,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a temporal range of events following the anchor.

Operator type: span

Parameters
range_queryThe range query to be mutated
time_spanThe time span in milliseconds of events following the anchor to select
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_previous ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  count,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a range of events preceding the anchor.

Operator type: span

Parameters
range_queryThe range query to be mutated
countSpecifies the end of the range of events to select preceding the anchor. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_previous_millis ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  time_span,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to select a temporal range of events preceding the anchor.

Operator type: span

Parameters
range_queryThe range query to be mutated
time_spanThe time span in milliseconds of events preceding the anchor to select
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_to ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  sequence,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at an absolute sequence number.

Operator type: span

Parameters
range_queryThe range query to be mutated
sequenceAbsolute sequence number specifying the end of the returned range
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_to_start ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at the start of the time series.

There is a difference between diffusion_time_series_range_query_from_start(range_query, error) and diffusion_time_series_range_query_from(range_query, 0, error) if the range also ends before the first. For example:

diffusion_time_series_range_query_from_start(range_query, error);
diffusion_time_series_range_query_to_start(range_query, error);

is always empty, but

diffusion_time_series_range_query_from_start(range_query, error);
diffusion_time_series_range_query_to(range_query, 0, error);

includes the event with sequence number 0.

Operator type: span

Parameters
range_queryThe range query to be mutated
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_to_time ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
time_t  t,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at an absolute sequence number.

Operator type: span

Parameters
range_queryThe range query to be mutated
tAbsolute time specifying the end of the range
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_until_last ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  count,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end a number of events before the end of the time series.

Operator type: span

Parameters
range_queryThe range query to be mutated
countSpecifies the end of the range of events to select as a number of events before the end of the time series. For value range queries, count is the number of original events. For edit range queries, count is the number of events of any type.
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_range_query_until_last_millis ( const DIFFUSION_TIME_SERIES_RANGE_QUERY_T range_query,
long  time_span,
DIFFUSION_API_ERROR error 
)

Mutates this DIFFUSION_TIME_SERIES_RANGE_QUERY_T with the span of the current range configured to end at a relative time from the timestamp of the last event in the time series.

Operator type: span

Parameters
range_queryThe range query to be mutated
time_spanSpecifies the end of the range of events to select as a number of milliseconds relative to the timestamp of the latest event in the time series
errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.
bool diffusion_time_series_select_from ( SESSION_T session,
const DIFFUSION_TIME_SERIES_RANGE_QUERY_PARAMS_T  params,
DIFFUSION_API_ERROR api_error 
)

Specifies a logical start point within the topic tree.

Parameters
sessionThe session handle. If NULL, the function returns immediately.
paramsParameters describing the range query and callback handlers which may be invoked in response.
api_errorPopulated if an error occurs. Can be NULL.
Returns
true if the operation was successful. False, otherwise. In this case, if a non-NULL api_error pointer has been provided, this will be populated with the error information and should be freed with diffusion_api_error_free.