Package org.elasticsearch.xpack.esql.datasources

Class FormatNameResolver

java.lang.Object

org.elasticsearch.xpack.esql.datasources.FormatNameResolver

public final class FormatNameResolver
extends Object

Single source of truth for resolving format names from EXTERNAL query configuration.

Both the optimizer (PushFiltersToSource) and execution (FileSourceFactory) need to resolve which format reader to use for a given query. This class centralises that logic so the two code paths cannot diverge.

Resolution priority:

1. reader config key — reader alias mapped to format name
2. format config key: explicit format override (the sentinel FORMAT_AUTO and an empty value mean "no override" and fall through to the extension)
3. File extension extracted from the source path

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CONFIG_FORMAT
static final FeatureFlag	ESQL_EXTERNAL_PARQUET_RS_FEATURE_FLAG	Gates the prototype parquet-rs native reader and its public reader=parquet-rs selector.
static final String	FORMAT_AUTO	Sentinel format value meaning "no explicit override, infer from the resource extension".
static final String	FORMAT_PARQUET	Format name registered by the Java parquet reader.
static final String	FORMAT_PARQUET_RS	Format name registered by the parquet-rs native reader.
static final String	READER_JAVA	Reader alias accepted in WITH {"reader": "..."} for the Java parquet reader.
static final String	READER_PARQUET_RS	Reader alias accepted in WITH {"reader": "..."} for the parquet-rs native reader.

Method Summary

