package datatypes

import "github.com/datastax/astra-db-go/v2/astra/datatypes"

Package datatypes defines the data types used in the Astra DB Go client library.

Index

Constants

const (
	NSPerHour = int64(3_600_000_000_000)
	NSPerMin  = int64(60_000_000_000)
	NSPerSec  = int64(1_000_000_000)
	NSPerMS   = int64(1_000_000)
	NSPerUS   = int64(1_000)
)

Nanosecond conversion constants. 

const (
	DurationMaxMonthsDays = int32(math.MaxInt32)
	DurationMaxNanos      = int64(math.MaxInt64)
)

Types

type Comparable

type Comparable interface {
	CompareTo(other any) int
}

Comparable is for types that can compare themselves to another value of the same type. The other arg will be the same type as the receiver.

type Comparator

type Comparator func(a, b unsafe.Pointer) int

Comparator compares two values via pointers. Return <0 for a < b, 0 for a == b, and >0 for a > b.

func ComparatorFor
func ComparatorFor(t reflect.Type) Comparator

ComparatorFor returns a Comparator for common types like primitives, time.Time, or Comparable.

reflect.Type is only used once at construction to pick the logic; the returned closure uses unsafe.Pointer casts and is allocation-free.

The Comparable branch is the exception — it uses reflect.NewAt and .Interface() which allocates on each call, but Comparable keys are niche enough that it shouldn't matter.

type DateOnly

type DateOnly struct {
	Year  int
	Month int
	Day   int
}

DateOnly represents a date (year, month, day) without a time component, used for Data API 'date' columns in tables.

func DateOnlyFromTime
func DateOnlyFromTime(t time.Time) DateOnly

DateOnlyFromTime creates a DateOnly from a time.Time (local time).

func DateOnlyNow
func DateOnlyNow() DateOnly

DateOnlyNow creates a DateOnly for the current local date.

func DateOnlyUTCNow
func DateOnlyUTCNow() DateOnly

DateOnlyUTCNow creates a DateOnly for the current UTC date.

func MustParseDateOnly
func MustParseDateOnly(s string) DateOnly

MustParseDateOnly is like ParseDateOnly but panics on error.

func NewDateOnly
func NewDateOnly(year, month, day int) DateOnly

NewDateOnly creates a new DateOnly.

func ParseDateOnly
func ParseDateOnly(s string) (DateOnly, error)

ParseDateOnly parses a date string in [+-]?YYYY-MM-DD format.

func (DateOnly) CompareTo
func (d DateOnly) CompareTo(other any) int

CompareTo implements the Comparable interface.

func (DateOnly) String
func (d DateOnly) String() string

String returns the date in YYYY-MM-DD format. Years < 0 or >= 10000 are prefixed with a sign.

func (DateOnly) ToTime
func (d DateOnly) ToTime() time.Time

ToTime converts the DateOnly to a time.Time at midnight UTC.

type Duration

type Duration struct {
	// contains filtered or unexported fields
}

Duration represents a Cassandra duration type stored as months, days, and nanoseconds. These three components are not directly convertible to each other (months are calendar months, days are calendar days, and nanoseconds are a fixed-length time unit). All three components must share the same sign.

func MustParseDuration
func MustParseDuration(s string) Duration

MustParseDuration parses a duration string and panics on error. Intended for use in tests and with known-valid inputs.

func NewDuration
func NewDuration(months int32, days int32, nanoseconds int64) (Duration, error)

NewDuration creates a Duration from months, days, and nanoseconds. All components must share the same sign and be within valid ranges: months and days in [-2147483647, 2147483647], nanoseconds in [-9223372036854775807, 9223372036854775807].

func ParseDuration
func ParseDuration(s string) (Duration, error)

ParseDuration parses a duration string in one of four formats:

func (Duration) Abs
func (d Duration) Abs() Duration

Abs returns the duration with a positive sign, negating if needed.

func (Duration) AppendShortString
func (d Duration) AppendShortString(dst []byte) []byte

