Get Time Series Entries

• Open a session.
• Create an instance of timeSeriesFor 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 timeSeriesFor.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
/** @var TimeSeriesEntryArray $val */
$val = $session->timeSeriesFor("users/john", "HeartRates")
    ->get();

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
$session = $store->openSession();
try {
     $baseTime = DateUtils::today();

    $query = $session->query(User::class)
        ->whereEquals("Name", "John");

    $result = $query->toList();

    /** @var TimeSeriesEntryArray $val */
    $val = $session->timeSeriesFor($result[0], "HeartRates")
        ->get();

    $session->saveChanges();
} finally {
    $session->close();
}

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.

$goingUp = false;

$session = $store->openSession();
try {
    // Call 'Get' with the custom StockPrice class type
    /** @var TimeSeriesEntryArray<StockPrice> $val */
    $val = $session->typedTimeSeriesFor(StockPrice::class, "users/john")
        ->get();

    $closePriceDay1 = $val[0]->getValue()->getClose();
    $closePriceDay2 = $val[1]->getValue()->getClose();
    $closePriceDay3 = $val[2]->getValue()->getClose();

    if (($closePriceDay2 > $closePriceDay1)
        &&
        ($closePriceDay3 > $closePriceDay2))
        $goingUp = true;
} finally {
    $session->close();
}

• When retrieving time series entries using timeSeriesFor.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
/** @var TimeSeriesEntryArray $entries */
$entries =
    $session->timeSeriesFor("users/john", "HeartRates")
        ->get(null, null,
            includes: function($builder) {
                return $builder
                    // Include documents referred-to by entry tags
                    ->includeTags()
                    // Include Parent Document
                    ->includeDocument();
            });

public function get(?DateTimeInterface $from = null, ?DateTimeInterface $to = null, ?Closure $includes = null, int $start = 0, int $pageSize = PHP_INT_MAX): ?TimeSeriesEntryArray;

// The stongly-typed API is used, to address time series values by name.

/**
 * Return the time series values for the provided range
 *
 * @param DateTimeInterface|null $from
 * @param DateTimeInterface|null $to
 * @param int $start
 * @param int $pageSize
 * @return TypedTimeSeriesEntryArray|null
 */
public function get(?DateTimeInterface $from = null, ?DateTimeInterface $to = null, int $start = 0, int $pageSize = PHP_INT_MAX): ?TypedTimeSeriesEntryArray;

Return Values (Optional)

• ?TimeSeriesEntryArray - an array of time series entry classes.

  class TimeSeriesEntry
  {
      private ?DateTime $timestamp = null;
      private ?string $tag = null;
      private ?array $values = null;
      private bool $rollup = false;
  
      private ?array $nodeValues = null; // Map<String, Double[]>
  
  
      //..
  }