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(topic_path: str, original_sequence: int, value: TimeSeriesValueTypeOrRaw, value_type: TimeSeriesValueTypeClasses) -> EventMetadata
async
¶
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(topic_path: str, value: TimeSeriesValueTypeOrRaw, value_type: typing.Type[TimeSeriesValueType], timestamp: typing.Union[datetime.datetime, StrictNonNegativeInt] = None) -> EventMetadata
async
¶
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, StrictNonNegativeInt]
|
an optional timestamp. The timestamp must be greater or equal to that of the most recent event appended to the topic |
None
|
Returns:
| Type | Description |
|---|---|
EventMetadata
|
a result that completes when a response is received from the server. |
of(val_type: typing.Type[VT]) -> typing.Type[TimeSeriesEventDataType[VT]]
classmethod
¶
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(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 = typing.TypeVar('QuerySelf', bound='RangeQuery')
module-attribute
¶
A RangeQuery or instance of a subclass thereof (used when passing the same type back).
RangeQueryType: TypeAlias = 'RangeQuery'
module-attribute
¶
A parameterizable RangeQuery or instance of a subclass thereof (used when changing the value type).
RangeQueryMode
¶
Bases: enum.IntEnum
The range query mode.
Since
6.9
VIEW_RANGE = 0
class-attribute
¶
The range query is in view range mode.
EDIT_RANGE = 1
class-attribute
¶
The range query is in edit range mode.
change_current_range(original: RangeQueryParameters, range_selector: typing.Callable[[Range], Range]) -> RangeQueryParameters
¶
Changes the given RangeQueryParameters into this RangeQueryMode
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
original |
RangeQueryParameters
|
The range query parameters to change the mode of. |
required |
range_selector |
typing.Callable[[Range], Range]
|
The range selector function. |
required |
Returns:
| Type | Description |
|---|---|
RangeQueryParameters
|
The new RangeQueryParameters |
Raises:
| Type | Description |
|---|---|
ArgumentError
|
this mode is invalid for the RangeQuery. |
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
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
create_default(session: InternalSession, tp: typing.Type[VT]) -> RangeQueryType[VT]
classmethod
¶
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 |
|---|---|
RangeQueryType[VT]
|
The according default Range Query object. |
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() -> 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() -> 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() -> 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() -> 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(range_selector: typing.Callable[[Range], Range]) -> QuerySelf
¶
Creates a copy of the current query with a modified range.
The range selector function.
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_(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
|
required |
Returns:
| Type | Description |
|---|---|
QuerySelf
|
The copy of this range query with a new anchor. |
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(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
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
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() -> 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(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 |
required |
Returns:
| Type | Description |
|---|---|
QuerySelf
|
The copy of this range query with a new span. |
See Also
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
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
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
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,
Operator type: span
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
|
required |
Returns:
| Type | Description |
|---|---|
QuerySelf
|
The copy of this range query with a new span. |
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
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
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.
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_(tp: typing.Type[VT]) -> RangeQueryType[VT]
¶
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]
|
The new value type. |
required |
Returns:
| Type | Description |
|---|---|
RangeQueryType[VT]
|
The copy of this range query with a new query value type. |
select_from(topic_path: pydantic.StrictStr) -> QueryResult[VT]
async
¶
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 |
IncompatibleTopicError
|
The value type
does not match the event data type of the time series topic bound to
|
InvalidQueryError
|
The range query is not valid for the time series. |
SessionSecurityError
|
The calling session does not have |
SessionClosedError
|
The calling session is closed. |
range_query_request
¶
query_result
¶
QueryResult
¶
Bases: typing.Generic[VT]
The query result providing a stream of events.
Since
6.9
selected_count: int
class-attribute
¶
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: StreamStructure = StreamStructure.VALUE_EVENT_STREAM
class-attribute
¶
The stream structure of the provided events.
events: typing.List[Event[VT]] = []
class-attribute
¶
The events as a list.
is_complete: bool
property
¶
Gets whether this result includes all events selected by the query.
Returns:
| Type | Description |
|---|---|
bool
|
|
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
otherhave an event with equal sequence numbers, the event fromotheris 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
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 |
range_query_result
¶
RangeQueryResult
¶
Bases: MarshalledModel
The range query result.
events: typing.Tuple[Event, ...]
class-attribute
¶
The collection of events.
selected_count: StrictNonNegativeInt
class-attribute
¶
The selected count.
value_data_type: typing.Type[diffusion.datatypes.AbstractDataType] = attr.field(converter=diffusion.datatypes.get)
class-attribute
¶
The value data type.
offsets: Offsets = Offsets()
class-attribute
¶
The initial offsets of this range query result
range_query_parameters
¶
StreamStructure
¶
QueryType
¶
Bases: enum.IntEnum
The range query type.
Since
6.1
VALUES = 0
class-attribute
¶
Original events in view range merged with latest edits in edit range.
ALL_EDITS = 1
class-attribute
¶
Original events in view range plus all edits in edit range.
LATEST_EDITS = 2
class-attribute
¶
Original events in view range plus latest event in edit range.
primary_operator: str
property
¶
Returns the primary operator of a given
edit_range_operator: str
property
¶
Returns:
| Type | Description |
|---|---|
str
|
The edit range operator of the given |
stream_structure: StreamStructure
property
¶
Returns the stream structure of a given
Returns:
| Type | Description |
|---|---|
StreamStructure
|
The stream structure of the given |
PointType
¶
Bases: enum.IntEnum
The point type.
Since
6.9
ABSOLUTE_START = 0
class-attribute
¶
The value is ignored.
ABSOLUTE_SEQUENCE = 1
class-attribute
¶
The value is a absolute sequence number.
ABSOLUTE_TIME = 2
class-attribute
¶
The value is a
OFFSET_SEQUENCE = 3
class-attribute
¶
The value is the number of terminal events of the series to skip.
OFFSET_TIME = 4
class-attribute
¶
The value is the terminal duration in milliseconds of the series to skip.
NEXT_COUNT = 5
class-attribute
¶
The value is a relative number of events after another point.
NEXT_TIME = 6
class-attribute
¶
The value is a duration in milliseconds after another point.
PREVIOUS_COUNT = 7
class-attribute
¶
The value is a relative number of events before another point.
PREVIOUS_TIME = 8
class-attribute
¶
The value is a duration in milliseconds before another point.
anchor_operator: typing.Optional[str]
property
¶
Returns the anchor operator for a given
Returns:
| Type | Description |
|---|---|
typing.Optional[str]
|
The anchor operator for the given |
span_operator: str
property
¶
Returns the span operator for this PointType
Returns:
| Type | Description |
|---|---|
str
|
The span operator. |
format_unit(value: int) -> str
¶
Returns the unit suffix for a given
Returns:
| Type | Description |
|---|---|
str
|
The unit suffix. |
validate(value: StrictNonNegativeInt) -> bool
¶
Validates a given
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value |
StrictNonNegativeInt
|
The value to validate. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
|
bool
|
Otherwise |
Point
¶
Bases: typing.NamedTuple
The query point for a range.
Since
6.9
value: StrictNonNegativeInt
class-attribute
¶
The value.
tp: PointType
class-attribute
¶
The point type.
is_absolute: bool
property
¶
Gets whether the current point is absolute or not.
Returns:
| Type | Description |
|---|---|
bool
|
Whether the current point is absolute. |
at_start()
classmethod
cached
¶
Returns a point representing an absolute sequence.
at(time: typing.Union[StrictNonNegativeInt, StrictTimedelta]) -> PointSelf
classmethod
¶
Returns a point representing an absolute time or sequence number.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time |
typing.Union[StrictNonNegativeInt, StrictTimedelta]
|
The absolute time (as a |
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The point representing an absolute time. |
offset(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> PointSelf
classmethod
¶
Returns a point representing a sequence offset from the end of the time series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
The sequence offset (as a non-negative |
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The point representing the offset from the end of the time series. |
offset_milliseconds(milliseconds: StrictNonNegativeInt) -> PointSelf
classmethod
¶
Returns a point representing a duration from the end of the time series.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The time span in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The point representing a duration from the end of the time series. |
next(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> PointSelf
classmethod
¶
Returns a relative point at
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 |
|---|---|
PointSelf
|
The relative point at |
next_milliseconds(milliseconds: StrictNonNegativeInt) -> PointSelf
classmethod
¶
Returns a relative point at
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The time span in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The relative point at |
previous(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> PointSelf
classmethod
¶
Returns a relative point at
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
|
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The relative point at |
previous_milliseconds(milliseconds: StrictNonNegativeInt) -> PointSelf
classmethod
¶
Returns the relative point at
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The time span in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
PointSelf
|
The relative point at |
anchor_description() -> str
¶
Returns:
| Type | Description |
|---|---|
str
|
the anchor description for the current |
span_description() -> str
¶
Returns the span description for the current
Returns:
| Type | Description |
|---|---|
str
|
The span description. |
Range
¶
Bases: object
The query range.
Since
6.9
anchor: Point = Point.at_start()
class-attribute
¶
The anchor point.
span: Point = Point.offset(0)
class-attribute
¶
The span point.
DEFAULT_RANGE() -> RangeSelf
classmethod
cached
¶
The default range with Point.at_start() as anchor and Point.offset(0) as span.
create(anchor: Point, span: Point) -> RangeSelf
classmethod
¶
from_start() -> Range
¶
from_(time: typing.Union[StrictNonNegativeInt, StrictTimedelta]) -> RangeSelf
¶
Copies the current Range with a new anchor point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time |
typing.Union[StrictNonNegativeInt, StrictTimedelta]
|
The sequence number (as a non-negative |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new anchor point. |
from_last(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> RangeSelf
¶
Copies the current Range with a new anchor point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
The offset (as a StrictNonNegativeInt) or a time (as a StrictNonNegativeTimedelta) |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new anchor point. |
from_last_milliseconds(milliseconds: StrictNonNegativeInt) -> RangeSelf
¶
Copies the current Range with a new anchor point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The time offset in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new anchor point. |
to_start() -> Range
¶
to(time: typing.Union[StrictNonNegativeInt, StrictTimedelta]) -> RangeSelf
¶
Create a copy of the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
time |
typing.Union[StrictNonNegativeInt, StrictTimedelta]
|
The absolute time (as a |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
until_last(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> RangeSelf
¶
Copies the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
The offset from the end of the time series as:
- time span (as a |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
until_last_milliseconds(milliseconds: StrictNonNegativeInt) -> RangeSelf
¶
Copies the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The time span offset in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
next(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> Range
¶
Copies the current Range with a new span point.
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 |
|---|---|
Range
|
The copy of the current Range with a new span point. |
next_milliseconds(milliseconds: StrictNonNegativeInt) -> RangeSelf
¶
Copies the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The next time span in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
previous(offset: typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]) -> RangeSelf
¶
Copies the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
offset |
typing.Union[StrictNonNegativeInt, StrictNonNegativeTimedelta]
|
|
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
previous_milliseconds(milliseconds: StrictNonNegativeInt) -> RangeSelf
¶
Copies the current Range with a new span point.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
milliseconds |
StrictNonNegativeInt
|
The previous time span in milliseconds. |
required |
Returns:
| Type | Description |
|---|---|
RangeSelf
|
The copy of the current Range with a new span point. |
RangeQueryParameters
¶
Bases: MarshalledModel
The range query parameters.
Since
6.9
query_type: QueryType = QueryType.VALUES
class-attribute
¶
The query type
view_range: Range = Range.DEFAULT_RANGE()
class-attribute
¶
The view range
edit_range: Range = Range.DEFAULT_RANGE()
class-attribute
¶
The edit range
is_historic_query
property
¶
Gets whether the current query parameters are a historic query or not.
with_view_range(range: Range) -> RQPSelf
¶
Creates a copy of the current
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
range |
Range
|
The new view range. |
required |
Returns:
| Type | Description |
|---|---|
RQPSelf
|
The copy of the current
RangeQueryParameters
with a new view |
with_query_type(type: QueryType) -> RQPSelf
¶
Creates a copy of the current
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
type |
QueryType
|
The new query type. |
required |
Returns:
| Type | Description |
|---|---|
RQPSelf
|
The copy of the current
RangeQueryParameters
with a new |