AppendShortString appends the compact API wire format to dst. Months, days, and nanoseconds are each expressed as a raw count with a single unit suffix. Example: Duration{14, 3, 3_600_000_000_000} → "14mo3d3600000000000ns"

func (Duration) Days
func (d Duration) Days() int32

Days returns the days component of the duration.

func (Duration) Equals
func (d Duration) Equals(other Duration) bool

Equals returns true if both durations have identical component values.

func (Duration) HasDayPrecision
func (d Duration) HasDayPrecision() bool

HasDayPrecision returns true if the nanoseconds component is zero (no sub-day precision).

func (Duration) HasMillisecondPrecision
func (d Duration) HasMillisecondPrecision() bool

HasMillisecondPrecision returns true if the nanoseconds component is a multiple of 1,000,000.

func (Duration) IsNegative
func (d Duration) IsNegative() bool

IsNegative returns true if any component is negative.

func (Duration) IsZero
func (d Duration) IsZero() bool

IsZero returns true if all components are zero.

func (Duration) MarshalJSON
func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler using the compact string wire format.

func (Duration) Months
func (d Duration) Months() int32

Months returns the months component of the duration.

func (Duration) Nanoseconds
func (d Duration) Nanoseconds() int64

Nanoseconds returns the nanoseconds component of the duration.

func (Duration) Negate
func (d Duration) Negate() Duration

Negate returns a new Duration with all components negated.

func (Duration) Plus
func (d Duration) Plus(other Duration) (Duration, bool)

Plus returns the component-wise sum of two durations. Returns (result, true) on success, or (zero, false) if the durations have opposite signs or the result is invalid (e.g. overflow).

func (Duration) String
func (d Duration) String() string

String returns the human-readable long-form representation (e.g. "1y3mo25d5h6m7s8ms9us10ns").

func (*Duration) UnmarshalJSON
func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler, parsing the duration from a string.

type DurationBuilder

type DurationBuilder struct {
	// contains filtered or unexported fields
}

DurationBuilder builds a Duration incrementally. Use NewDurationBuilder or NewDurationBuilderFrom to create one. Errors from Add* methods accumulate and are returned on Build.

func NewDurationBuilder
func NewDurationBuilder() *DurationBuilder

NewDurationBuilder returns a new empty DurationBuilder.

func NewDurationBuilderFrom
func NewDurationBuilderFrom(base Duration) *DurationBuilder

NewDurationBuilderFrom returns a DurationBuilder initialized from an existing Duration.

func (*DurationBuilder) AddDays
func (b *DurationBuilder) AddDays(n int32) *DurationBuilder
func (*DurationBuilder) AddHours
func (b *DurationBuilder) AddHours(n int64) *DurationBuilder

AddHours adds n hours (converted to nanoseconds).

func (*DurationBuilder) AddMicros
func (b *DurationBuilder) AddMicros(n int64) *DurationBuilder

AddMicros adds n microseconds (converted to nanoseconds).

func (*DurationBuilder) AddMillis
func (b *DurationBuilder) AddMillis(n int64) *DurationBuilder

AddMillis adds n milliseconds (converted to nanoseconds).

func (*DurationBuilder) AddMinutes
func (b *DurationBuilder) AddMinutes(n int64) *DurationBuilder

AddMinutes adds n minutes (converted to nanoseconds).

func (*DurationBuilder) AddMonths
func (b *DurationBuilder) AddMonths(n int32) *DurationBuilder
func (*DurationBuilder) AddNanos
func (b *DurationBuilder) AddNanos(n int64) *DurationBuilder

AddNanos adds n nanoseconds.

func (*DurationBuilder) AddSeconds
func (b *DurationBuilder) AddSeconds(n int64) *DurationBuilder

AddSeconds adds n seconds (converted to nanoseconds).

