Package dev.frostlake.functions.scalar.file

Class FileDescriptor

java.lang.Object
dev.frostlake.functions.scalar.file.FileDescriptor
public final class FileDescriptor extends Object
Builds and validates the file-metadata object that IS a FILE value.

Measured live: SELECT TO_FILE('@sse/hello.txt') yields exactly 


 {"CONTENT_TYPE":"text/plain","ETAG":"b7dddf722cfdc51710087d369f8d9e6b",
  "LAST_MODIFIED":"Mon, 03 Aug 2026 11:24:13 GMT","RELATIVE_PATH":"hello.txt",
  "SIZE":24,"STAGE":"@PROBE135_DB.S.SSE"}
— keys in alphabetical order, SIZE a JSON number, LAST_MODIFIED an RFC-1123 HTTP date in GMT with a ZERO-PADDED two-digit day (note LIST @stage formats the same instant with an unpadded day, so the two are not interchangeable), and ETAG the file's MD5 hex — verified equal to the md5 column of LIST @stage for every staged file on a server-side encrypted stage.

Frostlake's stages are real local directories, so every one of those fields is read from the actual file: SIZE from its length, LAST_MODIFIED from its mtime, ETAG from its MD5, CONTENT_TYPE from its extension (see FileContentTypes). Nothing here is synthesised from the path text.

The two URL fields are the exception. SCOPED_FILE_URL and STAGE_FILE_URL are absent from a descriptor TO_FILE builds from a stage path — live, both FL_GET_STAGE_FILE_URL and FL_GET_SCOPED_FILE_URL return NULL for such a file, even on a directory-enabled stage. They are plain descriptor FIELDS that only a caller-supplied metadata object populates (proved by feeding TRY_TO_FILE an object carrying them and reading them straight back). So the accessors read the field and Frostlake leaves it unset — returning NULL is the measured behaviour, not a shortfall.

  • Field Details

    • CONTENT_TYPE

      public static final String CONTENT_TYPE
      The descriptor's CONTENT_TYPE field.
      See Also:

    • ETAG

      public static final String ETAG
      The descriptor's ETAG field — the file's MD5 hex.
      See Also:

    • LAST_MODIFIED

      public static final String LAST_MODIFIED
      The descriptor's LAST_MODIFIED field — an RFC-1123 date string.
      See Also:

    • RELATIVE_PATH

      public static final String RELATIVE_PATH
      The descriptor's RELATIVE_PATH field.
      See Also:

    • SIZE

      public static final String SIZE
      The descriptor's SIZE field — a number of bytes.
      See Also:

    • STAGE

      public static final String STAGE
      The descriptor's STAGE field, e.g. @DB.SCHEMA.NAME.
      See Also:

    • SCOPED_FILE_URL

      public static final String SCOPED_FILE_URL
      The descriptor's SCOPED_FILE_URL field — only ever caller-supplied.
      See Also:

    • STAGE_FILE_URL

      public static final String STAGE_FILE_URL
      The descriptor's STAGE_FILE_URL field — only ever caller-supplied.
      See Also:

  • Method Details

    • notFoundMessage

      public static String notFoundMessage(String location)
      Snowflake's "Remote file 'x' was not found…" message for the given location.

    • fromLocation

      public static VariantValue fromLocation(String location, StageFileLocator locator)
      Resolve a stage reference and read the real file's metadata.
      Parameters:
      location - the stage reference as the caller wrote it (it is echoed in the error)
      locator - resolves the reference to a file on disk
      Returns:
      the descriptor, or null when the file does not exist (the caller decides whether that is an error, as TO_FILE does, or a NULL, as TRY_TO_FILE does)

    • fromMetadataObject

      public static VariantValue fromMetadataObject(Object value, boolean tryMode)
      Validate a caller-supplied metadata object, as TO_FILE(OBJECT) does. Unlike the stage-path form this does NOT check that the file exists — live, an object naming x.txt on a real stage round-trips even though no such file is there.
      Parameters:
      value - the object, as an OBJECT/VARIANT runtime value
      tryMode - true for TRY_TO_FILE (invalid input yields null instead of an error)
      Returns:
      the descriptor, or null when tryMode and the object is invalid

    • textField

      public static String textField(Object value, String field)
      A descriptor field as text, or null when the value is not a descriptor or the field is unset.

    • descriptorNode

      public static tools.jackson.databind.JsonNode descriptorNode(Object value)
      The descriptor as a JSON object node, or null when the value is not one.

    • parseLastModified

      public static Instant parseLastModified(String text)
      Parses a descriptor LAST_MODIFIED string, or null when it is not RFC-1123.

    • formatLastModified

      public static String formatLastModified(Instant instant)
      Renders an instant the way a descriptor's LAST_MODIFIED reads.