com.pushtechnology.diffusion.client.features

Interface TimeSeries.RangeQuery<V>

Type Parameters:

V - query value type

All Superinterfaces:

TimeSeries.Query<V>

Enclosing interface:

TimeSeries

public static interface TimeSeries.RangeQuery<V>
extends TimeSeries.Query<V>

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

See TimeSeries for an overview of the various types of range query:

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

TimeSeries.rangeQuery() returns a default RangeQuery. Further queries with different parameters can be configured using the methods of this interface. TimeSeries.RangeQuery instances are immutable. Each method returns a copy of this query with a modified setting. Method calls can be chained together in a fluent manner to create a query. For example:

 RangeQuery<Bytes> defaultQuery =
     session.feature(TimeSeries.class).rangeQuery();

 // A value range query that selects up to 100 original events from the
 // start of a time series.
 RangeQuery<Bytes> first100 = defaultQuery.forValues().fromStart().next(100);
 

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.

The syntax of a value range query is shown in the following diagram.

A value range query begins with the forValues() operator, followed by the view range. The view range determines the range of original events the time series that are of interest. See Range expressions below for the various ways to specify RANGE.

The events returned by the query are constrained by an optional edit range, introduced by the editRange() 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
rangeQuery().forValues();	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.
rangeQuery().forValues().from(100).to(150);	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.
rangeQuery().forValues().from(100).to(150).editRange().from(400);	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 limit() and 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.

The syntax of an edit range query is shown in the following diagram.

An edit range query begins with the forEdits() 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. See Range expressions below for the various ways to specify RANGE.

The events returned by the query are constrained by an optional edit range, introduced by the latestEdits() or allEdits() 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
rangeQuery().forEdits();	Return all events in a time series.
rangeQuery().forEdits().from(100).to(150);	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.
rangeQuery().forEdits().from(100).to(150).latestEdits();	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.
rangeQuery().forEdits().from(100).to(150).allEdits().from(400);	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 limit() and 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

There are five ways to specify an anchor.

Anchor	Meaning
from(long)	Sets the anchor at an absolute sequence number.
fromStart()	Sets the anchor at the start of the time series.
from(Instant) from(Date)	Sets the anchor at an absolute time.
fromLast(long)	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.
fromLast(Duration) fromLastMillis(long)	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

There are nine ways to specify a span.

Span	Meaning
to(long)	The range ends at an absolute sequence number. The sequence argument may be before or after the anchor.
toStart()	The range ends at the start of the time series.
to(Instant) to(Date)	The range ends at an absolute time. The instant argument may be before or after the anchor.
next(long)	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.
next(Duration) nextMillis(long)	The range ends at an event that is a relative time after the anchor.
previous(long)	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.
previous(Duration) previousMillis(long)	The range ends at an event that is a relative time before the anchor.
untilLast(long)	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.
untilLast(Duration) untilLastMillis(long)	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 methods

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

• editRange() only applies to value range queries, so cannot follow forEdits() without an intervening forValues();
• latestEdits() and allEdits() only apply to edit range queries, so cannot follow forValues() without an intervening forEdits().

Each method overrides some configuration of the RangeQuery to which it is applied, as summarized in the following table.

Builder method	Operator type	Overridden configuration
forValues()	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.
forEdits()	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.
editRange()	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. Throws IllegalStateException if this is not a value range query.
latestEdits() allEdits()	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. Throws IllegalStateException if this is not an edit range query.
from() fromStart() fromLast()	Anchor	Overrides the anchor of the current range.
to() toStart() next() previous() untilLast()	Span	Overrides the span of the current range.
limit()	Limit	Overrides the limit.
as()	Query value type	Overrides the query value type.

See Also:

TimeSeries.rangeQuery()

Method Summary