func (*DurationBuilder) AddWeeks
func (b *DurationBuilder) AddWeeks(n int32) *DurationBuilder
func (*DurationBuilder) AddYears
func (b *DurationBuilder) AddYears(n int32) *DurationBuilder
func (*DurationBuilder) Build
func (b *DurationBuilder) Build() (Duration, error)

Build returns the constructed Duration, or an error if any Add* call failed.

func (*DurationBuilder) Negate
func (b *DurationBuilder) Negate() *DurationBuilder

Negate toggles whether the built duration is negative.

func (*DurationBuilder) SetNegative
func (b *DurationBuilder) SetNegative(negative bool) *DurationBuilder

SetNegative explicitly sets the sign of the built duration.

type LinkedMap

type LinkedMap[K comparable, V any] struct {
	// contains filtered or unexported fields
}

LinkedMap is a hash map that preserves insertion order. Don't use the zero value; initialize it with NewLinkedMap or NewLinkedMapWithCapacity so it doesn't panic. It's a pointer wrapper, so it's safe to copy and pass by value.

func NewLinkedMap
func NewLinkedMap[K comparable, V any]() LinkedMap[K, V]

NewLinkedMap returns an empty LinkedMap.

func NewLinkedMapWithCapacity
func NewLinkedMapWithCapacity[K comparable, V any](capacity int) LinkedMap[K, V]

NewLinkedMapWithCapacity returns an empty LinkedMap with the given capacity.

func (LinkedMap[K, V]) All
func (m LinkedMap[K, V]) All() iter.Seq2[K, V]

All iterates entries in insertion order.

func (LinkedMap[K, V]) AllRev
func (m LinkedMap[K, V]) AllRev() iter.Seq2[K, V]

AllRev iterates entries in reverse insertion order.

func (LinkedMap[K, V]) Clear
func (m LinkedMap[K, V]) Clear()

Clear removes everything from the map.

func (LinkedMap[K, V]) Clone
func (m LinkedMap[K, V]) Clone() LinkedMap[K, V]

Clone returns a shallow copy that preserves insertion order.

func (LinkedMap[K, V]) Delete
func (m LinkedMap[K, V]) Delete(key K) (v V, found bool)

Delete removes a key and returns its value.

func (LinkedMap[K, V]) First
func (m LinkedMap[K, V]) First() *LinkedMapNode[K, V]

First returns the first node in insertion order, or nil if empty.

func (LinkedMap[K, V]) Get
func (m LinkedMap[K, V]) Get(key K) (v V, found bool)

Get returns the value for key, or false if it's missing.

func (LinkedMap[K, V]) GetOrDefault
func (m LinkedMap[K, V]) GetOrDefault(key K, defaultValue V) V

GetOrDefault returns the value for key, or defaultValue if it's missing.

func (LinkedMap[K, V]) Has
func (m LinkedMap[K, V]) Has(key K) bool

Has reports if a key is present.

func (LinkedMap[K, V]) Last
func (m LinkedMap[K, V]) Last() *LinkedMapNode[K, V]

Last returns the last node in insertion order, or nil if empty.

func (LinkedMap[K, V]) Len
func (m LinkedMap[K, V]) Len() int

Len is the number of entries in the map.

func (LinkedMap[K, V]) Set
func (m LinkedMap[K, V]) Set(key K, value V) (V, bool)

Set adds or updates a key-value pair. Returns the old value and true if the key existed, or zero/false if it's a fresh insert. Panics if the map is nil (use NewLinkedMap).

func (LinkedMap[K, V]) SetAny
func (m LinkedMap[K, V]) SetAny(key any, value any) bool

SetAny is an internal hook for serdes to insert entries via reflection.

func (LinkedMap[K, V]) String
func (m LinkedMap[K, V]) String() string
func (LinkedMap[K, V]) ToMap
func (m LinkedMap[K, V]) ToMap() map[K]V

ToMap returns a plain Go map with the same entries.

type LinkedMapNode

type LinkedMapNode[K comparable, V any] struct {
	// contains filtered or unexported fields
}

LinkedMapNode is a node in the map, exposed for direct traversal via First/Last.

