Get Time Series Entries

• Open a session.
• Create an instance of time_series_for and pass it the following:
  • Provide an explicit document ID, -or-
    pass an entity tracked by the session, e.g. a document object returned from session.query or from session.load.
  • Specify the time series name.
• Call time_series_for.get.

Get all entries:

In this example, we retrieve all entries of the "Heartrate" time series.
The ID of the parent document is explicitly specified.

# Get all time series entries
val = session.time_series_for("users/john", "HeartRates").get(datetime.min, datetime.max)

Get range of entries:

In this example, we query for a document and get its "Heartrate" time series data.

# Query for a document with the Name property "John"
# and get its HeartRates time-series values
with store.open_session() as session:
    base_line = datetime.utcnow()

    query = session.query(object_type=User).where_equals("Name", "John")

    result = list(query)

    doc_id = session.advanced.get_document_id(result[0])

    val = session.time_series_for(doc_id, "HeartRates").get(datetime.min, datetime.max)

    session.save_changes()

Get entries with multiple values:

• Here, we check whether a stock's closing-time price is rising from day to day (over three days).
  This example is based on the sample entries that were entered in this example.

• Since each time series entry contains multiple StockPrice values, we include a sample that uses named time series values to make the code easier to read.

going_up = False

# Use Get with a Named type
with store.open_session() as session:
    val = session.typed_time_series_for(StockPrice, "users/john").get()

    close_price_day_1 = val[0].value.close
    close_price_day_2 = val[1].value.close
    close_price_day_3 = val[2].value.close
    if close_price_day_2 > close_price_day_1 and close_price_day_3 > close_price_day_2:
        going_up = True

• When retrieving time series entries using time_series_for.get,
  you can include the series parent document and/or documents referred to by the entries tags.

• The included documents will be cached in the session, and instantly retrieved from memory if loaded by the user.

• Use the following syntax to include the parent or tagged documents:

# Get all time series entries
entries = session.time_series_for("users/john", "HeartRates").get_with_include(
    datetime.min,
    datetime.max,
    lambda builder: builder
    # Include documents referred-to by entry tags
    .include_tags()
    # Include Parent Document
    .include_document(),
)

def get(
    self,
    from_date: Optional[datetime] = None,
    to_date: Optional[datetime] = None,
    start: int = 0,
    page_size: int = int_max,
) -> Optional[List[TimeSeriesEntry]]: ...

# The strongly-typed API is used, to address time series values by name.
def get(
    self,
    from_date: Optional[datetime] = None,
    to_date: Optional[datetime] = None,
    start: int = 0,
    page_size: int = int_max,
) -> Optional[List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]]]: ...

Return Values (Optional)

• List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]] - an array of time series entry classes.

  class TimeSeriesEntry:
      def __init__(self, timestamp: datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None):
          self.timestamp = timestamp
          self.tag = tag
          self.values = values
          self.rollup = rollup
  
      @property
      def value(self):
          if len(self.values) == 1:
              return self.values[0]
          raise ValueError("Entry has more than one value.")
  
      @value.setter
      def value(self, value: int):
          if len(self.values) == 1:
              self.values[0] = value
              return
          raise ValueError("Entry has more than one value")

• TimeSeriesEntry<TValues>[] - Time series values that can be referred to by name.