Modifier and Type	Method and Description
TimeSeries.RangeQuery<V>	allEdits() Return a copy of this RangeQuery configured to perform an edit range query with the edit range that selects all edits in the entire time series.
<T> TimeSeries.RangeQuery<T>	as(Class<T> valueType) Return a copy of this RangeQuery with a different query value type.
TimeSeries.RangeQuery<V>	editRange() Return a copy of this RangeQuery configured to perform a value range query with the edit range set to the entire time series.
TimeSeries.RangeQuery<V>	forEdits() Return a copy of this RangeQuery configured to perform an edit range query with the view range set to the entire time series.
TimeSeries.RangeQuery<V>	forValues() Return a copy of this RangeQuery configured to perform a value range query with the view range set to the entire time series.
TimeSeries.RangeQuery<V>	from(Date date) Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute time.
TimeSeries.RangeQuery<V>	from(Instant instant) Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute time.
TimeSeries.RangeQuery<V>	from(long sequence) Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute sequence number.
TimeSeries.RangeQuery<V>	fromLast(Duration timeSpan) Return a copy of this RangeQuery with the anchor of the current range configured to be a relative time from the timestamp of the last event in the time series.
TimeSeries.RangeQuery<V>	fromLast(long count) Return a copy of this RangeQuery with the anchor of the current range configured to be a relative offset before the end of the time series.
TimeSeries.RangeQuery<V>	fromLastMillis(long timeSpan) Return a copy of this RangeQuery with the anchor of the current range configured to be a relative time from the timestamp of the last event in the time series.
TimeSeries.RangeQuery<V>	fromStart() Return a copy of this RangeQuery with the anchor of the current range configured to be the start of the time series.
TimeSeries.RangeQuery<V>	latestEdits() Return a copy of this RangeQuery configured to perform an edit range query with the edit range that selects latest edits in the entire time series.
TimeSeries.RangeQuery<V>	limit(long count) Return a copy of this RangeQuery that returns at most count events.
TimeSeries.RangeQuery<V>	next(Duration timeSpan) Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events following the anchor.
TimeSeries.RangeQuery<V>	next(long count) Return a copy of this RangeQuery with the span of the current range configured to select a range of events following the anchor.
TimeSeries.RangeQuery<V>	nextMillis(long timeSpan) Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events following the anchor.
TimeSeries.RangeQuery<V>	previous(Duration timeSpan) Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events preceding the anchor.
TimeSeries.RangeQuery<V>	previous(long count) Return a copy of this RangeQuery with the span of the current range configured to select a range of events preceding the anchor.
TimeSeries.RangeQuery<V>	previousMillis(long timeSpan) Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events preceding the anchor.
TimeSeries.RangeQuery<V>	to(Date date) Return a copy of this RangeQuery with the span of the current range configured to end at an absolute time.
TimeSeries.RangeQuery<V>	to(Instant instant) Return a copy of this RangeQuery with the span of the current range configured to end at an absolute time.
TimeSeries.RangeQuery<V>	to(long sequence) Return a copy of this RangeQuery with the span of the current range configured to end at an absolute sequence number.
TimeSeries.RangeQuery<V>	toStart() Return a copy of this RangeQuery with the span of the current range configured to end at the start of the time series.
TimeSeries.RangeQuery<V>	untilLast(Duration timeSpan) Return a copy of this RangeQuery 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.
TimeSeries.RangeQuery<V>	untilLast(long count) Return a copy of this RangeQuery with the span of the current range configured to end a number of events before the end of the time series.
TimeSeries.RangeQuery<V>	untilLastMillis(long timeSpan) Return a copy of this RangeQuery 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.

Methods inherited from interface com.pushtechnology.diffusion.client.features.TimeSeries.Query

selectFrom

Method Detail

forValues

TimeSeries.RangeQuery<V> forValues()

Return a copy of this RangeQuery configured to perform a value range query with the view range set to the entire time series.

Operator type: value range

Returns:

a copy of this range query configured to perform a view range query with a new view range that selects the entire time series

forEdits

TimeSeries.RangeQuery<V> forEdits()

Return a copy of this RangeQuery configured to perform an edit range query with the view range set to the entire time series.

Operator type: value range

Returns:

a copy of this range query configured to perform an edit range query with a new view range that selects the entire time series

editRange

TimeSeries.RangeQuery<V> editRange()
                            throws IllegalStateException

Return a copy of this RangeQuery configured 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. The default query returned by rangeQuery() is a value range query. The forValues() operator can be used to create a value range query from an edit range query.

Operator type: edit range

Returns:

a copy of this range query configured to perform a view range query with a new edit range that selects the entire time series

Throws:

IllegalStateException - if this is not a value range query

allEdits

