Implemented staged and temporal query support. (#6)

Implemented structures and convenience methods for staged and temporal queries.

Runtime/Vitrivr/UnityInterface/CineastApi/CineastWrapper.cs

@@ -37,6 +37,7 @@ public static async Task<QueryResponse> ExecuteQuery(SimilarityQuery query, int
     {
       var queryResults = await SegmentsApi.FindSegmentSimilarAsync(query);
 
+      // TODO: max results should be specified in the respective query config
       var querySegments = ResultUtils.ToSegmentData(queryResults, maxResults);
 
       var queryData = new QueryResponse(query, querySegments);
@@ -48,6 +49,41 @@ public static async Task<QueryResponse> ExecuteQuery(SimilarityQuery query, int
       return queryData;
     }
 
+    /// <summary>
+    /// Executes a staged query.
+    /// </summary>
+    public static async Task<QueryResponse> ExecuteQuery(StagedSimilarityQuery query, int maxResults, int prefetch)
+    {
+      var queryResults = await SegmentsApi.FindSegmentSimilarStagedAsync(query);
+
+      // TODO: max results should be specified in the respective query config
+      var querySegments = ResultUtils.ToSegmentData(queryResults, maxResults);
+
+      var queryData = new QueryResponse(query, querySegments);
+      if (prefetch > 0)
+      {
+        await queryData.Prefetch(prefetch);
+      }
+
+      return queryData;
+    }
+
+    /// <summary>
+    /// Executes a temporal query.
+    /// </summary>
+    public static async Task<TemporalQueryResponse> ExecuteQuery(TemporalQuery query, int prefetch)
+    {
+      var queryResults = await SegmentsApi.FindSegmentSimilarTemporalAsync(query);
+
+      var queryData = new TemporalQueryResponse(query, queryResults);
+      if (prefetch > 0)
+      {
+        await queryData.Prefetch(prefetch);
+      }
+
+      return queryData;
+    }
+
     /// <summary>
     /// Retrieves the unordered list of tags with names matching get given name.
     /// </summary>
@@ -81,7 +117,7 @@ public async Task<SimilarityQueryResultBatch> RequestThreaded(SimilarityQuery qu
     /// <returns>List of distinct values occuring in the specified column of the specified table</returns>
     public static async Task<List<string>> GetDistinctTableValues(string table, string column)
     {
-      var columnSpec = new ColumnSpecification(column, table); 
+      var columnSpec = new ColumnSpecification(column, table);
       var results = await Task.Run(() => MiscApi.FindDistinctElementsByColumn(columnSpec));
       return results.DistinctElements;
     }

Runtime/Vitrivr/UnityInterface/CineastApi/Model/Data/QueryResponse.cs

@@ -2,6 +2,7 @@
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
+using JetBrains.Annotations;
 using Org.Vitrivr.CineastApi.Model;
 using Vitrivr.UnityInterface.CineastApi.Model.Registries;
 using Vitrivr.UnityInterface.CineastApi.Utils;
@@ -17,20 +18,28 @@ public class QueryResponse
     /// <summary>
     /// The executed query leading to the stored results.
     /// </summary>
-    public readonly SimilarityQuery query;
+    [CanBeNull] public readonly SimilarityQuery Query;
+
+    [CanBeNull] public readonly StagedSimilarityQuery StagedQuery;
 
     /// <summary>
     /// Dictionary of result lists by result category.
     /// </summary>
-    public readonly Dictionary<string, List<ScoredSegment>> results;
+    public readonly Dictionary<string, List<ScoredSegment>> Results;
 
 
     /// <param name="query">Query to store data for</param>
     /// <param name="results">Dictionary of results by result category</param>
     public QueryResponse(SimilarityQuery query, Dictionary<string, List<ScoredSegment>> results)
     {
-      this.query = query;
-      this.results = results;
+      Query = query;
+      Results = results;
+    }
+
+    public QueryResponse(StagedSimilarityQuery query, Dictionary<string, List<ScoredSegment>> results)
+    {
+      StagedQuery = query;
+      Results = results;
     }
 
     /// <summary>
@@ -41,7 +50,7 @@ public async Task Prefetch(int number)
     {
       // TODO: Prevent more than the number of segments to be prefetched in total
       var segmentSet = new HashSet<SegmentData>();
-      foreach (var segmentList in results.Values)
+      foreach (var segmentList in Results.Values)
       {
         segmentList.Take(number).Select(item => item.segment).ToList().ForEach(segment => segmentSet.Add(segment));
       }
@@ -51,7 +60,7 @@ public async Task Prefetch(int number)
 
     public List<ScoredSegment> GetMeanFusionResults()
     {
-      return ResultUtils.MeanScoreFusion(results);
+      return ResultUtils.MeanScoreFusion(Results);
     }
   }
 }

Runtime/Vitrivr/UnityInterface/CineastApi/Model/Data/TemporalQueryResponse.cs

@@ -0,0 +1,29 @@
+using System.Linq;
+using System.Threading.Tasks;
+using Org.Vitrivr.CineastApi.Model;
+using Vitrivr.UnityInterface.CineastApi.Model.Registries;
+
+namespace Vitrivr.UnityInterface.CineastApi.Model.Data
+{
+  public class TemporalQueryResponse
+  {
+    public readonly TemporalQuery Query;
+    public readonly TemporalQueryResult Results;
+
+    public TemporalQueryResponse(TemporalQuery query, TemporalQueryResult results)
+    {
+      Query = query;
+      Results = results;
+    }
+
+    public async Task Prefetch(int number)
+    {
+      var segmentSet = Results.Content.Take(number)
+        .SelectMany(result => result.Segments
+          .Select(SegmentRegistry.GetSegment)
+        ).ToHashSet();
+
+      await SegmentRegistry.BatchFetchSegmentData(segmentSet.ToList());
+    }
+  }
+}

Runtime/Vitrivr/UnityInterface/CineastApi/Utils/QueryBuilder.cs

@@ -5,17 +5,36 @@
 
 namespace Vitrivr.UnityInterface.CineastApi.Utils
 {
-  public class QueryBuilder
+  public static class QueryBuilder
   {
     /// <summary>
     /// Generic similarity query for given terms
     /// </summary>
-    /// <param name="terms"></param>
+    /// <param name="terms">Terms to use for query.</param>
     public static SimilarityQuery BuildSimilarityQuery(params QueryTerm[] terms)
     {
       return new SimilarityQuery(terms.ToList());
     }
 
+    /// <summary>
+    /// Staged similarity query for the given stages.
+    /// </summary>
+    /// <param name="stages">Enumerable of stages, each containing the respective <see cref="QueryTerm"/>s.</param>
+    public static StagedSimilarityQuery BuildStagedQuery(IEnumerable<List<QueryTerm>> stages)
+    {
+      return new StagedSimilarityQuery(stages.Select(terms => new QueryStage(terms)).ToList());
+    }
+
+    /// <summary>
+    /// Temporal similarity query for the given staged temporal contexts.
+    /// </summary>
+    /// <param name="temporalContexts">Enumerable of temporally ordered enumerables containing stages, containing <see cref="QueryTerm"/>s.</param>
+    /// <returns></returns>
+    public static TemporalQuery BuildTemporalQuery(IEnumerable<IEnumerable<List<QueryTerm>>> temporalContexts)
+    {
+      return new TemporalQuery(temporalContexts.Select(BuildStagedQuery).ToList());
+    }
+
     /// <summary>
     /// Convenience method to create spatial similarity query
     /// </summary>