Modifier and Type	Method	Description
static String	normalizeFormatValue(Object raw)	Normalizes a raw format value to its canonical stored form — trim() then toLowerCase(Locale.ROOT) — or null when the value is absent.
static boolean	parquetRsEnabled()	The parquet-rs reader is live iff the parquet-rs sub-flag is on.
static String	parseExplicitFormat(Object raw)	Resolves a raw format config value into a usable format name, or returns null when the value means "infer from the resource extension" (blank, or the FORMAT_AUTO sentinel).
static String	readerAliasToFormat(String alias)	Maps a reader alias to its format name.
static String	resolve(Map<String,Object> config, String sourcePath)	Resolves the format name from the WITH config map and/or the source path.
static String	resolveFormatName(Map<String,Object> config, String objectName, FormatReaderRegistry registry)	Resolves the format name (e.g.
static FormatReader	resolveReader(Map<String,Object> config, String objectName, FormatReaderRegistry registry)	Resolves the format reader using config and source path, looking up the result in the registry.
static Set<String>	supportedReaderAliases()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

CONFIG_FORMAT

public static final String CONFIG_FORMAT

See Also:

• Constant Field Values

FORMAT_AUTO

public static final String FORMAT_AUTO

Sentinel format value meaning "no explicit override, infer from the resource extension". Shared with the dataset CRUD validator so the create path and this read path treat auto identically. Without this, a stored or EXTERNAL format=auto would reach registry.byName("auto") and throw.

See Also:

• Constant Field Values

READER_PARQUET_RS

public static final String READER_PARQUET_RS

Reader alias accepted in WITH {"reader": "..."} for the parquet-rs native reader.

See Also:

• Constant Field Values

READER_JAVA

public static final String READER_JAVA

Reader alias accepted in WITH {"reader": "..."} for the Java parquet reader.

See Also:

• Constant Field Values

FORMAT_PARQUET

public static final String FORMAT_PARQUET

Format name registered by the Java parquet reader.

See Also:

• Constant Field Values

FORMAT_PARQUET_RS

public static final String FORMAT_PARQUET_RS

Format name registered by the parquet-rs native reader.

See Also:

• Constant Field Values

ESQL_EXTERNAL_PARQUET_RS_FEATURE_FLAG

public static final FeatureFlag ESQL_EXTERNAL_PARQUET_RS_FEATURE_FLAG

Gates the prototype parquet-rs native reader and its public reader=parquet-rs selector. Snapshot-on, release-off; override in release with -Des.esql_external_parquet_rs_feature_flag_enabled=true. Lives here (and not in the parquet-rs plugin module) so this esql-core resolver can gate the alias while ParquetRsPlugin — which already depends on this class — reuses the same flag for format registration.

Method Details

parquetRsEnabled

public static boolean parquetRsEnabled()

The parquet-rs reader is live iff the parquet-rs sub-flag is on.

normalizeFormatValue

@Nullable
public static String normalizeFormatValue(Object raw)

Normalizes a raw format value to its canonical stored form — trim() then toLowerCase(Locale.ROOT) — or null when the value is absent. This is the single source of the normalization, so the create-time storage representation and the query-time resolution cannot drift. Unlike parseExplicitFormat(java.lang.Object) it does not collapse the FORMAT_AUTO sentinel: the CRUD validator stores auto verbatim so it round-trips, whereas the read path treats it as "infer from the extension".

parseExplicitFormat

@Nullable
public static String parseExplicitFormat(Object raw)

Resolves a raw format config value into a usable format name, or returns null when the value means "infer from the resource extension" (blank, or the FORMAT_AUTO sentinel). Normalizes via normalizeFormatValue(java.lang.Object), so a value accepted here resolves identically at query time.

This is the single source of truth for format sentinel handling. Both the CRUD validator (FileDataSourceValidator.explicitFormat) and the query-time resolvers (resolve(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String), resolveReader(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, org.elasticsearch.xpack.esql.datasources.FormatReaderRegistry)) delegate here so new sentinels only need one edit.

resolve

public static String resolve(Map<String,Object> config,
 String sourcePath)

Resolves the format name from the WITH config map and/or the source path.

Not compound-extension aware: the extension fallback here is a naive last-dot, so a compound name like hits.csv.gz resolves to the codec suffix "gz", not "csv". A caller that keys operator dispatch or reader lookup on the format over a possibly-compressed resource must use resolveFormatName(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, org.elasticsearch.xpack.esql.datasources.FormatReaderRegistry) (or resolveReader(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, org.elasticsearch.xpack.esql.datasources.FormatReaderRegistry)), which routes through the compound-aware registry. Kept for the config-override-only path (FileSourceFactory passes an empty source path); PushFiltersToSource still calls it over the exec source path and so misses filter pushdown on compressed text — migrating that caller is tracked separately.

Returns:

the format name (e.g. "parquet", "parquet-rs", "orc"), or null if undetermined

readerAliasToFormat

public static String readerAliasToFormat(String alias)

Maps a reader alias to its format name.

Returns:

the format name, or null if the alias is not recognised

supportedReaderAliases

public static Set<String> supportedReaderAliases()

resolveFormatName

public static String resolveFormatName(Map<String,Object> config,
 String objectName,
 FormatReaderRegistry registry)

Resolves the format name (e.g. "csv", "parquet") using config and source path, routed through the registry so it is compound-extension aware. Unlike resolve(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String), which last-dots the path and would yield the compression codec suffix ("gz") for a compound name like hits.csv.gz, this delegates to resolveReader(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String, org.elasticsearch.xpack.esql.datasources.FormatReaderRegistry) and reads back FormatReader.formatName() — FormatReader.formatName() returns the wrapped format, so the result equals the format name the inferred read path (FileSourceFactory) would produce. The strict resolver keys operator-factory dispatch on the result, so it uses this rather than resolve(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String) to avoid diverging from the read path over a compressed resource.

resolveReader

public static FormatReader resolveReader(Map<String,Object> config,
 String objectName,
 FormatReaderRegistry registry)

Resolves the format reader using config and source path, looking up the result in the registry.

Config-based overrides (reader, format) are resolved via resolve(java.util.Map<java.lang.String, java.lang.Object>, java.lang.String) and looked up by name. Extension-based resolution delegates to FormatReaderRegistry.byExtension which handles compound extensions (e.g. .ndjson.bz) and compression codecs.