TimeSeries.RangeQuery<V> allEdits()
                           throws IllegalStateException

Return a copy of this RangeQuery configured 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. The default query returned by rangeQuery() is a value range query. The forEdits() operator can be used to create an edit range query from a value range query.

Operator type: edit range

Returns:

a copy of this range query configured to perform an edit range query with a new edit range that selects all edits in the entire time series

Throws:

IllegalStateException - if this is not an edit range query

latestEdits

TimeSeries.RangeQuery<V> latestEdits()
                              throws IllegalStateException

Return a copy of this RangeQuery configured 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. The default query returned by rangeQuery() is a value range query. The forEdits() operator can be used to create an edit range query from a value range query.

Operator type: edit range

Returns:

a copy of this range query configured to perform an edit range query with a new edit range that selects the latest edits in the entire time series

Throws:

IllegalStateException - if this is not an edit range query

from

TimeSeries.RangeQuery<V> from(long sequence)
                       throws IllegalArgumentException

Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute sequence number.

Operator type: anchor

Parameters:

sequence - absolute sequence number specifying the anchor of the returned range

Returns:

a copy of this range query with a new anchor

Throws:

IllegalArgumentException - if sequence is negative

fromStart

TimeSeries.RangeQuery<V> fromStart()

Return a copy of this RangeQuery with the anchor of the current range configured to be the start of the time series.

There is a difference between fromStart() and from(0) if the range also ends before the first event of the time series. For example, fromStart()).toStart() is always empty, but from(0).toStart() includes the event with sequence number 0.

Operator type: anchor

Returns:

a copy of this range query with a new anchor

from

TimeSeries.RangeQuery<V> from(Instant instant)
                       throws ArithmeticException

Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute time.

Operator type: anchor

Parameters:

instant - absolute time specifying the anchor of range

Returns:

a copy of this range query with a new anchor

Throws:

ArithmeticException - if instant cannot be represented as a long number of milliseconds from the epoch of 1970-01-01T00:00:00Z, see Instant.toEpochMilli()

from

TimeSeries.RangeQuery<V> from(Date date)

Return a copy of this RangeQuery with the anchor of the current range configured to be an absolute time.

Operator type: anchor

Parameters:

date - absolute time specifying the anchor of range

Returns:

a copy of this range query with a new anchor

See Also:

from(Instant)

fromLast

TimeSeries.RangeQuery<V> fromLast(long count)
                           throws IllegalArgumentException

Return a copy of this RangeQuery with the anchor of the current range configured to be a relative offset before the end of the time series.

Operator type: anchor

Parameters:

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.

Returns:

a copy of this range query with a new anchor

Throws:

IllegalArgumentException - if count is negative

fromLast

TimeSeries.RangeQuery<V> fromLast(Duration timeSpan)
                           throws ArithmeticException,
                                  IllegalArgumentException

Return a copy of this RangeQuery 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:

timeSpan - specifies anchor relative to the timestamp of the latest event in the time series

Returns:

a copy of this range query with a new anchor

Throws:

IllegalArgumentException - if timeSpan is negative

ArithmeticException - if timeSpan cannot be represented as a long number of milliseconds, see Duration.toMillis()

fromLastMillis

TimeSeries.RangeQuery<V> fromLastMillis(long timeSpan)
                                 throws IllegalArgumentException

Return a copy of this RangeQuery 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:

timeSpan - specifies anchor as a number of milliseconds relative to the timestamp of the latest event in the time series

Returns:

a copy of this range query with a new anchor

Throws:

IllegalArgumentException - if timeSpan is negative

See Also:

fromLast(Duration)

to

TimeSeries.RangeQuery<V> to(long sequence)
                     throws IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to end at an absolute sequence number.

Operator type: span

Parameters:

sequence - absolute sequence number specifying the end of the returned range

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if sequence is negative

toStart

TimeSeries.RangeQuery<V> toStart()

Return a copy of this RangeQuery with the span of the current range configured to end at the start of the time series.

There is a difference between toStart() and to(0) if the range also starts before the first event of the time series. For example, fromStart().toStart() is always empty, but fromStart().to(0) includes the event with sequence number 0.

Operator type: span

Returns:

a copy of this range query with a new span

to

TimeSeries.RangeQuery<V> to(Instant instant)
                     throws ArithmeticException

