see on GitHub

Querying: Using Indexes


  • Time series indexes are not generated automatically by the server, but static indexes can be created by clients or using the Studio. As any other index, static time series indexes can be queried.

  • Querying a time series index projects the contents of fields specified in the index' select clause. The result-set can then be further filtered using LINQ expressions.

  • In this page:


Query Using Indexes

You can query time series indexes using session.Query and session.Advanced.DocumentQuery, and enhance the queries using LINQ expressions.

Syntax

  • Definitions

    • session.Query
      IRavenQueryable<T> Query<T, TIndexCreator>() where TIndexCreator 
           : AbstractCommonApiForIndexes, new();
    • DocumentQuery
      IDocumentQuery<T> DocumentQuery<T, TIndexCreator>() where TIndexCreator 
           : AbstractCommonApiForIndexes, new();
  • Parameters

    Parameters Description
    T Results Container
    TIndexCreator Index
  • Return Values

    As return values are specific to each index, we need to define a matching results container.

    In the following sample we define a map index that collects three fields from the "HeartRate" time series, a "Results" container for the results, and an index query that uses both.

    public class SimpleIndex : AbstractTimeSeriesIndexCreationTask<Employee>
    {
    
        public class Result
        {
            public double HeartBeat { get; set; }
            public DateTime Date { get; set; }
            public string User { get; set; }
            public string Tag { get; set; }
        }
    
        public SimpleIndex()
        {
            AddMap(
                "HeartRates",
                timeSeries => from ts in timeSeries
                              from entry in ts.Entries
                              select new
                              {
                                  HeartBeat =
                                    entry.Values[0],
                                  entry.Timestamp.Date,
                                  User = ts.DocumentId,
                                  Tag = entry.Tag
                              });
        }
    }
    // Query time-series index using session.Query
    using (var session = store.OpenSession())
    {
        List<SimpleIndex.Result> results = 
            session.Query<SimpleIndex.Result, SimpleIndex>()
            .ToList();
    }

Usage Samples

  • Querying an Index
    To query a time series index, call session.Query or session.Advanced.DocumentQuery.

    // Query time-series index using session.Query
    using (var session = store.OpenSession())
    {
        List<SimpleIndex.Result> results = 
            session.Query<SimpleIndex.Result, SimpleIndex>()
            .ToList();
    }
    // Query time-series index using DocumentQuery
    using (var session = store.OpenSession())
    {
        List<SimpleIndex.Result> results = 
            session.Advanced.DocumentQuery<SimpleIndex.Result, SimpleIndex>()
            .ToList();
    }
  • Enhancing Index Queries

    • When you call session.Query, You can add LINQ expressions to your query.

      // Enhance the query using LINQ expressions
      var chosenDate = new DateTime(2020, 5, 20);
      using (var session = store.OpenSession())
      {
          List<SimpleIndex.Result> results = 
              session.Query<SimpleIndex.Result, SimpleIndex>()
              .Where(w => w.Date < chosenDate)
              .OrderBy(o => o.HeartBeat)
              .ToList();
      }
    • You can add LINQ-like expressions to a DocumentQuery as well.

      // Query time-series index using DocumentQuery with Linq-like expressions
      using (var session = store.OpenSession())
      {
          List<SimpleIndex.Result> results = 
              session.Advanced.DocumentQuery<SimpleIndex.Result, SimpleIndex>()
              .WhereEquals("Tag", "watches/fitbit")
              .ToList();
      }
  • Async queries
    You can run asynchronous queries as well.

    // Time-series async index query using session.Query
    using (var session = store.OpenAsyncSession())
    {
        List<SimpleIndex.Result> results = 
            await session.Query<SimpleIndex.Result, SimpleIndex>()
            .ToListAsync();
    }