func (*LinkedMapNode[K, V]) Key
func (n *LinkedMapNode[K, V]) Key() K
func (*LinkedMapNode[K, V]) Next
func (n *LinkedMapNode[K, V]) Next() *LinkedMapNode[K, V]
func (*LinkedMapNode[K, V]) Prev
func (n *LinkedMapNode[K, V]) Prev() *LinkedMapNode[K, V]
func (*LinkedMapNode[K, V]) Value
func (n *LinkedMapNode[K, V]) Value() V

type ObjectId

type ObjectId struct {
	// contains filtered or unexported fields
}

ObjectId represents an ObjectId that can be used as an _id in the DataAPI. json.Marshals to {"$objectId": "6672e1cbd7fabb4e5493916f"}.

func MustParseObjectId
func MustParseObjectId(s string) ObjectId
func NewObjectId
func NewObjectId() ObjectId

NewObjectId generates a new ObjectId based on the current time.

func NewObjectIdAt
func NewObjectIdAt(t time.Time) ObjectId

NewObjectIdAt generates a new ObjectId encoding the given timestamp. The random and counter components are still generated normally.

func ParseObjectId
func ParseObjectId(s string) (ObjectId, error)

ParseObjectId parses an ObjectId from its 24-character hex string representation.

func (ObjectId) Bytes
func (o ObjectId) Bytes() [12]byte

Bytes returns the raw 12-byte ObjectId value.

func (ObjectId) CompareTo
func (o ObjectId) CompareTo(other any) int

CompareTo implements the Comparable interface.

func (ObjectId) Equals
func (o ObjectId) Equals(other ObjectId) bool

Equals returns true if the two ObjectIds have identical bytes.

func (ObjectId) GetTimestamp
func (o ObjectId) GetTimestamp() time.Time

GetTimestamp extracts the creation timestamp from the ObjectId. The first 4 bytes encode Unix seconds.

func (ObjectId) IsZero
func (o ObjectId) IsZero() bool

IsZero returns true if the ObjectId is the zero value (all bytes are 0).

func (ObjectId) MarshalJSON
func (o ObjectId) MarshalJSON() ([]byte, error)

MarshalJSON produces the Data API extended JSON format: {"$objectId": "6672e1cbd7fabb4e5493916f"}.

func (ObjectId) MarshalText
func (o ObjectId) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It returns the 24-character lowercase hex string.

func (ObjectId) String
func (o ObjectId) String() string

String returns the 24-character lowercase hex representation of the ObjectId.

func (*ObjectId) UnmarshalJSON
func (o *ObjectId) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the Data API extended JSON format: {"$objectId": "..."}.

func (*ObjectId) UnmarshalText
func (o *ObjectId) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a 24-character hex string.

type Set

type Set[T any] SortedMap[T, struct{}]

Set represents a collection of unique elements, kept in sorted order.

func NewSet
func NewSet[T any](elements ...T) Set[T]

NewSet returns a new Set for the given type T.

func NewSetWithComparator
func NewSetWithComparator[T any](cmp Comparator, elements ...T) Set[T]

NewSetWithComparator returns a new Set with a custom Comparator.

func (Set[T]) Add
func (s Set[T]) Add(v T)
func (Set[T]) AddAll
func (s Set[T]) AddAll(elements ...T)
func (Set[T]) All
func (s Set[T]) All() iter.Seq[T]
func (Set[T]) AllRev
func (s Set[T]) AllRev() iter.Seq[T]
func (Set[T]) Clear
func (s Set[T]) Clear()
func (Set[T]) Clone
func (s Set[T]) Clone() Set[T]
func (Set[T]) Delete
func (s Set[T]) Delete(v T)
func (Set[T]) Difference
func (s Set[T]) Difference(other Set[T]) Set[T]
func (Set[T]) Equals
func (s Set[T]) Equals(other Set[T]) bool
func (Set[T]) First
func (s Set[T]) First() T
func (Set[T]) Has
func (s Set[T]) Has(v T) bool
func (Set[T]) Intersection
func (s Set[T]) Intersection(other Set[T]) Set[T]
func (Set[T]) IsSubsetOf
func (s Set[T]) IsSubsetOf(other Set[T]) bool
func (Set[T]) Last
func (s Set[T]) Last() T
func (Set[T]) Len
func (s Set[T]) Len() int
func (Set[T]) Pop
func (s Set[T]) Pop() (T, bool)
func (Set[T]) SetAny
func (s Set[T]) SetAny(v any, _ any) bool

