Time Series

diffusion.features.timeseries

TimeSeries

Bases: Component

This feature allows a session to update and query time series topics.

Time series topics

A time series is a sequence of events. Each event contains a value and has server-assigned metadata comprised of a sequence number, timestamp, and author. Events in a time series are ordered by increasing sequence number. Sequence numbers have values between 0 and Number.MAX_INTEGER and are contiguous: an event with sequence number n will be followed by one with sequence number n + 1 . Two events with the same sequence number will be equal – having the same timestamp, author, and value.

A time series topic allows sessions to access a time series that is maintained by the server. A time series topic has an associated DataType event data type, such as Binary, String, or JSON, that determines the type of value associated with each event.

This feature provides a historic query API for time series topics, allowing a session to query arbitrary sub-sequences of a time series.

To create a Time Series type, use the TimeSeries.of method.

The Session.topics and Topics.add_value_stream features complete the API, providing ways to create and subscribe to a time series topic using this type.

The API presents a time series as an append-only data structure of immutable events that is only changed by adding new events.

Edit events

Although a time series is append-only, an event can be overridden by appending an edit event. An edit event is a special type of event that overrides an earlier event in the time series (referred to as the original event) with a new value. When an edit event is added to a time series, the server retains both the original event and the edit event, allowing subscription and query results to reflect the edit.

For example, suppose a time series has two events with the values A and B , and the first event has been overridden by a later edit event that provides a new value of X . The server has the following information about the time series.

Sequence	value	tp
0	A	original event
1	B	original event
2	X	edit of sequence 0

The current value of the event with sequence number 0 is X .

If an original event has several edit events, the latest edit event (the one with the highest sequence number) determines its current value. Each edit event refers to an original event, never to another edit event.

Extending the example by appending a further edit event to the time series:

Sequence	value	tp
3	Y	second edit of sequence 0

The current value of the event with sequence number 0 is now Y .

Retained range

A time series topic retains a range of the most recent events. When a new event is added to the time series, older events that fall outside of the range are discarded. By default, this range includes the ten most recent events. A different range can be configured by setting the TIME_SERIES_RETAINED_RANGE property.

Subscribing to a time series topic

A session can select a time series topic and add a value stream to receive updates about events appended to the time series. Events are represented by Event instances. Each event has a value and metadata. An edit event has two sets of metadata – its own metadata and that of the original event that it replaces.

Subscription range

New subscribers are sent a range of events from the end of the time series. This is known as the subscription range. Configuring a subscription range is a convenient way to provide new subscribers with an appropriate subset of the latest events.

The default subscription range depends on whether the topic is configured to publish delta streams. If delta streams are enabled, new subscribers are sent the latest event if one exists. If delta streams are disabled, new subscribers are sent no events. Delta streams are enabled by default and can be disabled by setting the PUBLISH_VALUES_ONLY property to true.

A larger subscription range can be configured by setting the TIME_SERIES_SUBSCRIPTION_RANGE property. Regardless of this property, if delta streams are enabled, new subscribers will be sent at least the latest event if one exists.

If the range of events is insufficient, the subscribing session can use a range query to retrieve older events.

When configuring a non-default subscription range for a time series topic, register value streams before subscribing to the topic. The session only maintains a local cache if the latest value received for a topic, not the full subscription range. If a value stream is added after a session has subscribed to a matching time series topic, the new stream will only be notified of the latest value.

Updating a time series topic

A session can use append to submit a value to be added to a time series. The server will add an event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Providing a number as fourth argument to append allows a session to submit a value and supplied time. This provides control over the timestamp of the event. The supplied instant must be synchronous to or more recent than the latest event stored by the time series topic. There are no other restrictions.

A session can use edit to submit an edit to an original time series event, identified by its sequence number. The server will add an edit event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Time series topics can also be updated using the functionality provided by the Topic Update feature. This includes set_topic and Update Streams. This usage performs an append operation with the added benefits of Update Constraints, topic creation when updating (upsert), and delta streams. When using methods from Topic Update the sequence number, timestamp and author metadata will be generated using the same rules as TimeSeries.append but the associated EventMetadata will not be returned to the caller.

Changes to a time series made outside the API

The API presents a time series as an append-only data structure of immutable events that is only changed by adding new events. The API does not allow events to be deleted or edited.

