Package dev.frostlake.functions.scalar.file

Class ToFile

java.lang.Object

dev.frostlake.functions.BuiltInFunction

dev.frostlake.functions.scalar.file.ToFile

public class ToFile
extends BuiltInFunction

TO_FILE(stage_and_path) / TO_FILE(stage, relative_path) / TO_FILE(metadata) — builds the file-metadata object that is a FILE value.

Live-verified:

• The stage-path form RESOLVES AND VALIDATES: TO_FILE('@sse/hello.txt') returns the descriptor read from the real file, and TO_FILE('@sse/missing.txt') fails "Remote file '@sse/missing.txt' was not found. …". TRY_TO_FILE returning NULL there is the ONLY difference between the two functions.
• The two-argument form is a plain join: TO_FILE('@sse', '/hello.txt') fails naming '@sse//hello.txt', and TO_FILE('sse', 'hello.txt') fails naming 'sse/hello.txt' — no @ is added and no separator is collapsed.
• A directory is not a file: TO_FILE('@sse/sub') and TO_FILE('@sse/') both fail "was not found".
• User and table stages resolve too — TO_FILE('@~/p135/hello.txt') and TO_FILE('@%tstg/hello.txt') both return descriptors.
• NULL in, NULL out, for both functions and with no error.
• The metadata-object form validates structure but NOT existence, so it is the one way to build a FILE value for a file that is not there.

The engine registers this twice: once from FunctionRegistry with no locator (so the name resolves and SHOW FUNCTIONS lists it) and again from QueryExecutor with a locator that can reach stages — the same two-step GET_DDL uses.

Constructor Summary

Constructors

Constructor	Description
ToFile()
ToFile(StageFileLocator locator)

Method Summary

Modifier and Type	Method	Description
static VariantValue	convert(List<Object> args, StageFileLocator locator, boolean tryMode)	The shared body of TO_FILE and TRY_TO_FILE.
Object	evaluate(List<Object> args)	Computes the function's result over its already-evaluated argument values.
int	getMaxArgCount()	The most arguments a call to this function may pass; Integer.MAX_VALUE marks a variadic function (see BuiltInFunction.isVariadic()).
int	getMinArgCount()	The fewest arguments a call to this function may pass; fewer is an argument-count error.

Methods inherited from class dev.frostlake.functions.BuiltInFunction

approximateRejection, binaryRejection, booleanRejection, evaluate, fileRejection, geoRejection, getName, getReturnType, isVariadic, refusesMissingArgumentsByType, semiStructuredRejection, structuredRejection, temporalRejection, temporalRejection, temporalRejection, textRejection, uuidRejection, vectorRejection

Methods inherited from class java.lang.Object

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

Constructor Details

ToFile

public ToFile()

ToFile

public ToFile(StageFileLocator locator)

Method Details

convert

public static VariantValue convert(List<Object> args,
 StageFileLocator locator,
 boolean tryMode)

The shared body of TO_FILE and TRY_TO_FILE.

Parameters:

args - the call arguments (one location/metadata, or a stage and a relative path)

locator - resolves a stage reference to a real file

tryMode - true for TRY_TO_FILE: every failure becomes NULL

Returns:

the FILE descriptor, or null

evaluate

public Object evaluate(List<Object> args)

Description copied from class: BuiltInFunction

Computes the function's result over its already-evaluated argument values. A SQL NULL argument arrives as Java null, and returning null makes the SQL result NULL.

Specified by:

evaluate in class BuiltInFunction

Parameters:

args - the argument values, in call order

Returns:

the function's value for these arguments, or null for SQL NULL

getMinArgCount

public int getMinArgCount()

Description copied from class: BuiltInFunction

The fewest arguments a call to this function may pass; fewer is an argument-count error.

Specified by:

getMinArgCount in class BuiltInFunction

Returns:

the minimum accepted argument count

getMaxArgCount

public int getMaxArgCount()

Description copied from class: BuiltInFunction

The most arguments a call to this function may pass; Integer.MAX_VALUE marks a variadic function (see BuiltInFunction.isVariadic()).

Specified by:

getMaxArgCount in class BuiltInFunction

Returns:

the maximum accepted argument count