Operations: Get Incremental Time Series



GetTimeSeriesOperation

Use GetTimeSeriesOperation to retrieve the distinct values stored per-node for the requested entries.


Syntax

  • Definition

    public GetTimeSeriesOperation(
        string docId, string timeseries, DateTime? @from = null,
        DateTime? to = null, int start = 0, int pageSize = int.MaxValue, 
        bool returnFullResults = false)
  • Parameters

    Parameters Type Description
    docId string Document ID
    timeseries string Time series name
    from (optional) DateTime? Range start
    Default: DateTime.Min
    to (optional) DateTime? Range end
    Default: DateTime.Max
    start int Start of first Page
    pageSize int Size of each page
    returnFullResults bool If true, retrieve the values stored per-node.
    If false, return null in TimeSeriesEntry.NodeValues.
  • Return Value: TimeSeriesRangeResult<TimeSeriesEntry>

    public class TimeSeriesRangeResult 
        {
            public DateTime From, To;
            public TimeSeriesEntry[] Entries;
            
            // The actual number of values
            public long? TotalResults; 
            
            // Helps to calculate next start
            public int? SkippedResults;
    public class TimeSeriesEntry 
        {
            public DateTime Timestamp { get; set; }
            public double[] Values { get; set; }
            public string Tag { get; set; }
            public bool IsRollup { get; set; }
            
            // The nodes distribution per each entry
            public Dictionary<string, double[]> NodeValues { get; set; }
    • Requesting a time series that doesn't exist will return null.
    • Requesting an entries range that doesn't exist will return a TimeSeriesRangeResult object with an empty Entries property.
  • Exceptions
    Exceptions are not generated.


Usage Flow

  • Pass GetTimeSeriesOperation -
    • Document ID
    • Incremental Time Series Name
    • Range Start
    • Range End.
    • 0 as the value of start, if you want to start with the first entry.
    • the number of results you want to retrieve, as the value of pageSize.
    • true as the value of returnFullResults, if you want to retrieve node values from time series entries.
  • Call store.Operations.Send to execute the operation.
  • Entries are returned into a dictionary of TimeSeriesRangeResult classes.
  • Calculate where the next Get operation needs to start.

    To calculate where the next page should start:

    • The value you set in pageSize indicates the location of the first entry to retrieve.
    • More than one entry can exist for the same timestamp since when different nodes increment a value for the same timestamp, the entries stored on those nodes will have the same timestamp, resulting in 'duplicate' entries.
    • The number of these duplicated entries is returned in the SkippedResults
    • To find where the next page starts, add (see code sample below):
      • Your current starting point
      • The returned Entries.Length
      • The returned SkippedResults
  • Run the next Get operation with your calculation result as its start entry.

  • Usage Sample

    • In this sample we retrieve 50 entries from an incremental time series that contains two per-node values in each entry.
      We then calculate where the next Get operation should start, and run another Get operation starting there.
      var pageSize = 100;
      var entries = store.Operations
                        .Send(new GetTimeSeriesOperation("users/ayende",
                         "INC:Downloads", start: 0, pageSize: pageSize / 2, 
                         returnFullResults: true));
      
      // we get 50 unique entries but we read 100 entries from the segment
      // so next call we should start from position 101: numberOfUniqueEntries + skippedResults 
      var nextStart = entries.Entries.Length + entries.SkippedResults;
      
      entries = store.Operations
                        .Send(new GetTimeSeriesOperation("users/ayende",
                         "INC:Downloads", start: (int)nextStart,
                         pageSize: pageSize / 2, returnFullResults: true));

    GetMultipleTimeSeriesOperation

    Use GetMultipleTimeSeriesOperation to retrieve data from multiple time series.