There are circumstances in which events can be removed from a time series by server operations outside the API. For example, a time series topic can be configured to discard or archive older events to save storage space; or the time series may be held in memory and lost if the server restarts. Subscribed sessions are not notified when events are removed in this way, but a session can infer the removal of events that are no longer included in query results. Similarly, an event's value can be changed on the server. For example, if an administrator changes its value to redact sensitive data. Again, subscribed sessions are not notified when events are modified, but a session can infer this has happened from query results.

Whether such changes can happen for a particular time series topic depends on the topic specification, and the administrative actions that are allowed. To write a robust application, do not rely on two Event instances with the same sequence number but obtained though different API calls, being equal; nor that there are no sequence number gaps between events in query results.

Access control

The session must have the READ_TOPIC topic permission for a topic to query a time series topic. The QUERY_OBSOLETE_TIME_SERIES_EVENTS path permission is additionally required to evaluate an edit range query, or a value range query with an edit range.

The session must have the UPDATE_TOPIC path permission for a topic to append a new event to a time series topic. The EDIT_TIME_SERIES_EVENTS path permission is additionally required to submit an edit to any time series event. The more restrictive EDIT_OWN_TIME_SERIES_EVENTS path permission allows a session to submit edits to time series topic events that are authored by the principal of the calling session.

Since 6.8.3

edit async

edit(topic_path: str, original_sequence: int, value: TimeSeriesValueTypeOrRaw, value_type: TimeSeriesValueTypeClasses) -> EventMetadata

Update a time series topic by appending a new value that overrides the value of an existing event.

The existing event is identified by its sequence number and must be an original event.

The server will add an edit event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Parameters:

Name	Type	Description	Default
topic_path	str	the path of the time series topic to update	required
original_sequence	int	the sequence number of the original event to edit	required
value	TimeSeriesValueTypeOrRaw	the event value	required
value_type	TimeSeriesValueTypeClasses	the type of the supplied value. This must match the value type of the DataType configured as the time series topic's TIME_SERIES_EVENT_VALUE_TYPE event value type}.	required

Returns:

Type	Description
EventMetadata	a result that completes when a response is received from the server.

append async

append(topic_path: str, value: TimeSeriesValueTypeOrRaw, value_type: typing.Type[TimeSeriesValueType], timestamp: typing.Union[datetime.datetime, StrictInt] = None) -> EventMetadata

Update a time series topic by appending a new value.

The server will add an event to the end of the time series based on the supplied value, with a new sequence number, timestamp, and the author set to the authenticated principal of the session.

Parameters:

Name	Type	Description	Default
topic_path	str	the path of the time series topic to update	required
value	TimeSeriesValueTypeOrRaw	the event value	required
value_type	typing.Type[TimeSeriesValueType]	the type of the supplied value. This must match the value type of the DataType configured as the time series topic's TIME_SERIES_EVENT_VALUE_TYPE event value type.	required
timestamp	typing.Union[datetime.datetime, StrictInt]	an optional timestamp. The timestamp must be greater or equal to that of the most recent event appended to the topic. If specifying this as a datetime.datetime it should be timezone-aware, otherwise UTC will be assumed.	None

Returns:

Type	Description
EventMetadata	a result that completes when a response is received from the server.

of classmethod

of(val_type: typing.Type[VT]) -> typing.Type[TimeSeriesEventDataType[VT]]

Provide a Time Series datatype with the given Event[VT] value type.

Parameters:

Name	Type	Description	Default
val_type	typing.Type[VT]	the type of value that events will contain.	required

Returns:

Type	Description
typing.Type[TimeSeriesEventDataType[VT]]	The relevant Time Series data type.

range_query

range_query(tp: typing.Type[typing.Union[VT, diffusion.datatypes.BINARY]] = diffusion.datatypes.BINARY) -> RangeQuery[VT]

Return the default Range Query.

Parameters:

Name	Type	Description	Default
tp	typing.Type[typing.Union[VT, diffusion.datatypes.BINARY]]	the type of the query	diffusion.datatypes.BINARY

Returns:

Type	Description
RangeQuery[VT]	The default range query for the given type.

query

range_query

QuerySelf module-attribute

QuerySelf = typing.TypeVar('QuerySelf', bound='RangeQuery')

