Querying Time Series Indexes

• The following is a time series map-index that will be used in the query examples throughout this article.

• Each index-entry consists of:

  • Three index-fields obtained from the "HeartRates" time series entries: bpm, date, and tag.
  • One index-field obtained from the time series segment header: employeeID.
  • One index-field obtained from the loaded employee document: employeeName.

• When querying this time series index:

  • The resulting items correspond to the time series entries that match the query predicate.
  • Each item in the results will in the shape of the defined index-entry.
    Different result types may be returned when the query projects the results.

class TsIndex extends AbstractRawJavaScriptTimeSeriesIndexCreationTask {
    constructor() {
        super();

        this.maps.add(`
            timeSeries.map("Employees", "HeartRates", function (segment) {
                 let employee = load(segment.DocumentId, "Employees")
                 
                 // Return the index-entry:
                 return segment.Entries.map(entry => ({
                 
                     // Define the index-fields:
                     bpm: entry.Values[0],
                     date: new Date(entry.Timestamp),
                     tag: entry.Tag
                     employeeID: segment.DocumentId,
                     employeeName: employee.FirstName + " " + employee.LastName
                 }));
            })
        `;
    }
}

Query all time series entries:

No filtering is applied in this query.
Results will include ALL entries from time series "HeartRates".

const results = await session
     // Query the index 
    .query({ indexName: "TsIndex" })
     // Query for all entries w/o any filtering
    .all();

// Access results:
const entryResult = results[0];
const employeeName = entryResult.employeeName;
const bpm = entryResult.bpm;

const results = await session
     // Provide RQL to rawQuery
    .advanced.rawQuery("from index 'TsIndex'")
     // Execute the query
    .all();

from index "TsIndex"

Filter query results:

In this example, time series entries are filtered by the query.
The query predicate is applied to the index-fields.

const results = await session
    .query({ indexName: "TsIndex" })
     // Retrieve only time series entries with high BPM values for a specific employee
    .whereEquals("employeeName", "Robert King")
    .whereGreaterThanOrEqual("bpm", 85)
    .all();

const results = await session
     // Retrieve only time series entries with high BPM values for a specific employee
    .advanced.rawQuery(`
         from index "TsIndex"
         where employeeName == "Robert King" and bpm > 85.0
    `)
    .all();

from index "TsIndex"
where employeeName == "Robert King" and bpm >= 85

Order query results:

Results can be ordered by any of the index-fields.

const results = await session
    .query({ indexName: "TsIndex" })
     // Retrieve time series entries where employees had a low BPM value
    .whereLessThan("bpm", 58)
     // Order by the 'date' index-field (descending order)
    .orderByDescending("date")
    .all();

const results = await session
     // Retrieve entries with low BPM value and order by 'date' descending
    .advanced.rawQuery(`
          from index "TsIndex"
          where bpm < 58
          order by date desc
    `)
    .all();

from index "TsIndex"
where bpm < 58
order by date desc

Project results:

• Instead of returning the entire index entry object for each result item,
  you can return only partial fields.

• Learn more about projecting query results in Project Index Query Results.

• In this example, we query for time series entries with a very high BPM value.
  We retrieve entries with BPM value > 100 but return only the employeeID for each entry.

const results = await session
    .query({ indexName: "TsIndex" })
    .whereGreaterThanOrEqual("bpm", 100)
     // Return only the employeeID index-field in the results
    .selectFields(["employeeID"])
     // Optionally: call 'distinct' to remove duplicates from results
    .distinct()
    .all();

const results = await session
     // Return only the employeeID index-field in the results
    .advanced.rawQuery(`
         from index "TsIndex"
         where bpm >= 100
         select distinct employeeID
    `)
    .all();

from index "TsIndex"
where bpm > 100
select distinct employeeID