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

Interface ExternalSourceFactory

All Known Subinterfaces:

ConnectorFactory, TableCatalog

public interface ExternalSourceFactory

Common interface for complete external data source factories. Both API-based connectors (Flight, JDBC) and table-based catalogs (Iceberg) implement this interface, enabling unified resolution and dispatch. Building-block factories (StorageProviderFactory, FormatReaderFactory) are NOT part of this hierarchy — they are composed by the framework for file-based sources.

Method Summary

Modifier and Type	Method	Description
boolean	canHandle(String location)
default boolean	canHandle(String location, Map<String,Object> config)	Config-aware variant of canHandle(String) used by the resolver when selecting a factory.
default FilterPushdownSupport	filterPushdownSupport()
default SourceOperatorFactoryProvider	operatorFactory()
SourceMetadata	resolveMetadata(String location, Map<String,Object> config)
default void	resolveMetadataAsync(String location, ListingHint hint, Map<String,Object> config, Executor executor, ActionListener<SourceMetadata> listener)	Asynchronously resolves metadata for the given location.
default SplitProvider	splitProvider()
String	type()
void	validateConfig(String location, Map<String,Object> config)	Reject configuration keys this factory doesn't recognize at the given location.

Method Details

type

String type()

canHandle

boolean canHandle(String location)

canHandle

default boolean canHandle(String location,
 Map<String,Object> config)

Config-aware variant of canHandle(String) used by the resolver when selecting a factory. The default delegates to the path-only form; a factory overrides this when query configuration can supply information the path alone lacks. The file factory uses it to claim an extensionless resource when an explicit format is configured (the read-path counterpart to the CRUD validator accepting an explicit format on an extensionless resource).

resolveMetadata

SourceMetadata resolveMetadata(String location,
 Map<String,Object> config)

resolveMetadataAsync

default void resolveMetadataAsync(String location,
 @Nullable
 ListingHint hint,
 Map<String,Object> config,
 Executor executor,
 ActionListener<SourceMetadata> listener)

Asynchronously resolves metadata for the given location.

The default wraps the synchronous resolveMetadata(String, Map) in the provided executor. File-based factories that can issue the footer/metadata read without pinning an executor thread across the network round-trip should override this to route through the format reader's FormatReader.metadataAsync(org.elasticsearch.xpack.esql.datasources.spi.StorageObject, java.util.concurrent.Executor, org.elasticsearch.action.ActionListener<org.elasticsearch.xpack.esql.datasources.spi.SourceMetadata>) path, so a multi-file discovery fan-out is bounded by an in-flight permit rather than by the executor's thread count.

When hint is non-null the caller already knows the object's length/mtime from a directory listing; overrides must build the storage object from it and skip any existence/HEAD probe, since that probe is a synchronous round-trip (e.g. an S3 HEAD) that would pin the executor thread before the async read and defeat the in-flight bound. A null hint means nothing is known (a single, explicitly-referenced path) and the override must verify existence itself.

validateConfig

void validateConfig(String location,
 Map<String,Object> config)

Reject configuration keys this factory doesn't recognize at the given location. Implementations compose their claimed-key sets and call ConfigKeyValidator.check(java.util.Map<java.lang.String, java.lang.Object>, java.util.Collection<java.util.Set<java.lang.String>>).

Required override. Every factory must explicitly state its validation contract — either by composing claimed-key sets and delegating to ConfigKeyValidator.check(java.util.Map<java.lang.String, java.lang.Object>, java.util.Collection<java.util.Set<java.lang.String>>), or, for factories with no per-query config keys today, by calling ConfigKeyValidator.check(config, List.of()) to reject any non-empty config map. An empty method body would silently accept typo'd configurations — exactly the footgun this abstract contract exists to prevent — so do not write one.

filterPushdownSupport

default FilterPushdownSupport filterPushdownSupport()

operatorFactory

default SourceOperatorFactoryProvider operatorFactory()

splitProvider

default SplitProvider splitProvider()