Documentation
¶
Overview ¶
Package types defines the small value types lakeorm exposes on its public API: SortableID (KSUID-backed), ObjectURI/Location (typed storage addresses), and SparkTableName. Kept in its own package so downstream code can import types without pulling in the driver/format/backend stack.
Index ¶
- Constants
- func SortableIDsToStrings(ids []SortableID) []string
- type IngestID
- type Location
- type SortableID
- func (id SortableID) Bytes() []byte
- func (id SortableID) Compare(other *SortableID) int
- func (id SortableID) IsNil() bool
- func (id SortableID) KSUID() ksuid.KSUID
- func (id SortableID) MarshalJSON() ([]byte, error)
- func (id SortableID) MarshalText() ([]byte, error)
- func (id *SortableID) Scan(src any) error
- func (id SortableID) String() string
- func (id *SortableID) UnmarshalJSON(data []byte) error
- func (id *SortableID) UnmarshalText(text []byte) error
- func (id SortableID) Value() (driver.Value, error)
Constants ¶
const SystemIngestIDColumn = "_ingest_id"
SystemIngestIDColumn is the reserved name for lake-orm's per-operation ingest_id column. Every table lake-orm creates carries this column, populated with a UUIDv7 per Insert call. User structs must NOT declare it — the column is synthesised at DDL time by each dialect and stamped at write time by the driver layer.
Reconciliation queries that want the column on the read side declare a separate result-shape struct with a field tagged `lake:"_ingest_id"`. The root scanner drops unmapped columns for structs that don't, so Query[T] over a T that ignores _ingest_id returns clean typed rows.
Variables ¶
This section is empty.
Functions ¶
func SortableIDsToStrings ¶
func SortableIDsToStrings(ids []SortableID) []string
SortableIDsToStrings converts a slice of SortableID to a slice of strings.
Types ¶
type IngestID ¶
type IngestID string
IngestID is the per-operation correlation token every Client.Insert generates. The underlying representation is a UUIDv7 — the leading 48 bits are a Unix-millisecond timestamp, which makes staging prefixes time-sortable in object-storage listings and lets the janitor (Client.CleanupStaging) identify orphans by parsing the timestamp out of a prefix name. No separate state file required.
Every write plan carries the IngestID; the driver stamps it onto every row it writes (direct-ingest stamps per prepared INSERT, parquet-ingest stamps on the parquet stage's synthesised _ingest_id field). The MERGE source is filtered by the same IngestID so retry-on-OCC-conflict is idempotent.
The string form is the canonical UUIDv7 hyphenated representation (e.g. "0193abc0-1234-7def-8901-234567890abc"). Drivers read the string form; types.IngestID is the typed wrapper callers see.
func NewIngestID ¶
NewIngestID generates a fresh UUIDv7 IngestID. Returns an error only if the underlying crypto/rand draw fails, which in practice means the process is unable to read entropy — an unrecoverable state callers can surface to their own error path.
func (IngestID) String ¶
String returns the canonical hyphenated UUIDv7 representation and satisfies fmt.Stringer for log formatting.
func (IngestID) Timestamp ¶
Timestamp decodes the 48-bit unix_ts_ms header from the UUIDv7 and returns the embedded moment. Used by CleanupStaging to identify prefixes older than a TTL without a state file.
Returns the zero time if the underlying string is not a valid UUIDv7 — callers that care about the distinction check Valid() first.
type Location ¶
type Location struct {
Scheme string // "s3", "gs", "file", "memory"
Bucket string // bucket/container/root — empty for "file" and "memory"
Path string // object key or filesystem path under Bucket
}
Location is a typed storage URI — scheme + bucket + path. It's the coordinate that Client and Driver must agree on at the string level, regardless of whether they resolve to the same physical endpoint via the same credentials. See lakeorm.Verify for the reachability probe that surfaces the mismatch cleanly.
func ParseLocation ¶
ParseLocation parses a canonical URI ("s3://bucket/key", "gs://bucket/key", "file:///abs/path", "memory://name/key") into a Location.
type SortableID ¶
type SortableID string
SortableID is a KSUID stored as its canonical base62 string. KSUIDs sort lexicographically in creation order, which is what makes them suitable for primary keys, idempotency tokens, and ingest IDs on object-storage prefixes (so lexicographic S3 listings match temporal order).
func NewSortableID ¶
func NewSortableID() SortableID
NewSortableID returns a freshly generated KSUID.
func ParseSortableID ¶
func ParseSortableID(s string) (SortableID, error)
ParseSortableID validates and returns a SortableID from a string.
func (SortableID) Bytes ¶
func (id SortableID) Bytes() []byte
Bytes returns the 20 raw KSUID bytes, or nil if the ID is zero.
func (SortableID) Compare ¶
func (id SortableID) Compare(other *SortableID) int
Compare returns -1/0/1 by lexicographic string order (KSUIDs are time-sortable).
func (SortableID) IsNil ¶
func (id SortableID) IsNil() bool
IsNil reports whether the ID is the zero value (empty or ksuid.Nil).
func (SortableID) KSUID ¶
func (id SortableID) KSUID() ksuid.KSUID
KSUID returns the underlying ksuid.KSUID (or ksuid.Nil on error / empty).
func (SortableID) MarshalJSON ¶
func (id SortableID) MarshalJSON() ([]byte, error)
func (SortableID) MarshalText ¶
func (id SortableID) MarshalText() ([]byte, error)
func (*SortableID) Scan ¶
func (id *SortableID) Scan(src any) error
Scan implements sql.Scanner for database/sql. Needed for the reflection scanner in scanner.go to pick SortableID up via its scannerTarget path (nullable SortableID columns become *SortableID fields transparently).
func (SortableID) String ¶
func (id SortableID) String() string
func (*SortableID) UnmarshalJSON ¶
func (id *SortableID) UnmarshalJSON(data []byte) error
func (*SortableID) UnmarshalText ¶
func (id *SortableID) UnmarshalText(text []byte) error
Source Files