A RangeQuery or instance of a subclass thereof (used when passing the same type back).

RangeQuery

Bases: typing.Generic[VT], RangeQueryBase[VT]

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

Notes:

See diffusion.features.timeseries.TimeSeries for an overview of the various types of range query:

• value range queries
• latest edits edit range queries
• all edits edit range queries

RangeQuery.create_default returns a default RangeQuery. Further queries with different parameters can be configured using the methods of this interface. 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.

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 RangeQuery.for_values 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 a range.

The events returned by the query are constrained by an optional edit range, introduced by the RangeQuery.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
RangeQuery.for_values()	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.for_values().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.for_values().from_(100).to(150).edit_range().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 RangeQuery.limit and 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 RangeQuery.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. See Range expressions below for the various ways to specify a range.

The events returned by the query are constrained by an optional edit range, introduced by the RangeQuery.latest_edits or RangeQuery.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
RangeQuery.for_edits()	Return all events in a time series.
RangeQuery.for_edits().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.for_edits().from_(100).to(150).latest_edits()	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.for_edits().from_(100).to(150).all_edits().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 RangeQuery.limit and RangeQuery.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
RangeQuery.from_	Sets the anchor at an absolute sequence number.
RangeQuery.from_start	Sets the anchor at the start of the time series.
RangeQuery.from_	Sets the anchor at an absolute time.
RangeQuery.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.
RangeQuery.from_last	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
RangeQuery.to	The range ends at an absolute sequence number. The sequence argument may be before or after the anchor.
RangeQuery.to_start	The range ends at the start of the time series.
RangeQuery.to	The range ends at an absolute time. The time_span argument may be before or after the anchor.
RangeQuery.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.
RangeQuery.next	The range ends at an event that is a relative time after the anchor.
RangeQuery.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.
RangeQuery.previous	The range ends at an event that is a relative time before the anchor.
RangeQuery.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.
RangeQuery.until_last	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

RangeQuery builder methods - those that return another RangeQuery - can be applied in any order with the following exceptions:

• RangeQuery.edit_range only applies to value range queries, so cannot follow RangeQuery.for_edits without an intervening RangeQuery.for_values.

• RangeQuery.latest_edits and RangeQuery.all_edits only apply to edit range queries, so cannot follow RangeQuery.for_values without an intervening RangeQuery.for_edits.

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

Builder method	Operator type	Overriden configuration
RangeQuery.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.
RangeQuery.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.
RangeQuery.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.
RangeQuery.latest_edits, RangeQuery.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.
RangeQuery.from_, RangeQuery.from_start RangeQuery.from_last	Anchor	Overrides the anchor of the current range.
RangeQuery.to, RangeQuery.to_start, RangeQuery.next, RangeQuery.previous, RangeQuery.until_last	Span	Overrides the span of the current range.
RangeQuery.limit	Limit	Overrides the limit.
RangeQuery.as_	query value type	Overrides the query value type.

Added in version 6.9.

VT: The value data type

See Also

timeseries.TimeSeries timeseries.RangeQuery

create_default classmethod

create_default(session: InternalSession, tp: typing.Type[VT]) -> RangeQuery[VT]

Create the default Range Query for the given type

Parameters:

Name	Type	Description	Default
session	InternalSession	session from which this query will invoke select operations.	required
tp	typing.Type[VT]	initial value type of query	required

Returns:

Type	Description
RangeQuery[VT]	The according default Range Query object.

for_values

for_values() -> QuerySelf

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

Notes

Operator type: value range

Returns:

Type	Description
QuerySelf	The copy of this range query configured to perform a view range query with a new view range that selects the entire time series.

for_edits

for_edits() -> QuerySelf

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

Notes

Operator type: value range

Returns:

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

edit_range

edit_range() -> QuerySelf

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

Notes

This operator can only be applied to value range queries. The default query returned by RangeQuery is a value range query. The RangeQuery.for_values operator can be used to create a value range query from an edit range query.

Operator type: edit range

Returns:

Type	Description
QuerySelf	The copy of this range query configured to perform a view range query with a new edit range that selects the entire time series.

Raises:

Type	Description
InvalidOperationException	The current range query is not a value range query.

all_edits

all_edits() -> QuerySelf

Returns 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.

Notes