SetAny is an internal hook for serdes to insert entries via reflection.

func (Set[T]) String
func (s Set[T]) String() string
func (Set[T]) SymmetricDifference
func (s Set[T]) SymmetricDifference(other Set[T]) Set[T]
func (Set[T]) ToSlice
func (s Set[T]) ToSlice() []T
func (Set[T]) Union
func (s Set[T]) Union(other Set[T]) Set[T]

type SortedMap

type SortedMap[K any, V any] struct {
	// contains filtered or unexported fields
}

SortedMap is a skip list-backed map that keeps keys ordered by a Comparator. K doesn't need to be comparable since the Comparator handles the logic. All operations are O(log n) on average.

Don't use the zero value; initialize it with NewSortedMap. It's a pointer wrapper, so it's safe to copy and pass by value.

func NewSortedMap
func NewSortedMap[K any, V any]() SortedMap[K, V]

NewSortedMap returns an empty map ordered by a default Comparator for K. Use NewSortedMapWithComparator for custom ordering.

func NewSortedMapWithComparator
func NewSortedMapWithComparator[K any, V any](cmp Comparator) SortedMap[K, V]

NewSortedMapWithComparator returns an empty map ordered by the given Comparator.

func (SortedMap[K, V]) All
func (m SortedMap[K, V]) All(bounds ...K) iter.Seq2[K, V]

All iterates entries in ascending key order. Supports bounds: All() is full, All(lo) is lo <= k, All(lo, hi) is lo <= k <= hi.

func (SortedMap[K, V]) AllRev
func (m SortedMap[K, V]) AllRev(bounds ...K) iter.Seq2[K, V]

AllRev iterates entries in descending key order. Supports bounds: AllRev() is full, AllRev(lo) is lo <= k, AllRev(lo, hi) is lo <= k <= hi.

O(n) time and space: skip lists don't support backward traversal, so we collect matching nodes into a slice and yield them in reverse.

func (SortedMap[K, V]) Clear
func (m SortedMap[K, V]) Clear()

Clear removes everything from the map.

func (SortedMap[K, V]) Delete
func (m SortedMap[K, V]) Delete(key K) (v V, found bool)

Delete removes a key and returns its value.

func (SortedMap[K, V]) First
func (m SortedMap[K, V]) First() *SortedMapNode[K, V]

First returns the first (smallest) node, or nil if empty.

func (SortedMap[K, V]) Get
func (m SortedMap[K, V]) Get(key K) (v V, found bool)

Get returns the value for key, or false if it's missing.

func (SortedMap[K, V]) GetOrDefault
func (m SortedMap[K, V]) GetOrDefault(key K, defaultValue V) V

GetOrDefault returns the value for key, or defaultValue if it's missing.

func (SortedMap[K, V]) Has
func (m SortedMap[K, V]) Has(key K) bool

Has reports if a key is present.

func (SortedMap[K, V]) Last
func (m SortedMap[K, V]) Last() *SortedMapNode[K, V]

Last returns the last (largest) node, or nil if empty.

func (SortedMap[K, V]) Len
func (m SortedMap[K, V]) Len() int

Len is the number of entries in the map.

func (SortedMap[K, V]) Set
func (m SortedMap[K, V]) Set(key K, value V) (V, bool)

Set adds or updates a key-value pair. Returns the old value and true if the key existed, or zero/false if it's a fresh insert. Panics if the map is nil (use NewSortedMap).

