Package dev.frostlake.values

Class VectorValue

java.lang.Object
dev.frostlake.values.VectorValue
All Implemented Interfaces:
Serializable, Comparable<VectorValue>
public final class VectorValue extends Object implements Comparable<VectorValue>, Serializable
Runtime value of Snowflake's VECTOR(FLOAT|INT, n) type: a fixed-length list of 32-BIT elements plus the element type. The elements are held as double because every 32-bit float and every 32-bit int is exactly representable there — the narrowing is applied on the way IN, so a stored element is always a value the declared type can hold.

The precision split (live-verified). Vector ELEMENTS are 32-bit while the arithmetic OVER them is 64-bit:

  • VECTOR_NORMALIZE([1,2,3]::VECTOR(FLOAT,3)) is [0.26726124,0.5345225, 0.80178374] — the float32 renderings of the float64 quotients, not 0.2672612419124244;
  • VECTOR_L1_DISTANCE([0.1,0.2,0.3], [0.4,0.5,0.6]) is 0.9000000134110451, which is EXACTLY the float64 sum of the three float64-widened float32 differences — a float32 accumulation would round to 0.90000004;
  • VECTOR_NORMALIZE([1e-30,2e-30,2e-30]::VECTOR(FLOAT,3)) is [0.33333334,0.6666667,0.6666667], which float32 arithmetic could not produce at all (the squares underflow to zero in float32).
So: read the 32-bit elements, compute in double, and narrow only the ELEMENTS of a vector RESULT — of(dev.frostlake.types.VectorElementType, double[]). A scalar result keeps full double precision.

Rendering is a FIXED SIX DECIMAL PLACES for FLOAT — %.6f, rounded, never scientific and never trimmed — while INT prints plainly. It is the element's own value that is rendered, so the float32 narrowing above shows through: [1,2,3] reads [1.000000,2.000000,3.000000], VECTOR_NORMALIZE([1,2,3]) reads [0.267261,0.534522,0.801784], 1e-20 reads 0.000000 and 1e20 reads 100000002004087734272.000000 — the float32's exact value written out in full.

This class previously claimed the shortest round-tripping text (Float.toString(float)) and cited three values as live-verified; all three were wrong about the TEXT, though right about the VALUE. Six places is a THIRD float spelling in this engine, sharing nothing with the two beside it: a FLOAT cast to VARCHAR is ten SIGNIFICANT digits (SharedFunctionHelpers.floatText) and a DOUBLE inside a VARIANT keeps its own. A vector's SCALAR results — VECTOR_L1_DISTANCE and the rest — follow the ten-significant-digit rule and not this one, because they are floats and not vectors.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static VectorValue
    cast(Object value, VectorType target)
    expr::VECTOR(t, n) — the value converted to the declared vector type, with Snowflake's live conversion errors.
    int
    compareTo(VectorValue other)
    Element-wise ordering, shorter-first on a common prefix — the ordering the display text implies.
    int
    dimension()
     
    double
    element(int index)
    Element index as float64 — exact, because the stored value is already 32-bit.
    double[]
    elements()
    The elements as float64, ready to compute over (a copy: the value is immutable).
    boolean
    equals(Object other)
     
    VectorElementType
    getElementType()
     
    int
    hashCode()
     
    static VectorValue
    of(VectorElementType elementType, double[] computed)
    A vector of computed float64 values NARROWED to elementType — the one way a function builds a vector result, so the 32-bit element rule is applied in a single place.
    String
    toString()
     
    VectorType
    type()
    The declared type this value belongs to — element type AND dimension.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static VectorValue of(VectorElementType elementType, double[] computed)
      A vector of computed float64 values NARROWED to elementType — the one way a function builds a vector result, so the 32-bit element rule is applied in a single place.

    • cast

      public static VectorValue cast(Object value, VectorType target)
      expr::VECTOR(t, n) — the value converted to the declared vector type, with Snowflake's live conversion errors. An ARRAY (or its JSON text) of the right length converts; a vector of exactly the same type passes through; anything else is rejected.

    • getElementType

      public VectorElementType getElementType()

    • dimension

      public int dimension()

    • element

      public double element(int index)
      Element index as float64 — exact, because the stored value is already 32-bit.

    • elements

      public double[] elements()
      The elements as float64, ready to compute over (a copy: the value is immutable).

    • type

      public VectorType type()
      The declared type this value belongs to — element type AND dimension.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • compareTo

      public int compareTo(VectorValue other)
      Element-wise ordering, shorter-first on a common prefix — the ordering the display text implies.
      Specified by:
      compareTo in interface Comparable<VectorValue>