Package org.elasticsearch.xpack.esql.datasources.spi

Interface FilterPushdownSupport

public interface FilterPushdownSupport

SPI interface for filter pushdown support in external data sources.

Inspired by Lucene's translatable() pattern and Spark's SupportsPushDownFilters, this interface allows data sources to indicate which ESQL filter expressions they can handle natively, enabling efficient predicate pushdown.

The pushdown flow works as follows:

1. The optimizer calls pushFilters(List) with AND-separated filter expressions
2. The implementation converts supported expressions to source-specific filters
3. The result contains an opaque pushed filter and any remainder expressions
4. The pushed filter is stored in the physical plan node (opaque to core)
5. During execution, the operator factory retrieves and applies the pushed filter

Since external sources execute on the coordinator only (ExecutesOn.Coordinator), the pushed filter is never serialized - it's created during local physical optimization and consumed immediately by the operator factory in the same JVM.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static enum	FilterPushdownSupport.Pushability	Indicates whether an expression can be pushed to the data source.
static final record	FilterPushdownSupport.PushdownResult	Result of attempting to push filters to a data source.

Method Summary

Modifier and Type	Method	Description
default FilterPushdownSupport.Pushability	canPush(Expression expr)	Check if a single expression can be pushed to the source.
FilterPushdownSupport.PushdownResult	pushFilters(List<Expression> filters)	Attempt to push filters to the source.

Method Details

pushFilters

FilterPushdownSupport.PushdownResult pushFilters(List<Expression> filters)

Attempt to push filters to the source.

The implementation should examine each expression and determine if it can be converted to a source-specific filter. Expressions that can be fully pushed should be converted; those that cannot should be returned as remainder.

Parameters:

filters - ESQL filter expressions (AND-separated)

Returns:

result containing the pushed filter (opaque) and remainder expressions

canPush

default FilterPushdownSupport.Pushability canPush(Expression expr)

Check if a single expression can be pushed to the source.

Similar to Lucene's translatable() returning YES/NO/RECHECK, this method allows fine-grained control over which expressions are pushable.

Parameters:

expr - the expression to check

Returns:

the pushability status