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
const allEntries = await session
    .timeSeriesFor("users/john", "HeartRates")
    .get();

Get range of entries:

In this example, we query for a document and get a range of entries from its "Heartrate" time series.

// Query for a document
const user = await session.query({ collection: "users" })
    .whereEquals("name", "John")
    .first();

const from = new Date();
const to = new Date(baseTime.getTime() + 60_000 * 5);

// Retrieve a range of 6 entries
const tsEntries = await session
    .timeSeriesFor(user, "HeartRates")
    .get(from, to);

Get entries with multiple values:

• Here, we check if a stock's closing price is rising consecutively 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.

let goingUp = false;

const allEntries = await session
    .timeSeriesFor("users/john", "StockPrices")
    .get();
    
const closePriceDay1 = allEntries[0].values[1];
const closePriceDay2 = allEntries[1].values[1];
const closePriceDay3 = allEntries[2].values[1];

// Check if the stock's closing price is rising
if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) {
        goingUp = true;
}

let goingUp = false;

const allEntries = await session
    .timeSeriesFor("users/john", "StockPrices")
    .get();

// Call 'asTypedEntry' to be able to access the entry's values by their names
// Pass the class type (StockPrice)
const typedEntry1 = allEntries[0].asTypedEntry(StockPrice);

// Access the entry value by its StockPrice class property name (close)
const closePriceDay1 = typedEntry1.value.close;

const typedEntry2 = allEntries[1].asTypedEntry(StockPrice);
const closePriceDay2 = typedEntry2.value.close;

const typedEntry3 = allEntries[2].asTypedEntry(StockPrice);
const closePriceDay3 = typedEntry3.value.close;

// Check if the stock's closing price is rising
if ((closePriceDay2 > closePriceDay1) && (closePriceDay3 > closePriceDay2)) {
    goingUp = true;
}

• 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:

const allEntries = await session
    .timeSeriesFor("users/john", "HeartRates")
     // Get all entries
    .get(null, null, builder => builder
        .includeDocument() // include the parent document
        .includeTags());   // include documents referenced in the entries tags
    
// The following 'load' call will not trigger a server request
const user = await session.load("users/john");

// Available overloads:
// ====================

get(); // Get all entries

get(from, to);
get(from, to, start);

get(start, pageSize);
get(from, to, start, pageSize);

get(from, to, includes);
get(from, to, includes, start);
get(from, to, includes, start, pageSize);

class TimeSeriesEntry {
    // The entry's time stamp
    timestamp; // Date
    
    // The entry's tag, can contain a related document ID
    tag; // string
    
    // List of up to 32 values for this entry
    values; // number[]
    
    // Is this an entry that belongs to a "rollup" time series
    isRollup; // boolean
    
    // Nodes info for incremental time series
    nodeValues; // Record<string, number[]>;
    
    // A method that returns the entry as a typed entry (TypedTimeSeriesEntry)
    asTypedEntry(clazz); // 'clazz' designates the type for the value  
}

class TypedTimeSeriesEntry {
    timestamp; // Date
    tag;       // string
    values;    // number[]
    isRollup;  // boolean
    
    // Access the value of a typed entry as an object
    value;     // object of type clazz
}