Return a copy of this RangeQuery with the span of the current range configured to end at an absolute time.

Operator type: span

Parameters:

instant - absolute time specifying the end of the range

Returns:

a copy of this range query with a new span

Throws:

ArithmeticException - if instant cannot be represented as a long number of milliseconds from the epoch of 1970-01-01T00:00:00Z, see Instant.toEpochMilli()

to

TimeSeries.RangeQuery<V> to(Date date)

Return a copy of this RangeQuery with the span of the current range configured to end at an absolute time.

Operator type: span

Parameters:

date - absolute time specifying the end of the range

Returns:

a copy of this range query with a new span

See Also:

to(Instant)

next

TimeSeries.RangeQuery<V> next(long count)
                       throws IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a range of events following the anchor.

Operator type: span

Parameters:

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.

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if count is negative

next

TimeSeries.RangeQuery<V> next(Duration timeSpan)
                       throws ArithmeticException,
                              IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events following the anchor.

Operator type: span

Parameters:

timeSpan - the time span of events following the anchor to select

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

ArithmeticException - if timeSpan cannot be represented as a long number of milliseconds, see Duration.toMillis()

nextMillis

TimeSeries.RangeQuery<V> nextMillis(long timeSpan)
                             throws IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events following the anchor.

Operator type: span

Parameters:

timeSpan - the time span in milliseconds of events following the anchor to select

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

See Also:

next(Duration)

previous

TimeSeries.RangeQuery<V> previous(long count)
                           throws IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a range of events preceding the anchor.

Operator type: span

Parameters:

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.

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if count is negative

previous

TimeSeries.RangeQuery<V> previous(Duration timeSpan)
                           throws ArithmeticException,
                                  IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events preceding the anchor.

Operator type: span

Parameters:

timeSpan - the time span of events preceding the anchor to select

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

ArithmeticException - if timeSpan cannot be represented as a long number of milliseconds, see Duration.toMillis()

previousMillis

TimeSeries.RangeQuery<V> previousMillis(long timeSpan)
                                 throws IllegalArgumentException

Return a copy of this RangeQuery with the span of the current range configured to select a temporal range of events preceding the anchor.

Operator type: span

Parameters:

timeSpan - the time span in milliseconds of events preceding the anchor to select

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

See Also:

previous(Duration)

untilLast

TimeSeries.RangeQuery<V> untilLast(long count)
                            throws IllegalArgumentException

Return a copy of this RangeQuery 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:

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.

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if count is negative

untilLast

TimeSeries.RangeQuery<V> untilLast(Duration timeSpan)
                            throws ArithmeticException,
                                   IllegalArgumentException

Return a copy of this RangeQuery 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:

timeSpan - specifies the end of the range of events to select relative to the timestamp of the latest event in the time series

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

ArithmeticException - if timeSpan cannot be represented as a long number of milliseconds, see Duration.toMillis()

untilLastMillis

TimeSeries.RangeQuery<V> untilLastMillis(long timeSpan)
                                  throws IllegalArgumentException

Return a copy of this RangeQuery 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:

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

Returns:

a copy of this range query with a new span

Throws:

IllegalArgumentException - if timeSpan is negative

See Also:

untilLast(Duration)

limit

TimeSeries.RangeQuery<V> limit(long count)
                        throws IllegalArgumentException

Return a copy of this RangeQuery that returns 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.

This is most useful when a temporal span has been configured with next(Duration) or previous(Duration), where the potential number of returned events is unknown.

TimeSeries.QueryResult.isComplete() can be used to determine whether a query has returned an incomplete result.

Operator type: limit

Parameters:

count - the maximum number of events to return

Returns:

a copy of this range query with a new limit

Throws:

IllegalArgumentException - if count is negative

as

<T> TimeSeries.RangeQuery<T> as(Class<T> valueType)

Return a copy of this RangeQuery 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 method is called for a time series topic with an incompatible event data type, the query will complete exceptionally.

If the event data type of the time series topic is known, compatibility of a particular valueClass can be checked using dataType.canReadAsClass(valueClass). The default range query has a query value type of Bytes, which is compatible with all time series value data types.

Operator type: query value type

Returns:

a copy of this range query with a new query value type