func (SortedMap[K, V]) SetAny
func (m SortedMap[K, V]) SetAny(key any, value any) bool

SetAny is an internal hook for serdes to insert entries via reflection.

func (SortedMap[K, V]) String
func (m SortedMap[K, V]) String() string

type SortedMapNode

type SortedMapNode[K any, V any] struct {
	// contains filtered or unexported fields
}

SortedMapNode is a node in the map, exposed for direct traversal via First/Last.

func (*SortedMapNode[K, V]) Key
func (n *SortedMapNode[K, V]) Key() K
func (*SortedMapNode[K, V]) Next
func (n *SortedMapNode[K, V]) Next() *SortedMapNode[K, V]
func (*SortedMapNode[K, V]) Value
func (n *SortedMapNode[K, V]) Value() V

type TimeOnly

type TimeOnly struct {
	Hour       int
	Minute     int
	Second     int
	Nanosecond int
}

TimeOnly represents a time (hour, minute, second, nanosecond) without a date component, used for Data API 'time' columns in tables.

func MustParseTimeOnly
func MustParseTimeOnly(s string) TimeOnly

MustParseTimeOnly is like ParseTimeOnly but panics on error.

func NewTimeOnly
func NewTimeOnly(hour, minute, second, nanosecond int) TimeOnly

NewTimeOnly creates a new TimeOnly.

func ParseTimeOnly
func ParseTimeOnly(s string) (TimeOnly, error)

ParseTimeOnly parses a time string in HH:MM[:SS[.NNNNNNNNN]] format.

func TimeOnlyFromTime
func TimeOnlyFromTime(t time.Time) TimeOnly

TimeOnlyFromTime creates a TimeOnly from a time.Time (local time).

func TimeOnlyNow
func TimeOnlyNow() TimeOnly

TimeOnlyNow creates a TimeOnly for the current local time.

func TimeOnlyUTCNow
func TimeOnlyUTCNow() TimeOnly

TimeOnlyUTCNow creates a TimeOnly for the current UTC time.

func (TimeOnly) CompareTo
func (t TimeOnly) CompareTo(other any) int

CompareTo implements the Comparable interface.

func (TimeOnly) String
func (t TimeOnly) String() string

String returns the time in HH:MM:SS.NNNNNNNNN format.

type UUID

type UUID struct {
	// contains filtered or unexported fields
}