This operator can only be applied to edit range queries. The default query returned by RangeQuery is a value range query. The RangeQuery.for_edits operator can be used to create an edit range query from a value range query.

Operator type: edit range

Returns:

Type	Description
QuerySelf	The 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.

Raises:

Type	Description
InvalidOperationException	The current range query is not an edit range query.

latest_edits

latest_edits() -> QuerySelf

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

Notes

This operator can only be applied to edit range queries. The default query returned by RangeQuery is a value range query. The RangeQuery.for_edits operator can be used to create an edit range query from a value range query.

Operator type: edit range

Returns:

Type	Description
QuerySelf	The 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.

Raises:

Type	Description
InvalidOperationError	The current range query is not an edit range query.

with_current_range

with_current_range(range_selector: typing.Callable[[Range], Range]) -> QuerySelf

Creates a copy of the current query with a modified range. The range selector function. The new range query.

Parameters:

Name	Type	Description	Default
range_selector	typing.Callable[[Range], Range]		required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new transformed range.

from_

from_(anchor: typing.Union[StrictNonNegativeInt, StrictTimedelta]) -> QuerySelf

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

Notes

Operator type: anchor

Parameters:

Name	Type	Description	Default
anchor	typing.Union[StrictNonNegativeInt, StrictTimedelta]	Absolute time specifying the anchor of the range (as a datetime.timedelta from the epoch) or the absolute sequence number specifying the anchor of the returned range.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new anchor.

from_start

from_start() -> QuerySelf

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

Notes

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

Operator type: anchor

Returns:

Type	Description
QuerySelf	The copy of this range query with a new anchor.

from_last

from_last(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> QuerySelf

Returns 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.

Notes

Operator type: anchor

Takes only one argument - time_span and count are mutually exclusive.

Parameters:

Name	Type	Description	Default
offset	typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]	The anchor as: the time-span relative to the timestamp of the latest event in the time series (as a StrictNonNegativeInt) or the number of events before the end of the time series (as a StrictNonNegativeTimedelta)	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new anchor.

See Also

RangeQuery.from_last_milliseconds

from_last_milliseconds

from_last_milliseconds(milliseconds: StrictNonNegativeInt) -> QuerySelf

Returns 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.

Notes

Operator type: anchor

Parameters:

Name	Type	Description	Default
milliseconds	StrictNonNegativeInt	The milliseconds relative to the timestamp of the latest event in the time series.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new anchor.

See Also

RangeQuery.from_last

to

