Package io.deephaven.engine.table.impl.select

Interface WhereFilter

All Superinterfaces:
ConcurrencyControl<Filter>, Expression, Filter
All Known Subinterfaces:
ReindexingFilter
All Known Implementing Classes:
AbstractConditionFilter, AbstractRangeFilter, AutoTuningIncrementalReleaseFilter, BaseIncrementalReleaseFilter, ByteRangeFilter, CharRangeFilter, ClockFilter, ComparableRangeFilter, ComposedFilter, ConditionFilter, ConjunctiveFilter, DisjunctiveFilter, DoubleRangeFilter, DownsampledWhereFilter, DynamicWhereFilter, FloatRangeFilter, IncrementalReleaseFilter, InstantRangeFilter, IntRangeFilter, LongRangeFilter, MatchFilter, RangeFilter, RollingReleaseFilter, ShortRangeFilter, SingleSidedComparableRangeFilter, SortedClockFilter, TimeSeriesFilter, UnsortedClockFilter, VectorComponentFilterWrapper, WhereAllFilter, WhereFilterDelegatingBase, WhereFilterImpl, WhereFilterInvertedImpl, WhereFilterLivenessArtifactImpl, WhereFilterSerialImpl, WhereFilterWithDeclaredBarriersImpl, WhereFilterWithRespectedBarriersImpl, WhereNoneFilter
public interface WhereFilter extends Filter
Interface for individual filters within a where clause.

  • Field Details

    • ZERO_LENGTH_WHERE_FILTER_ARRAY

      static final WhereFilter[] ZERO_LENGTH_WHERE_FILTER_ARRAY

  • Method Details

    • of

      static WhereFilter of(Filter filter)

    • from

      static WhereFilter[] from(Collection<? extends Filter> filters)

    • copyFrom

      static WhereFilter[] copyFrom(WhereFilter[] filters)

    • fromInternal

      @InternalUseOnly static WhereFilter[] fromInternal(Filter filter)

    • withDeclaredBarriers

      default WhereFilter withDeclaredBarriers(Object... declaredBarriers)
      Description copied from interface: ConcurrencyControl
      Designates the filter/selectable as declaring the specified barrier object(s).

      A barrier does not affect concurrency but imposes an ordering constraint for the filters or selectables that respect the same barrier. When a filter/selectable is marked as respecting a barrier object, it indicates that the respecting filter/selectable will be executed entirely after the filter/selectable declaring the barrier.

      Each barrier must be unique and declared by at most one filter. Object equals and Object.hashCode() hashCode will be used to determine uniqueness and identification of barrier objects.

      Specified by:
      withDeclaredBarriers in interface ConcurrencyControl<Filter>
      Specified by:
      withDeclaredBarriers in interface Filter
      Parameters:
      declaredBarriers - the unique barrier object identifiers
      Returns:
      a new instance of T with the declaredBarriers applied

    • withRespectedBarriers

      default WhereFilter withRespectedBarriers(Object... respectedBarriers)
      Description copied from interface: ConcurrencyControl
      Specifies that the filter/selectable should respect the ordering constraints of the given barriers.

      Filters that define a barrier (using ConcurrencyControl.withDeclaredBarriers(Object...)) will be executed entirely before filters/selectables that respect that barrier.

      It is an error to respect a barrier that has not already been defined per the natural left to right ordering of filters/selectables at the operation level. This is to minimize the risk of user error as the API is loosely typed.

      Object equals and Object.hashCode() hashCode will be used to identify which barriers are respected.

      Specified by:
      withRespectedBarriers in interface ConcurrencyControl<Filter>
      Specified by:
      withRespectedBarriers in interface Filter
      Parameters:
      respectedBarriers - the unique barrier object identifiers to respect
      Returns:
      a new instance of T with the respects barrier rule applied

    • withSerial

      default WhereFilter withSerial()
      Description copied from interface: ConcurrencyControl
      Applies serial concurrency control to the expression.

      The serial wrapped filter/selectable is guaranteed to process exactly the set of rows as if any prior filters/selectables were applied, but it will do so in a serial manner. If this is a filter, then the expression will not evaluate additional rows or skip rows that future filters may eliminate. Take care when selecting marking filters/selectables as serial, as the operation will not be able to take advantage of powerful optimizations.

      • Concurrency impact: The expression will never be invoked concurrently with itself.
      • Intra-expression ordering impact: Rows are evaluated sequentially in row set order.

      • Inter-expression ordering impact: For a filter, serial acts as an absolute reordering barrier, ensuring that no parts of a filter are executed out of order relative to this serial wrapper.

        For selectables, additional ordering constraints are controlled by the value of the QueryTable.SERIAL_SELECT_IMPLICIT_BARRIERS. This is set by the property QueryTable.serialSelectImplicitBarriers (defaulting to the value of QueryTable.statelessSelectByDefault).

        If QueryTable.SERIAL_SELECT_IMPLICIT_BARRIERS is false, then no additional ordering between selectable expressions is imposed. As with every select or update call, if column B references column A, then the necessary inputs from column A are evaluated before column B is evaluated. To impose further ordering constraints, use barriers.

        If QueryTable.SERIAL_SELECT_IMPLICIT_BARRIERS is true, then a serial selectable is an absolute barrier with respect to all other serial selectables. This prohibits serial selectables from being evaluated concurrently, permitting them to access global state. Selectables that are not serial may be reordered with respect to a serial selectable.

      Specified by:
      withSerial in interface ConcurrencyControl<Filter>
      Specified by:
      withSerial in interface Filter
      Returns:
      a new instance of T with serial concurrency control applied.

    • getColumns

      List<String> getColumns()
      Get the columns required by this select filter.

      This filter must already be initialized before calling this method.

      Returns:
      the columns used as input by this select filter.

    • getColumnArrays

      List<String> getColumnArrays()
      Get the array columns required by this select filter.

      This filter must already be initialized before calling this method.

      Returns:
      the columns used as array input by this select filter.

    • init

      void init(@NotNull @NotNull TableDefinition tableDefinition)
      Initialize this filter given the table definition. If this filter has already been initialized, this should be a no-op, or optionally validate that the table definition is compatible with previous initialization.
      Parameters:
      tableDefinition - the definition of the table that will be filtered
      ApiNote:
      Any QueryLibrary, QueryScope, or QueryCompiler usage needs to be resolved within init. Implementations must be idempotent.

    • init

      default void init(@NotNull @NotNull TableDefinition tableDefinition, @NotNull @NotNull QueryCompilerRequestProcessor compilationProcessor)
      Initialize this select filter given the table definition
      Parameters:
      tableDefinition - the definition of the table that will be filtered
      compilationProcessor - the processor to use for compilation
      ApiNote:
      Any QueryLibrary, QueryScope, or QueryCompiler usage needs to be resolved within init. Implementations must be idempotent.

    • beginOperation

      default SafeCloseable beginOperation(@NotNull @NotNull Table sourceTable)
      Perform any operation-level initialization necessary using the Table that will be filtered with this WhereFilter, e.g. gathering data indexes. This method will always be called exactly once, before gathering any dependencies or filtering data.
      Parameters:
      sourceTable - The Table that will be filtered with this WhereFilter
      Returns:
      A SafeCloseable that will be closed when the operation is complete, whether successful or not

    • validateSafeForRefresh

      default void validateSafeForRefresh(BaseTable<?> sourceTable)
      Validate that this WhereFilter is safe to use in the context of the provided sourceTable.
      Parameters:
      sourceTable - the source table

    • filter

      @NotNull @NotNull WritableRowSet filter(@NotNull @NotNull RowSet selection, @NotNull @NotNull RowSet fullSet, @NotNull @NotNull Table table, boolean usePrev)
      Filter selection to only matching rows.
      Parameters:
      selection - the indices that should be filtered. The selection must be a subset of fullSet, and may include rows that the engine determines need not be evaluated to produce the result. Implementations may not mutate or close selection.
      fullSet - the complete RowSet of the table to filter. The fullSet is used for calculating variables like "i" or "ii". Implementations may not mutate or close fullSet.
      table - the table to filter
      usePrev - true if previous values should be used. Implementing previous value filtering is optional, and a WhereFilter.PreviousFilteringNotSupported exception may be thrown. If a PreviousFiltering exception is thrown, then the caller must acquire the PeriodicUpdateGraph lock.
      Returns:
      The subset of selection accepted by this filter; ownership passes to the caller

    • filterInverse

      @NotNull default @NotNull WritableRowSet filterInverse(@NotNull @NotNull RowSet selection, @NotNull @NotNull RowSet fullSet, @NotNull @NotNull Table table, boolean usePrev)
      Filter selection to only non-matching rows.

      Defaults to 

       
 try (final WritableRowSet regular = filter(selection, fullSet, table, usePrev)) {
     return selection.minus(regular);
 }

      Implementations are encouraged to override this when they can provide more efficient implementations.

      Parameters:
      selection - the indices that should be filtered. The selection must be a subset of fullSet, and may include rows that the engine determines need not be evaluated to produce the result. Implementations may not mutate or close selection.
      fullSet - the complete RowSet of the table to filter. The fullSet is used for calculating variables like "i" or "ii". Implementations may not mutate or close fullSet.
      table - the table to filter
      usePrev - true if previous values should be used. Implementing previous value filtering is optional, and a WhereFilter.PreviousFilteringNotSupported exception may be thrown. If a PreviousFiltering exception is thrown, then the caller must acquire the PeriodicUpdateGraph lock.
      Returns:
      The subset of selection not accepted by this filter; ownership passes to the caller

    • filter

      @FinalDefault default WritableRowSet filter(RowSet selection, RowSet fullSet, Table table, boolean usePrev, boolean invert)
      Delegates to filter(RowSet, RowSet, Table, boolean) when invert == false and filterInverse(RowSet, RowSet, Table, boolean) when invert == true.
      Parameters:
      selection - the indices that should be filtered. The selection must be a subset of fullSet, and may include rows that the engine determines need not be evaluated to produce the result. Implementations may not mutate or close selection.
      fullSet - the complete RowSet of the table to filter. The fullSet is used for calculating variables like "i" or "ii". Implementations may not mutate or close fullSet.
      table - the table to filter
      usePrev - true if previous values should be used. Implementing previous value filtering is optional, and a WhereFilter.PreviousFilteringNotSupported exception may be thrown. If a PreviousFiltering exception is thrown, then the caller must acquire the PeriodicUpdateGraph lock.
      invert - if the filter should be inverted
      Returns:
      The subset of selection; ownership passes to the caller

    • isSimpleFilter

      boolean isSimpleFilter()
      Returns:
      true if this is a filter that does not require any code execution, but rather is handled entirely within the database engine.

    • isRefreshing

      default boolean isRefreshing()
      Is this filter refreshing?
      Returns:
      if this filter is refreshing

    • permitParallelization

      default boolean permitParallelization()
      Returns:
      if this filter can be applied in parallel

    • setRecomputeListener

      void setRecomputeListener(WhereFilter.RecomputeListener result)
      Set the WhereFilter.RecomputeListener that should be notified if results based on this WhereFilter must be recomputed.
      Parameters:
      result - The WhereFilter.RecomputeListener to notify

    • isAutomatedFilter

      boolean isAutomatedFilter()
      The database system may automatically generate a filter, for example, when applying an ACL to a table. There are certain operations which may bypass these filters.

      This function returns whether this filter is automated.

      Returns:
      true if this filter was automatically applied by the database system. False otherwise.

    • setAutomatedFilter

      void setAutomatedFilter(boolean value)
      The database system may automatically generate a filter, for example, when applying an ACL to a table. There are certain operations which may bypass these filters.

      This function indicates that this filter is automated.

      Parameters:
      value - true if this filter was automatically applied by the database system. False otherwise.

    • canMemoize

      default boolean canMemoize()
      Can this filter operation be memoized?
      Returns:
      if this filter can be memoized

    • hasVirtualRowVariables

      default boolean hasVirtualRowVariables()
      Returns true if this filter uses row virtual offset columns of i, ii or k.

    • copy

      WhereFilter copy()
      Create a copy of this WhereFilter.
      Returns:
      an independent copy of this WhereFilter.

    • invert

      default Filter invert()
      Description copied from interface: Filter
      The logical inversion of this. While logically equivalent to Filter.not(this), implementations of this method will return more specifically typed inversions where applicable.
      Specified by:
      invert in interface Filter
      Returns:
      the inverse filter
      See Also:

    • walk

      default <T> T walk(Expression.Visitor<T> visitor)
      Specified by:
      walk in interface Expression

    • walk

      default <T> T walk(Filter.Visitor<T> visitor)
      Specified by:
      walk in interface Filter

    • walk

      default <T> T walk(WhereFilter.Visitor<T> visitor)
      This method calls the appropriate visitor method based on the type of this WhereFilter. This will invoke the most specific WhereFilter.Visitor method available.
      Type Parameters:
      T - the return value type
      Parameters:
      visitor - the visitor
      Returns:
      the value