UUID represents a universally unique identifier with Data API JSON serialization. On the wire, UUIDs are serialized as extended JSON: {"$uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}.

func MustParseUUID
func MustParseUUID(s string) UUID
func NewUUID
func NewUUID() UUID

NewUUID generates a new v4 (random) UUID. Implementations SHOULD utilize UUIDv7 instead of UUIDv1 and UUIDv6 if possible.

func NewUUIDv1
func NewUUIDv1() UUID

NewUUIDv1 generates a new v1 (Gregorian time + random Node) UUID. The timestamp bits are scattered across the first 8 bytes per RFC 4122.

func NewUUIDv1At
func NewUUIDv1At(t time.Time) UUID

NewUUIDv1At generates a v1 UUID encoding the given timestamp. Clock sequence and Node ID are random. This does not participate in monotonic ordering with NewUUIDv1 calls.

func NewUUIDv4
func NewUUIDv4() UUID

NewUUIDv4 generates a new v4 (random) UUID using crypto/rand. Implementations SHOULD utilize UUIDv7 instead of UUIDv1 and UUIDv6 if possible.

func NewUUIDv6
func NewUUIDv6() UUID

NewUUIDv6 generates a new v6 (reordered Gregorian time) UUID. V6 rearranges the v1 timestamp bits into big-endian order for lexicographic sorting.

func NewUUIDv6At
func NewUUIDv6At(t time.Time) UUID

NewUUIDv6At generates a v6 UUID encoding the given timestamp. Clock sequence and Node ID are random. This does not participate in monotonic ordering with NewUUIDv6 calls.

func NewUUIDv7
func NewUUIDv7() UUID

NewUUIDv7 generates a new v7 (timestamp + random) UUID per rfc9562. The first 48 bits encode Unix milliseconds; bytes 6–7 carry the 12-bit sub-millisecond sequence for monotonicity. The remaining bits are random.

func NewUUIDv7At
func NewUUIDv7At(t time.Time) UUID

NewUUIDv7At generates a v7 UUID encoding the given timestamp. The sub-millisecond sequence is derived from the nanosecond component of t. This does not participate in monotonic ordering with NewUUIDv7 calls.

func ParseUUID
func ParseUUID(s string) (UUID, error)

ParseUUID parses a UUID from its string representation. It accepts the canonical form (with dashes) and the 32-hex-digit form (without dashes).

func (UUID) AppendString
func (u UUID) AppendString(dst []byte) []byte

AppendString appends the canonical dash-separated UUID string to dst and returns the extended slice.

func (UUID) Bytes
func (u UUID) Bytes() [16]byte

Bytes returns the raw 16-byte UUID value.

func (UUID) CompareTo
func (u UUID) CompareTo(other any) int

CompareTo implements the Comparable interface.

func (UUID) Equals
func (u UUID) Equals(other UUID) bool

Equals returns true if the two UUIDs have identical bytes.

func (UUID) IsZero
func (u UUID) IsZero() bool

IsZero returns true if the UUID is the zero value (all bytes are 0).

func (UUID) MarshalJSON
func (u UUID) MarshalJSON() ([]byte, error)

MarshalJSON produces the Data API extended JSON format: {"$uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}.

func (UUID) MarshalText
func (u UUID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler. It returns the canonical dash-separated UUID string. This is used by table serialization (as opposed to MarshalJSON which produces the collection {"$uuid": "..."} format).

func (UUID) String
func (u UUID) String() string

String returns the canonical dash-separated UUID string.

func (UUID) Timestamp
func (u UUID) Timestamp() (time.Time, bool)

Timestamp extracts the embedded timestamp from a v1, v6, or v7 UUID. For unsupported versions, it returns the zero time and false.

func (*UUID) UnmarshalJSON
func (u *UUID) UnmarshalJSON(data []byte) error

UnmarshalJSON parses the Data API extended JSON format: {"$uuid": "..."}.

func (*UUID) UnmarshalText
func (u *UUID) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler. It parses a canonical UUID string (with or without dashes).

func (UUID) Version
func (u UUID) Version() int

Version returns the UUID version number (e.g., 4 for v4, 7 for v7).

type Vector

type Vector struct {
	// contains filtered or unexported fields
}

Vector represents a vector that marshals to the {$binary: "..."} format. Internally it stores either a []float32 or a base64 string.

func NewVector
func NewVector(v any) Vector

NewVector creates a Vector from a []float32 or a base64-encoded string. If v is not a supported type, returns zero value vector.

Example usage: 

v1 := datatypes.NewVector([]float32{0.1, 0.2, 0.3})
v2 := datatypes.NewVector("PaPXCr8euFI+x64U")
func (Vector) AppendBase64
func (v Vector) AppendBase64(dst []byte) []byte
func (Vector) AsBase64
func (v Vector) AsBase64() string

AsBase64 returns the vector as a base64-encoded binary string, encoding from floats if necessary.

func (Vector) AsFloatArray
func (v Vector) AsFloatArray() ([]float32, error)

AsFloatArray returns the vector as a []float32, decoding from base64 if necessary.

func (Vector) Dimension
func (v Vector) Dimension() int

Dimension returns the number of float32 elements in the vector.

func (Vector) MarshalJSON
func (v Vector) MarshalJSON() ([]byte, error)

MarshalJSON produces the {$binary: "..."} format, using the stored base64 directly if available.

func (*Vector) UnmarshalJSON
func (v *Vector) UnmarshalJSON(data []byte) error

UnmarshalJSON parses either {$binary: "..."} (stored as base64) or a raw float array (stored as floats), preserving the original representation.