to(time: typing.Union[StrictNonNegativeInt, StrictTimedelta]) -> QuerySelf

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

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
time	typing.Union[StrictNonNegativeInt, StrictTimedelta]	Either: - the absolute sequence number specifying the end of the returned range (as a StrictNonNegativeInt or - the absolute time specifying the end of the range (as a StrictTimedelta)	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

to_start

to_start() -> QuerySelf

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

Notes

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

Operator type: span

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

until_last

until_last(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> QuerySelf

Returns a copy of this RangeQuery with the span of the current range configured to end at a relative point from the last event in the time series.

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
offset	typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]	The offset from the end of the time series as: - time span (as a datetime.timedelta) or - sequence count (as a non-negative int)	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

See Also

RangeQuery.until_last_milliseconds

until_last_milliseconds

until_last_milliseconds(milliseconds: StrictNonNegativeInt) -> QuerySelf

Returns 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.

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
milliseconds	StrictNonNegativeInt	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.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

See Also

RangeQuery.until_last

next

next(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> QuerySelf

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

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
offset	typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]	either the time span of events following the anchor to select (as a StrictNonNegativeTimedelta) or the end of the range of events to select following the anchor (as a StrictNonNegativeInt)	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

See Also

RangeQuery.next_milliseconds

next_milliseconds

next_milliseconds(milliseconds: StrictNonNegativeInt) -> QuerySelf

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

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
milliseconds	StrictNonNegativeInt	The time span in milliseconds of events following the anchor to select.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new next milliseconds value.

See Also

RangeQuery.next

previous

previous(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> QuerySelf

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

Notes

For value range queries, is the number of original events.For edit range queries, is the number of events of any type.

Operator type: span

Parameters:

Name	Type	Description	Default
offset	typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]	The end of the range of events to select preceding the anchor (as a StrictNonNegativeInt) or The time span of events preceding the anchor to select (as a StrictNonNegativeTimedelta)	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

previous_milliseconds

previous_milliseconds(milliseconds: StrictNonNegativeInt) -> QuerySelf

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

Notes

Operator type: span

Parameters:

Name	Type	Description	Default
milliseconds	StrictNonNegativeInt	The time span in milliseconds of events preceding the anchor to select.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new span.

See Also

RangeQuery.previous

limit

limit(count: StrictNonNegativeInt) -> QuerySelf

Returns a copy of this RangeQuery that returns at most count events.

Notes

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

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

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

Operator type: limit

Parameters:

Name	Type	Description	Default
count	StrictNonNegativeInt	The maximum number of events to return.	required

Returns:

Type	Description
QuerySelf	The copy of this range query with a new limit.

as_

as_(tp: typing.Type[VT_other]) -> RangeQuery[VT_other]

Returns a copy of this RangeQuery with a different query value type.

Notes

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 value type can be checked using AbstractDataType.validate_type. The default timeseries.RangeQuery has a query value type of BINARY, which is compatible with all time series value data types.

Operator type: query value type

Parameters:

Name	Type	Description	Default
tp	typing.Type[VT_other]	The new value type.	required

Returns:

Type	Description
RangeQuery[VT_other]	The copy of this range query with a new query value type.

select_from async

select_from(topic_path: pydantic.StrictStr) -> QueryResult[VT]

Evaluates this query for a time series topic.

Notes

The calling session must have the .PathPermission.READ_TOPIC topic permission for topic_path to evaluate the query. The PathPermission.QUERY_OBSOLETE_TIME_SERIES_EVENTS topic permission is also required if this is a RangeQuery.for_edits range query, or a RangeQuery.for_values range query with an RangeQuery.edit_range.

Parameters:

Name	Type	Description	Default
topic_path	pydantic.StrictStr	The path of the time series topic to query.	required

Returns:

Type	Description
QueryResult[VT]	An object providing the results.

Raises:

Type	Description
NoSuchTopicError	There is no topic bound to topic_path.
IncompatibleTopicError	The value type does not match the event data type of the time series topic bound to topic_path, or the topic bound to topic_path is not a time series topic.
InvalidQueryError	The range query is not valid for the time series.
SessionSecurityError	The calling session does not have PathPermission.READ_TOPIC permission for topic_path. The calling session does not have PathPermission.QUERY_OBSOLETE_TIME_SERIES_EVENTS permission for topic_path and this is a RangeQuery.for_edits range query, or a RangeQuery.for_values range query with an RangeQuery.edit_range.
SessionClosedError	The calling session is closed.

query_result

QueryResult

Bases: typing.Generic[VT]

The query result providing a stream of events.

Since

6.9

selected_count class-attribute

selected_count: int

Gets the number of events selected by the query.

Notes

This number may be greater than Stream.Count() due to a policy of the time series topic to limit the number of returned results, or the use of .

stream_structure class-attribute

stream_structure: StreamStructure = StreamStructure.VALUE_EVENT_STREAM

The stream structure of the provided events.

events class-attribute

events: typing.List[Event[VT]] = []

The events as a list.

is_complete property

is_complete: bool

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

Returns:

Type	Description
bool	True if QueryResult.selected_count is equal to the amount of events in QueryResult.events. Otherwise False.

merge

merge(other: QueryResult[VT]) -> QueryResult[VT]

Merges this result with other, combining original events and edit events, to produce a QueryResult of type StreamStructure.VALUE_EVENT_STREAM

Notes

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 to return true and to return the count of events in the stream, regardless of whether this result is complete.

Parameters:

Name	Type	Description	Default
other	QueryResult[VT]	The other query result to merge with.	required

Returns:

Type	Description
QueryResult[VT]	The newly merged query result.

Raises:

Type	Description
ArgumentNoneError	other is None

range_query_parameters

StreamStructure

Bases: enum.IntEnum

The structure of the event stream.

EDIT_EVENT_STREAM class-attribute

EDIT_EVENT_STREAM = enum.auto()

The stream contains edit events

VALUE_EVENT_STREAM class-attribute

VALUE_EVENT_STREAM = enum.auto()

The stream contains value events