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_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`. 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_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_T`s 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_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` More...

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` 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

diffusion_time_series_range_query_for_values(range_query, NULL);

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.

diffusion_time_series_range_query_for_values(range_query, NULL);
diffusion_time_series_range_query_from(range_query, 100, NULL);
diffusion_time_series_range_query_to(range_query, 150, NULL); 

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.

diffusion_time_series_range_query_for_values(range_query, NULL);
diffusion_time_series_range_query_from(range_query, 100, NULL);
diffusion_time_series_range_query_to(range_query, 150, NULL);
diffusion_time_series_range_query_edit_range(range_query, NULL);
diffusion_time_series_range_query_from(range_query, 400, NULL); 

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
diffusion_time_series_range_query_for_edits(range_query, NULL);	Return all events in a time series.
diffusion_time_series_range_query_for_edits(range_query, NULL); 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.
diffusion_time_series_range_query_for_edits(range_query, NULL); diffusion_time_series_range_query_from(range_query, 100, NULL); diffusion_time_series_range_query_to(range_query, 150, NULL); diffusion_time_series_range_query_latest_edits(range_query, NULL);	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.
diffusion_time_series_range_query_for_edits(range_query, NULL); diffusion_time_series_range_query_from(range_query, 100, NULL); diffusion_time_series_range_query_to(range_query, 150, NULL); diffusion_time_series_range_query_all_edits(range_query, NULL); diffusion_time_series_range_query_from(range_query, 400, NULL);	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
diffusion_time_series_range_query_from	Sets the anchor at an absolute sequence number.
diffusion_time_series_range_query_from_start	Sets the anchor at the start of the time series.
diffusion_time_series_range_query_from_time	Sets the anchor at an absolute time.
diffusion_time_series_range_query_from_last	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.
diffusion_time_series_range_query_from_last_millis	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
diffusion_time_series_range_query_to	The range ends at an absolute sequence number. The `sequence` argument may be before or after the anchor.
diffusion_time_series_range_query_to_start	The range ends at the start of the time series.
diffusion_time_series_range_query_to_time	The range ends at an absolute time. The `instant` argument may be before or after the anchor.
diffusion_time_series_range_query_next	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.
diffusion_time_series_range_query_next_millis	The range ends at an event that is a relative time after the anchor.
diffusion_time_series_range_query_previous	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.
diffusion_time_series_range_query_previous_millis	The range ends at an event that is a relative time before the anchor.
diffusion_time_series_range_query_until_last	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.
diffusion_time_series_range_query_until_last_millis	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
diffusion_time_series_range_query_for_values	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.
diffusion_time_series_range_query_for_edits	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.
diffusion_time_series_range_query_edit_range	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.
diffusion_time_series_range_query_latest_edits diffusion_time_series_range_query_all_edits	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.
diffusion_time_series_range_query_from diffusion_time_series_range_query_from_start diffusion_time_series_range_query_from_last	Anchor	Overrides the anchor of the current range.
diffusion_time_series_range_query_to diffusion_time_series_range_query_to_start diffusion_time_series_range_query_next diffusion_time_series_range_query_previous diffusion_time_series_range_query_until_last	Span	Overrides the span of the current range.
diffusion_time_series_range_query_limit	Limit	Overrides the limit.
diffusion_time_series_range_query_as	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_result	The query result.
context	User supplied context.

Returns: HANDLERS_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

enum DIFFUSION_QUERY_RESULT_STRUCTURE_T

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_result The 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_result The 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_result The 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_result The 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_result The 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_result	The query result to be merged
other	The 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_result The 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
datatype	Pointer to the datatype value. This can be `NULL` if the range query is required to be compatible with all time series value data types.
error	Populated 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.

diffusion_time_series_range_query_free should be called on the pointer when no longer needed.

Parameters

range_query The 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
error	Populated 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_query The 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_query	The range query to be mutated
sequence	Absolute sequence number specifying the anchor of the returned range
error	Populated 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_query	The range query to be mutated
count	Specifies 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.
error	Populated 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_query	The range query to be mutated
time_span	Specifies anchor as a number of milliseconds relative to the timestamp of the latest event in the time series.
error	Populated 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
t	Absolute time specifying the end of the range
error	Populated 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
count	The maximum number of events to return
error	Populated 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_query	The range query to be mutated
count	Specifies 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.
error	Populated 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_query	The range query to be mutated
time_span	The time span in milliseconds of events following the anchor to select
error	Populated 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_query	The range query to be mutated
count	Specifies 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.
error	Populated 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_query	The range query to be mutated
time_span	The time span in milliseconds of events preceding the anchor to select
error	Populated 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_query	The range query to be mutated
sequence	Absolute sequence number specifying the end of the returned range
error	Populated 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_query	The range query to be mutated
error	Populated 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_query	The range query to be mutated
t	Absolute time specifying the end of the range
error	Populated 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_query	The range query to be mutated
count	Specifies 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.
error	Populated 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_query	The range query to be mutated
time_span	Specifies 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
error	Populated 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

session	The session handle. If NULL, the function returns immediately.
params	Parameters describing the range query and callback handlers which may be invoked in response.
api_error	Populated 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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Creating value range queries

Creating edit range queries

Range expressions

Anchors

Spans

Using the builder functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation