Interface QueryEngine

All Known Implementing Classes:
AbstractQueryEngine

public interface QueryEngine
Reads historical data for a historian: browsing, raw, aggregated and complex point queries, plus the capabilities and node metadata the query pipeline uses. Query methods deliver results to a processor rather than returning them.
  • Method Details

    • browse

      void browse(QualifiedPath root, BrowseFilter filter, BrowsePublisher publisher)
      Browses the tree under root, applying filter and passing results to publisher.
      Parameters:
      root - the path to browse from.
      filter - the criteria for filtering results.
      publisher - receives the results.
    • query

      void query(RawQueryOptions options, RawPointProcessor processor)
      Runs a raw query, passing the points to processor.
      Parameters:
      options - the paths, time range and other query settings.
      processor - receives the points.
    • query

      default void query(AggregatedQueryOptions options, AggregatedPointProcessor processor, NativeQueryContext context)
      Runs an aggregated query, passing the points to processor. Unsupported by default.

      Each native key arrives with its EngineDirective in context: gap policy, edges and shape, never the key's interpolation or fill word. For a key fillsWindowsNatively(AggregatedQueryKey, EngineDirective) accepts, the engine fills the windows, and the ones it leaves empty stay empty.

      Parameters:
      options - the time window, paths and other query settings.
      processor - receives the points.
      context - the pipeline's directives and live post bounds; NativeQueryContext.NONE for a direct call.
    • query

      default <P extends ComplexPoint<?>, K extends ComplexQueryKey<?>> void query(ComplexQueryOptions<K> options, ComplexPointProcessor<P,K> processor)
      Runs a complex point query, passing the results to processor. Unsupported by default.
      Type Parameters:
      P - the complex point type.
      K - the complex query key type.
      Parameters:
      options - the query settings.
      processor - receives the results.
    • nativeAggregates

      default Collection<? extends AggregationType> nativeAggregates()
      Returns the aggregates this engine computes, each once. A StandardAggregates entry declared by reference is computed under the platform's semantics; any other id is the engine's own and is never folded by the gateway. The gateway computes every standard aggregate the engine leaves out. Empty by default; checked at registration.
    • capabilities

      default EngineCapabilities capabilities()
      Describes what this engine supports, which drives option filtering in the Designer. The default is minimal; engines should override it. Must return an immutable value.
    • lookupNode

      default Optional<? extends HistoricalNode> lookupNode(QualifiedPath source, @Nullable TimeRange range)
      Resolves the node that describes source during range. The query pipeline calls this once per key to choose aggregates by data type and fill behavior by interpolation mode.

      A node has multiple versions over time, so return the version active at TimeRange.endTime(), or the latest historized version if none covers the range. Consult the in-memory node tree first and fall back to stored column metadata for retired tags. Returning empty is always safe; the pipeline then assumes DataType.Float8.

      Parameters:
      source - the source path being queried; never null.
      range - the query's time range, to pick among node versions; may be null.
      Returns:
      the node, or empty if the engine has no record of source.
    • lookupNodes

      default Map<QualifiedPath, ? extends HistoricalNode> lookupNodes(Set<QualifiedPath> sources, @Nullable TimeRange range)
      Resolves several nodes at once, equivalent to lookupNode(QualifiedPath, TimeRange) per source. Override to answer in one round trip.
      Parameters:
      sources - the source paths to resolve; never null.
      range - the query's time range, to pick among node versions; may be null.
      Returns:
      an unmodifiable map keyed by the caller's QualifiedPath instances; unmatched sources are absent, never mapped to null.
    • deliveredValueType

      default DataType deliveredValueType(DataType declaredType)
      Returns the type of values this engine delivers for a node declared as declaredType. Engines that widen on storage, such as every integral type into one long column, must report the widened type.
      Parameters:
      declaredType - the tag's configured data type.
      Returns:
      the delivered type; the declared type by default.
    • fillsWindowsNatively

      default boolean fillsWindowsNatively(AggregatedQueryKey key, EngineDirective directive)
      Returns whether this engine fills key's empty windows itself under directive's gap policy, marking each filled cell Interpolated; the gateway then fills none of them. false by default.
    • aggregateLattice

      default Optional<AggregateLattice> aggregateLattice()
      Returns the cell grid of this engine's pre-aggregated tier, if it has one. The pipeline snaps consenting queries onto it and reads any bounding values on the snapped grid. Empty by default.
    • boundsInline

      default boolean boundsInline(AggregatedQueryKey key)
      Returns whether this engine renders key's bounding values itself when the query asks for them. Consulted only for an engine declaring EngineCapabilities.QueryCapability.BOUNDING_VALUES; for a key answered false, the platform reads the boundary samples on the snapped grid. An inline bound is the nearest sample with a value at a level the query admits. true by default.