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

Interface StorageProvider

All Superinterfaces:

AutoCloseable, Closeable

public interface StorageProvider
extends Closeable

Abstraction for accessing objects in external storage systems. Implementations handle specific protocols (HTTP, S3, GCS, local, etc.). This is a read-only interface focused on ESQL's needs for querying external data.

Method Summary

Modifier and Type	Method	Description
boolean	exists(StoragePath path)	Checks if an object exists at the given path.
StorageIterator	listObjects(StoragePath prefix, boolean recursive)	Lists objects under a prefix.
StorageObject	newObject(StoragePath path)	Creates a StorageObject for reading.
StorageObject	newObject(StoragePath path, long length)	Creates a StorageObject with pre-known length (avoids HEAD request for remote objects).
StorageObject	newObject(StoragePath path, long length, Instant lastModified)	Creates a StorageObject with pre-known length and modification time.
List<String>	supportedSchemes()	Returns the URI schemes this provider handles (e.g., ["http", "https"]).
default boolean	supportsStableMetadata()	Whether this provider's objects have reliable last-modified timestamps suitable for mtime-based cache invalidation.

Methods inherited from interface java.io.Closeable

close

Method Details

newObject

StorageObject newObject(StoragePath path)

Creates a StorageObject for reading. The path must be a valid object path.

newObject

StorageObject newObject(StoragePath path,
 long length)

Creates a StorageObject with pre-known length (avoids HEAD request for remote objects).

newObject

StorageObject newObject(StoragePath path,
 long length,
 Instant lastModified)

Creates a StorageObject with pre-known length and modification time.

listObjects

StorageIterator listObjects(StoragePath prefix,
 boolean recursive)
                     throws IOException

Lists objects under a prefix. For blob storage, lists all objects with the given prefix. Returns an iterator to support lazy loading of large directories.

Parameters:

prefix - the prefix path to list under

recursive - if true, recurse into subdirectories; if false, list only immediate children

Throws:

IOException

exists

boolean exists(StoragePath path)
        throws IOException

Checks if an object exists at the given path.

Throws:

IOException

supportedSchemes

List<String> supportedSchemes()

Returns the URI schemes this provider handles (e.g., ["http", "https"]).

supportsStableMetadata

default boolean supportsStableMetadata()

Whether this provider's objects have reliable last-modified timestamps suitable for mtime-based cache invalidation. Returns true by default. Providers serving dynamic content (e.g. HTTP URLs) should return false so the schema cache is bypassed and metadata is resolved fresh on every query.