storage

func (*AnalyzeResult) String ¶ added in v0.2.3

func (ar *AnalyzeResult) String() string

String returns a formatted analysis report showing the query plan and execution statistics.

func (Attribute) String ¶

func (a Attribute) String() string

String returns the attribute as a string (if stored directly)

func (*BadgerEmulatorStore) Assert ¶ added in v0.16.0

func (s *BadgerEmulatorStore) Assert(datoms []datalog.Datom) error

func (*BadgerEmulatorStore) AssertEach ¶ added in v0.16.0

func (s *BadgerEmulatorStore) AssertEach(produce func(add func(*datalog.Datom) error) error) error

AssertEach gathers what produce yields and asserts it. Gathering is the whole of it here: entries are a map keyed by encoded key, so there is no incremental structure to build into and a per-datom path would save nothing.

func (*BadgerEmulatorStore) BeginTx ¶ added in v0.16.0

func (s *BadgerEmulatorStore) BeginTx() (StoreTx, error)

func (*BadgerEmulatorStore) Close ¶ added in v0.16.0

func (s *BadgerEmulatorStore) Close() error

func (*BadgerEmulatorStore) DatomsAfter ¶ added in v0.16.0

func (s *BadgerEmulatorStore) DatomsAfter(eid datalog.ElementID) (after []datalog.Datom, afterErr error)

func (*BadgerEmulatorStore) DeleteDatoms ¶ added in v0.16.0

func (s *BadgerEmulatorStore) DeleteDatoms(datoms []datalog.Datom) (int, error)

DeleteDatoms removes each datom's keys from every index, and then any blob those datoms were the last to refer to.

func (*BadgerEmulatorStore) Encoder ¶ added in v0.16.0

func (s *BadgerEmulatorStore) Encoder() *BinaryKeyEncoder

func (*BadgerEmulatorStore) FinishBatch ¶ added in v0.16.0

func (s *BadgerEmulatorStore) FinishBatch() error

FinishBatch has nothing to complete: AssertEach writes its datoms before returning.

func (*BadgerEmulatorStore) GetMetadataUint64 ¶ added in v0.16.0

func (s *BadgerEmulatorStore) GetMetadataUint64(key string) (uint64, bool, error)

func (*BadgerEmulatorStore) MaxElementID ¶ added in v0.16.0

func (s *BadgerEmulatorStore) MaxElementID() (datalog.ElementID, error)

func (*BadgerEmulatorStore) MaxTxForEntity ¶ added in v0.16.0

func (s *BadgerEmulatorStore) MaxTxForEntity(e datalog.Identity) (datalog.ElementID, bool, error)

func (*BadgerEmulatorStore) NewReadSession ¶ added in v0.16.0

func (s *BadgerEmulatorStore) NewReadSession() (ReadSession, error)

NewReadSession opens a consistent read view at the store's current state. Clone mutates the source tree's copy-on-write context, so it runs under the store's write lock, exclusive with committers and other sessions.

func (*BadgerEmulatorStore) Retract ¶ added in v0.16.0

func (s *BadgerEmulatorStore) Retract(datoms []datalog.Datom) error

func (*BadgerEmulatorStore) Scan ¶ added in v0.16.0

func (s *BadgerEmulatorStore) Scan(bound ScanBound) (Iterator, error)

func (*BadgerEmulatorStore) ScanKeysOnly ¶ added in v0.16.0

func (s *BadgerEmulatorStore) ScanKeysOnly(bound ScanBound) (Iterator, error)

func (*BadgerEmulatorStore) SetMetadataUint64 ¶ added in v0.16.0

func (s *BadgerEmulatorStore) SetMetadataUint64(key string, value uint64) error

func (*BadgerIterator) Close ¶

func (i *BadgerIterator) Close() error

Close closes the iterator and releases the underlying BadgerDB transaction. Session-owned iterators return themselves to the session instead — the shared transaction is discarded by the session, not by any one scan. Safe to call multiple times.

func (*BadgerIterator) Datom ¶

func (i *BadgerIterator) Datom() (*datalog.Datom, error)

Datom returns the current datom decoded from the key Values are not stored - all datom information is in the key

func (*BadgerIterator) ElementID ¶ added in v0.6.0

func (i *BadgerIterator) ElementID() datalog.ElementID

ElementID extracts the transaction ElementID from the current key. This is more efficient than Datom() when only the ElementID is needed.

func (*BadgerIterator) Error ¶ added in v0.11.2

func (i *BadgerIterator) Error() error

Error returns nil — BadgerIterator.Next() does not perform any fallible operations; errors surface exclusively through Datom() on the current item. Returning nil satisfies the Iterator interface and tells wrapping iterators there is no deferred error to collect.

func (*BadgerIterator) Key ¶ added in v0.15.0

func (i *BadgerIterator) Key() []byte

Key returns the current index key without decoding the datom or resolving blobs. Valid after Next returns true until the next Next, Seek, or Close.

func (*BadgerIterator) Next ¶

func (i *BadgerIterator) Next() bool

Next advances the iterator

func (*BadgerIterator) Scanned ¶ added in v0.15.2

func (i *BadgerIterator) Scanned() int

Scanned reports keys taken from the index inside this iterator's range.

func (*BadgerIterator) Seek ¶

func (i *BadgerIterator) Seek(key []byte)

Seek positions the iterator at or after the given key

func (*BadgerStore) Assert ¶

func (s *BadgerStore) Assert(datoms []datalog.Datom) error

Assert adds datoms to the store.

func (*BadgerStore) AssertEach ¶ added in v0.15.2

func (s *BadgerStore) AssertEach(produce func(add func(*datalog.Datom) error) error) error

AssertEach writes through a WriteBatch rather than one transaction. A producer yields arbitrarily many datoms, and at eight index keys each plus a blob per out-of-line value, Badger's per-transaction ceiling arrives long before a caller has reason to suspect a limit exists — a single entity's history is enough. The batch splits at that ceiling itself, so the arithmetic stays Badger's and cannot drift from it.

The cost is that this is not atomic: a mid-way failure leaves the datoms already committed in place. Re-asserting is safe, because an index key is derived wholly from its datom and a repeated write reproduces it exactly. A caller that needs a boundary uses BeginTx, whose StoreTx.Assert still writes into the one transaction that caller owns.

func (*BadgerStore) BeginTx ¶

func (s *BadgerStore) BeginTx() (StoreTx, error)

BeginTx starts a new transaction

func (*BadgerStore) Close ¶

func (s *BadgerStore) Close() error

Close closes the store

func (*BadgerStore) CountKeys ¶

func (s *BadgerStore) CountKeys(index IndexType, start, end []byte) (int64, error)

CountKeys counts keys in a range without fetching values (fast counting)

func (*BadgerStore) DatomsAfter ¶ added in v0.13.3

func (s *BadgerStore) DatomsAfter(eid datalog.ElementID) ([]datalog.Datom, error)

DatomsAfter returns every datom whose Tx is strictly greater than eid. It scans TAEV, whose Tx-descending order puts the affected datoms first, and stops at the first datom with Tx <= eid. Read-only; the caller removes them with DeleteDatoms, doing whatever cache/clock coordination it needs in between.

func (*BadgerStore) DeleteDatoms ¶ added in v0.13.3

func (s *BadgerStore) DeleteDatoms(datoms []datalog.Datom) (int, error)

DeleteDatoms physically removes each given datom from all eight indices, returning the count handed over. Unlike Retract (which appends a tombstone at a higher Tx), this is a true rewind: the keys are gone, so the datoms vanish from History() too.

The deletes go through a WriteBatch for the same reason AssertEach's writes do, and it is the delete side that needs it more: a rewind's extent is the whole post-snapshot tail, and at eight index keys per datom the pending-write set is eight times a count the caller has no reason to think is bounded. Badger's per-transaction ceiling arrives around 26,000 datoms. The batch splits at that ceiling itself, so the arithmetic stays Badger's and cannot drift from it.

The cost is that this is not atomic: a mid-way failure leaves the datoms already deleted gone, and History() shows a torn tail until the rewind is re-run. Re-running completes it — TruncateTo restores the clock only after every delete succeeds, so a second pass collects the datoms that survived, and sweepUnreferencedBlobs below reaches the blobs of those that did not, which no pass could name from the datoms it can still see. A reader whose MVCC snapshot lands between chunks can observe a partially deleted tail for the duration.

When the call returns, no blob without a referring datom remains — including blobs this call never touched. The tier is this store's own answer to values too wide for a key, so nothing above the Store seam hears about it.

func (*BadgerStore) Encoder ¶ added in v0.15.0

func (s *BadgerStore) Encoder() *BinaryKeyEncoder

func (*BadgerStore) FinishBatch ¶ added in v0.15.2

func (s *BadgerStore) FinishBatch() error

FinishBatch has nothing to complete: AssertEach flushes its write batch before returning.

func (*BadgerStore) GetMetadataUint64 ¶ added in v0.6.0

func (s *BadgerStore) GetMetadataUint64(key string) (uint64, bool, error)

GetMetadataUint64 retrieves a uint64 metadata value by key. Returns (value, true) if found, (0, false) if not found.

func (*BadgerStore) MaxElementID ¶ added in v0.6.0

func (s *BadgerStore) MaxElementID() (datalog.ElementID, error)

MaxElementID returns the highest ElementID in the store by scanning TAEV index. With bitwise NOT encoding for Tx, forward scan gives highest Tx first (O(1)). Returns zero ElementID if store is empty.

func (*BadgerStore) MaxTxForEntity ¶ added in v0.13.3

func (s *BadgerStore) MaxTxForEntity(e datalog.Identity) (datalog.ElementID, bool, error)

MaxTxForEntity returns the highest Tx among a single entity's datoms. The bool is false when the entity has no datoms. TruncateTo uses it to find the floor below which a snapshot marker must be preserved.

func (*BadgerStore) NewReadSession ¶ added in v0.15.1

func (s *BadgerStore) NewReadSession() (ReadSession, error)

NewReadSession opens a consistent read view at the store's current state.

func (*BadgerStore) Retract ¶

func (s *BadgerStore) Retract(datoms []datalog.Datom) error

Retract removes datoms from the store

func (*BadgerStore) Scan ¶

func (s *BadgerStore) Scan(bound ScanBound) (Iterator, error)

Scan returns a workspace-decoded iterator for a range of keys. Scan and ScanKeysOnly share the same KeyOnlyIterator contract: Datom() returns the iterator's current workspace until Next, Seek, or Close.

func (*BadgerStore) ScanKeysOnly ¶

func (s *BadgerStore) ScanKeysOnly(bound ScanBound) (Iterator, error)

ScanKeysOnly returns an iterator that decodes datoms from keys without fetching values This is much faster than regular scanning as it avoids the redundant value fetch

func (*BadgerStore) SetMetadataUint64 ¶ added in v0.6.0

func (s *BadgerStore) SetMetadataUint64(key string, value uint64) error

SetMetadataUint64 stores a uint64 metadata value by key.

func (*BadgerTx) Assert ¶

func (t *BadgerTx) Assert(datoms []datalog.Datom) error

Assert adds datoms within a transaction. Unlike BadgerStore.Assert this does not split: the caller owns the transaction boundary, so an oversized commit surfaces Badger's ErrTxnTooBig for the caller to handle.

func (*BadgerTx) Commit ¶

func (t *BadgerTx) Commit() error

Commit reclaims any blob this transaction's retracts left unreferenced, then commits. Reclaiming here rather than inside Retract is what lets the count see asserts the same transaction made afterwards.

func (*BadgerTx) Retract ¶

func (t *BadgerTx) Retract(datoms []datalog.Datom) error

Retract removes datoms within a transaction

func (*BadgerTx) Rollback ¶

func (t *BadgerTx) Rollback() error

Rollback rolls back the transaction

func (*BinaryKeyEncoder) DecodeKey ¶

func (e *BinaryKeyEncoder) DecodeKey(index IndexType, key []byte) (entity [20]byte, attr [32]byte, value []byte, tx [16]byte, op byte, afterRef [16]byte, err error)

DecodeKey extracts components from a binary index key. Returns fixed-size arrays for entity, attr, tx, and op to avoid heap escape. tx is 16 bytes: Lamport (8) + ReplicaID (8) = ElementID Tx is stored with bitwise NOT for descending sort, reversed on decode. Op is 1 byte: 0-4 (see CRDTOp constants). Always the LAST byte of every key. AfterRef is optionally present for Op ∈ {OpRGAInsert(3), OpRGATombstone(4)}.

Key formats (Op always last — see docs/reference/OP_POSITION_PROOF.md):

EAVT: [prefix][E][A][type][value][Tx↓][AfterRef?][Op]
EATV: [prefix][E][A][Tx↓][type][value][AfterRef?][Op]
AEVT: [prefix][A][E][type][value][Tx↓][AfterRef?][Op]
AETV: [prefix][A][E][Tx↓][type][value][AfterRef?][Op]
ATEV: [prefix][A][Tx↓][E][type][value][AfterRef?][Op]
AVET: [prefix][A][type][value][E][Tx↓][AfterRef?][Op]
VAET: [prefix][type][value][A][E][Tx↓][AfterRef?][Op]
TAEV: [prefix][Tx↓][A][E][type][value][AfterRef?][Op]

Decoding strategy: Op = key[len-1]. If Op.HasAfterRef(), AfterRef = key[len-17:len-1]. No heuristic needed. No ambiguity.

func (*BinaryKeyEncoder) EncodeKey ¶

func (e *BinaryKeyEncoder) EncodeKey(index IndexType, d *datalog.Datom) []byte

func (*BinaryKeyEncoder) EncodeKeyWithValueBytes ¶ added in v0.11.0

func (e *BinaryKeyEncoder) EncodeKeyWithValueBytes(index IndexType, d *datalog.Datom, vBytes []byte) []byte

EncodeKeyWithValueBytes builds an index key using pre-encoded value bytes. Use this when encoding the same datom into multiple indexes to avoid recomputing compression 7 times.

func (*BinaryKeyEncoder) EncodePrefix ¶

func (e *BinaryKeyEncoder) EncodePrefix(index IndexType, parts ...[]byte) []byte

EncodePrefix creates a binary prefix key for range scans

func (*BinaryKeyEncoder) EncodePrefixRange ¶

func (e *BinaryKeyEncoder) EncodePrefixRange(index IndexType, parts ...[]byte) (start, end []byte)

EncodePrefixRange creates start and end keys for a prefix scan

func (*BinaryKeyEncoder) EncodeScanBound ¶ added in v0.15.2

func (e *BinaryKeyEncoder) EncodeScanBound(b ScanBound) (EncodedRun, error)

EncodeScanBound renders a typed ScanBound as the run a binary-key scan walks: the byte range, and the membership test that narrows a prefix range to the value the bound names. This is the Badger-side projection of the bound; a backend that compares typed components directly never calls it.

func (*BinaryKeyEncoder) EncodeTxForPrefix ¶ added in v0.6.0

func (e *BinaryKeyEncoder) EncodeTxForPrefix(tx Tx) []byte

EncodeTxForPrefix encodes a Tx with bitwise NOT — the form Tx takes inside a key. Higher Tx values encode to lower byte values, so an index that orders Tx yields newest first. encodeBoundComponent renders a bound's Tx component through here, so a bound and the keys it addresses agree on the encoding.

A ScanBound binds Tx to a value; it has no second endpoint. A caller wanting a Tx *range* seeks to one end and walks with its own stop condition, as pull_batch.go does.

func (*BinaryKeyEncoder) EncodeValueBytes ¶ added in v0.11.0

func (e *BinaryKeyEncoder) EncodeValueBytes(v interface{}) (vBytes []byte, blobData *datalog.BlobData)

EncodeKey creates a binary index key from a datom Tx is encoded with bitwise NOT for descending sort order (highest Tx first). Op is always the LAST byte of every key. This enables deterministic decoding: op = key[len(key)-1]. If Op.HasAfterRef(), AfterRef is the 16 bytes before Op.

Key formats (Op always last — see docs/reference/OP_POSITION_PROOF.md):

EAVT: [prefix][E][A][type][value][Tx↓][AfterRef?][Op]  - groups by value for add-wins
EATV: [prefix][E][A][Tx↓][type][value][AfterRef?][Op]  - first entry is current (E-primary CRDT)
AEVT: [prefix][A][E][type][value][Tx↓][AfterRef?][Op]  - by attribute (V before Tx)
AETV: [prefix][A][E][Tx↓][type][value][AfterRef?][Op]  - first entry is current (A-primary CRDT)
ATEV: [prefix][A][Tx↓][E][type][value][AfterRef?][Op]  - Tx↓ ahead of E: AsOf-by-attribute seeks straight to the transaction
AVET: [prefix][A][type][value][E][Tx↓][AfterRef?][Op]  - value lookup
VAET: [prefix][type][value][A][E][Tx↓][AfterRef?][Op]  - reverse refs
TAEV: [prefix][Tx↓][A][E][type][value][AfterRef?][Op]  - transaction log

AfterRef? = 16 bytes present only if Op ∈ {OpRGAInsert(3), OpRGATombstone(4)} EncodeValueBytes computes the V run a key holds for a value: the type tag followed by the payload. Applies compression if enabled. Returns the bytes for the key and optional BlobData for Tier 3 values. Call this once per datom, then pass the result to EncodeKeyWithValueBytes for each index.

The payload carries no length and no terminator. It does not need one: every component behind V in every index layout is fixed width, and Op — the last byte of every key — says whether AfterRef is present, so a key's own length determines where its V ended. DecodeKey recovers V from that arithmetic, and a scan narrows a V-bound prefix range by the same arithmetic (EncodedRun's membership rule). A delimiter would buy exact byte ranges at the cost of the on-disk format.

This is the only producer of a V run. A scan bound's V component goes through it as well, so a bound and the keys it addresses cannot drift apart.

func (*BinaryKeyEncoder) VAETHashPrefix ¶ added in v0.15.3

func (e *BinaryKeyEncoder) VAETHashPrefix(vType datalog.ValueType, hash [20]byte) []byte

VAETHashPrefix returns the VAET key prefix naming every datom whose value is the blob at hash, under one hashed type tag.

VAET leads with the value payload, and a tier-3 payload is the fixed-width [type]hash, so this prefix is exact: every key carrying it references that blob, and no key referencing it under this tag lacks it. That is what makes a reference probe one seek rather than a scan. A caller asking whether a blob is referenced at all probes once per datalog.HashedValueTypes entry, because one blob is reachable under either tag.

func (*CRDTResolvingIterator) Close ¶ added in v0.7.0

func (it *CRDTResolvingIterator) Close() error

Close releases resources held by the iterator.

func (*CRDTResolvingIterator) Datom ¶ added in v0.7.0

func (it *CRDTResolvingIterator) Datom() (*datalog.Datom, error)

Datom returns the current CRDT-resolved datom.

func (*CRDTResolvingIterator) ElementID ¶ added in v0.7.0

func (it *CRDTResolvingIterator) ElementID() datalog.ElementID

ElementID returns the transaction ElementID of the current entry.

func (*CRDTResolvingIterator) Error ¶ added in v0.11.2

func (it *CRDTResolvingIterator) Error() error

Error returns the first error encountered during unique-walk resolution, or nil if iteration proceeded cleanly. Callers that expect walk-based resolution should check this after iterator exhaustion.

func (*CRDTResolvingIterator) Next ¶ added in v0.7.0

func (it *CRDTResolvingIterator) Next() bool

Next advances to the next CRDT-resolved datom.

func (*CRDTResolvingIterator) Scanned ¶ added in v0.15.2

func (it *CRDTResolvingIterator) Scanned() int

Scanned reports the source's intake, and only that.

Resolution reads no index of its own on most paths, and the gap between this and what resolution emitted is the history depth the index made the query pay for. Unique CardinalityOne is the exception — processUniqueEntry opens an AVET supersession scan per Set entry — and those reads accrue into the arm's report at the point they happen, not here.

They cannot be added here. The scan this iterator wraps was acquired through the arm's report, so the source already accrues into it; folding the walk's reads into this total as well would either double-count them or, for an arm reading the report rather than this method, lose them entirely.

func (*CRDTResolvingIterator) Seek ¶ added in v0.7.0

func (it *CRDTResolvingIterator) Seek(bound ScanBound)

Seek positions the iterator at or after the bound's start, discarding the group state accumulated for the run it is leaving. The many state's maps stay for the next group start to empty, so their capacity survives the seek.

func (*Cache) BeginInFlight ¶ added in v0.13.0

func (c *Cache) BeginInFlight(keys []CacheKey)

BeginInFlight marks the given keys as committing by storing the in-flight sentinel for each, overwriting any cached entry. Called by Transaction.Commit BEFORE the storage commit; the matching clear is Invalidate (called after the commit, or after a failed commit), which deletes the entries. While a key's sentinel stands, GetOrResolve resolves it from storage and storeIfNotInFlight refuses to cache it. Another commit's Invalidate or a drop of the key's slot can clear the sentinel before this commit's UpdateMaxVersion records the arrival.

func (*Cache) Clear ¶ added in v0.6.0

func (c *Cache) Clear()

Clear removes all entries from the cache. It raises the floor first, so a resolution that read before the clear is not stored afterward.

func (*Cache) ForView ¶ added in v0.16.2

func (c *Cache) ForView() *Cache

ForView creates the cache of a view as of a target over c's database. It holds the view's resolutions alone, so they are freed with the view, and it reads c's record of the arrivals on each key.

func (*Cache) GetCachedAttrs ¶ added in v0.6.0

func (c *Cache) GetCachedAttrs(e datalog.Identity) map[datalog.Keyword]bool

GetCachedAttrs returns the set of attributes we've cached for an entity Returns nil if no attributes are cached for this entity

func (*Cache) GetOrResolve ¶ added in v0.6.0

func (c *Cache) GetOrResolve(key CacheKey, def *schema.AttributeDefinition, resolver CacheResolver, readPoint datalog.ElementID, handler annotations.Handler, report *scanReport) (*CacheEntry, error)

GetOrResolve returns the cached entry if fresh, rebuilding if stale. In a view's cache it is getOrResolveForView.

def is the attribute's definition as the caller holds it, nil for an attribute its schema does not declare. Its cardinality and uniqueness are the rule the caller resolves the attribute under. An entry resolved under another rule is not a hit: a set's view serves no reader under cardinality one, and a value the unique walk settled serves no reader under the plain rule, so the entry is rebuilt under def's.

readPoint is the read point the caller took before it read: before its session opened, or now for a reader of the latest store. An entry serves the caller when no datom arrived on its key after the read point, which makes it the value the caller's session holds. Otherwise the caller resolves through its resolver, and the cache stores that resolution only when no datom arrived on the key after the read point.

An arrival clears its key's entry, and a resolution is stored only when it read every arrival, so an entry present and not in flight holds every datom of its key. False negatives (returning stale data) are NOT acceptable. The report accrues the index intake *this call* spends: the entry's build cost when this call built it, and nothing when the entry came from cache. It is not entry.scanned, which is the entry's build cost forever. The distinction is the difference between "what this read cost" and "what this (E, A) cost to resolve once, some time ago", and datoms.scanned means the first everywhere else in the engine — a trace of a thousand hits must not report a thousand index reads that did not happen.

Accrual happens inside the resolvers, so a rebuild that fails keeps what it read; the callers that report nothing pass DiscardIntake and say so.

func (*Cache) Invalidate ¶ added in v0.6.0

func (c *Cache) Invalidate(touched []CacheKey)

Invalidate removes cached entries for the given keys, another commit's in-flight sentinel included, and leaves each slot's version where it stands. Called by Database on tx.Commit() with all touched (E,A) pairs.

func (*Cache) InvalidateAttribute ¶ added in v0.11.2

func (c *Cache) InvalidateAttribute(a datalog.Keyword)

InvalidateAttribute removes all cached entries for the given attribute, regardless of entity. Used when a write to a unique attribute may have silently staled other entities' cached values under the walk-based (A, V)-LWW resolution.

Conservative strategy (CRDT_UNIQUE_SEMANTICS.md D3): one unique-attr write invalidates every cached entry for that attribute. A future optimization could maintain an (A, V) → [E] reverse index to invalidate only the entities whose walks could actually change; the current approach is simpler and correct.

It raises the floor before it drops the attribute's slots, so a resolution of another entity's key that read before the write is not stored, whether or not the key had a slot.

func (*Cache) InvalidateRewind ¶ added in v0.13.3

func (c *Cache) InvalidateRewind(touched []CacheKey)

InvalidateRewind drops the slots of keys whose datoms a rollback physically removed, once the removal is readable. It raises the floor first, so a resolution that read the removed datoms is not stored for them. Pairs with BeginInFlight: that opens the uncached window before the delete, this closes it after.

func (*Cache) PopulateFromDatoms ¶ added in v0.10.0

func (c *Cache) PopulateFromDatoms(key CacheKey, card datalog.Keyword, datoms []datalog.Datom, readPoint datalog.ElementID)

PopulateFromDatoms resolves a group of datoms for a single (E, A) pair and stores the result in the cache. Uses the canonical Resolve*FromDatoms functions from crdt_resolve.go — no CRDT logic duplication.

This is the dispatch target for PrefetchEntities: as the EATV iterator crosses an attribute boundary, the accumulated datoms are resolved and cached here in a single call.

readPoint is the read point the caller took before it began reading the datoms.

func (*Cache) ReadPoint ¶ added in v0.16.2

func (c *Cache) ReadPoint() datalog.ElementID

ReadPoint is the read point of a reader of the latest store that begins now.

func (*Cache) TrackEntityAttr ¶ added in v0.6.0

func (c *Cache) TrackEntityAttr(e datalog.Identity, a datalog.Keyword)

TrackEntityAttr records that we have cached an (E, A) entry Called when storing cache entries to track what's cached per entity

func (*Cache) UpdateMaxVersion ¶ added in v0.6.0

func (c *Cache) UpdateMaxVersion(key CacheKey, arrival datalog.ElementID)

UpdateMaxVersion records an arrival of datoms on key. arrival is an ElementID drawn from the database's clock once the datoms are readable. The slot's version rises to it, and the slot's entry, which may lack the datoms, is dropped; an in-flight sentinel stays for its commit to clear.

func (*CacheEntry) Cardinality ¶ added in v0.6.0

func (e *CacheEntry) Cardinality() datalog.Keyword

Cardinality returns the cardinality of this cache entry

func (*CacheEntry) ManySet ¶ added in v0.6.0

func (e *CacheEntry) ManySet() map[string]any

ManySet returns the set for cardinality-many attributes, each member under its memberKey.

func (*CacheEntry) ManyTx ¶ added in v0.16.3

func (e *CacheEntry) ManyTx() map[string]datalog.ElementID

ManyTx returns, under each member's memberKey, the Tx of the member's newest assertion for cardinality-many attributes.

func (*CacheEntry) OneTx ¶ added in v0.16.3

func (e *CacheEntry) OneTx() datalog.ElementID

OneTx returns the Tx of the datom a cardinality-one entry resolves to.

func (*CacheEntry) OneValue ¶ added in v0.6.0

func (e *CacheEntry) OneValue() any

OneValue returns the value for cardinality-one attributes

func (*CacheEntry) VectorIndex ¶ added in v0.6.0

func (e *CacheEntry) VectorIndex() []datalog.ElementID

VectorIndex returns the position index for cardinality-vector attributes

func (*CacheEntry) VectorList ¶ added in v0.6.0

func (e *CacheEntry) VectorList() []any

VectorList returns the ordered list for cardinality-vector attributes

func (*CacheEntry) Version ¶ added in v0.6.0

func (e *CacheEntry) Version() datalog.ElementID

Version returns the ElementID when this entry was computed

func (*Database) Analyze ¶ added in v0.2.3

func (d *Database) Analyze(queryInput interface{}, inputs ...interface{}) (*AnalyzeResult, error)

Analyze executes a query and returns detailed execution statistics. The query can be either an EDN string or a *query.Query from the query builder. This is like EXPLAIN ANALYZE in PostgreSQL - it actually runs the query and captures timing information at each step.

Example:

result, err := db.Analyze(`[:find ?e :in $ ?scenario :where [?e :task/scenario ?scenario]]`, scenarioID)
if err != nil { ... }
fmt.Println(result.String())  // Shows plan + execution trace

The result includes:

• Query plan with index selection
• Query result as a Relation (call .Size() or iterate to access)
• Event trace with timing for each operation
• Summary statistics

func (*Database) AsOf ¶

func (d *Database) AsOf(target datalog.ElementID) *Database

AsOf returns a read-only Database handle that queries state as of the given transaction. The returned handle uses CRDT resolution filtered to that point in causal time.

The temporal handle shares the parent's store and schema. It keeps its resolutions in a cache of its own over the parent's (Cache.ForView), so they are freed with the handle and every arrival the parent's cache records reaches them. With the parent's cache disabled the handle has none. It supports reads (Query, NewExecutor, NewExecutorWithOptions, Matcher, Pull) but not writes: NewTransaction will panic. Close is a no-op — the parent owns the store lifetime.

func (*Database) AsOfSnapshot ¶ added in v0.13.3

func (d *Database) AsOfSnapshot(name string) (*Database, error)

AsOfSnapshot returns a read-only handle viewing the database as of the named snapshot. The returned handle rejects writes (NewTransaction panics on a temporal handle).

It reads at the marker's own high-water (snapshotMarkerMax), which is domain-equivalent to the captured point At — the marker datoms it adds are reserved-namespace and filtered from domain queries. An as-of handle carries its target beside its mode, so a handle at the zero ElementID, an empty-database snapshot's At, reads nothing: every datom lies after the target (shouldFilterTx).

func (*Database) AsOfTx ¶ added in v0.16.1

func (d *Database) AsOfTx() (txID datalog.ElementID, ok bool)

AsOfTx reports the transaction an AsOf handle reads as of, and whether this handle is one. The live database reads the store as it stands, and a History handle reads every datom ever written, so neither reads as of a transaction and ok is false for both.

func (*Database) Assert ¶ added in v0.8.0

func (d *Database) Assert(datoms []datalog.Datom) error

Assert adds datoms in a single transaction.

func (*Database) AttributeLookup ¶ added in v0.16.3

func (d *Database) AttributeLookup(attr datalog.Keyword) (query.AttributeLookup, error)

AttributeLookup implements executor.EntityLookupMatcher for a database passed as a named source, answering through its matcher.

func (*Database) Cache ¶ added in v0.6.0

func (d *Database) Cache() *Cache

Cache returns the CRDT resolution cache. Used by the matcher for O(1) access to resolved CRDT views.

func (*Database) CanFuseAttributeFetch ¶ added in v0.16.2

func (d *Database) CanFuseAttributeFetch(source query.Symbol, attr datalog.Keyword) bool

CanFuseAttributeFetch implements executor.AttributeFetchFusable for a database passed as a named source, answering through its matcher: whether a match of attr on the database answers, per entity, the one value its lookup answers, under the schema it runs with and in its view.

func (*Database) ClearPlanCache ¶

func (d *Database) ClearPlanCache()

ClearPlanCache clears the query plan cache

func (*Database) Clock ¶ added in v0.6.0

func (d *Database) Clock() *LamportClock

Clock returns the Lamport clock for CRDT operations. Returns nil if the database was created without CRDT support.

func (*Database) Close ¶

func (d *Database) Close() error

Close closes the database.

On a temporal handle (AsOf/History), Close is a no-op — the parent owns the store lifetime. Closing a temporal handle must not close the shared underlying store.

func (*Database) DeleteSnapshot ¶ added in v0.13.3

func (d *Database) DeleteSnapshot(name string) (deleteErr error)

DeleteSnapshot removes the named snapshot from the registry by retracting its marker. The rewindable timeline is untouched; only the registry entry goes away.

func (*Database) Explain ¶ added in v0.2.3

func (d *Database) Explain(queryInput interface{}, inputs ...interface{}) (*planner.RealizedPlan, error)

Explain returns the query plan for a query without executing it. The query can be either an EDN string or a *query.Query from the query builder. This is useful for understanding index selection, phase structure, and how input parameters affect symbol binding.

Example:

plan, err := db.Explain(`[:find ?e :in $ ?scenario :where [?e :task/scenario ?scenario]]`, scenarioID)
if err != nil { ... }
fmt.Println(plan.String())  // Human-readable plan output

The plan shows:

• Index selection (EAVT, AEVT, AVET, VAET, TAEV)
• Selectivity scores for patterns
• Symbol availability and binding through phases
• Predicate and expression assignment

func (*Database) ExplainAlgebra ¶ added in v0.15.1

func (d *Database) ExplainAlgebra(queryInput interface{}, inputs ...interface{}) (*planner.AlgebraExplanation, error)

ExplainAlgebra returns, without executing, the full record of what planning does to a query: the relational algebra it compiles to, every rewrite decision the optimization passes made (applied, or declined with the failed precondition), the optimized tree, the Datalog it decompiles back to, and the physical plan — all as values. The query can be either an EDN string or a *query.Query from the query builder.

Example:

expl, err := db.ExplainAlgebra(`[:find ?s (max ?h) :in $ :where ...]`)
if err != nil { ... }
fmt.Println(expl.String())          // full rendering
for _, r := range expl.Rewrites {   // typed transform provenance
    fmt.Println(r.Pass, r.Action, r.Reason)
}

When this database's planner options disable the algebra optimizer, the explanation carries the compiled algebra view only (the algebra of a query is a fact about the query), no rewrites, and the physical plan exactly as this database would produce it.

func (*Database) Export ¶ added in v0.5.6

func (d *Database) Export(w io.Writer, opts ...ExportOptions) error

Export writes all datoms in the database to EDN format. With no options, values are serialized as plain EDN strings. With Compressed: true, large strings use #lzj tagged literals.

func (*Database) ExportBinary ¶ added in v0.15.0

func (d *Database) ExportBinary(w io.WriteSeeker, opts ...BinaryExportOptions) (exportErr error)

ExportBinary writes the complete EAVT datom log as a seekable JDZL file. w must be an io.WriteSeeker so the trailer index offset can be patched.

func (*Database) ExportCompressed ¶ added in v0.11.0

func (d *Database) ExportCompressed(w io.Writer) error

ExportCompressed is a convenience alias for Export with Compressed: true. To filter entities during compressed export, use Export directly with ExportOptions.

func (*Database) Fork ¶ added in v0.15.4

func (d *Database) Fork(name string) (branch *Database, err error)

Fork starts a branch from the snapshot named name.

The branch holds what this database held as of the snapshot, the state AsOfSnapshot reads, and neither sees what the other commits afterward. It opens as any database does, with this database's given schema declared into it where its store lacks it, and runs with the schema its store states; it plans with this database's planner options and carries its own EA cache. It writes as a replica of its own: a fresh ReplicaID, and a clock started past every ElementID it holds, so every write it makes orders after everything it inherited.

Fork records the fork in this database: the snapshot's name, the point the snapshot captured, the point the branch holds this database's state as of, and the branch's ReplicaID. While a snapshot of that name holds the captured point, TruncateTo refuses to pass the branch's point; deleting the snapshot, or a later take of its name that captures another point, releases the branch. Fork opens the transaction that records the branch before it looks up the snapshot, so a TruncateTo that starts holding writers while the Fork runs waits for the record. A Fork begun after a TruncateTo starts holding writers is refused with ErrRollbackInProgress. An AsOf or History handle is read-only and cannot fork, and neither can a store with no way to start a branch.

func (*Database) GetBool ¶ added in v0.8.0

func (d *Database) GetBool(e datalog.Identity, a datalog.Keyword) (bool, bool, error)

GetBool returns a bool attribute value.

func (*Database) GetFloat ¶ added in v0.8.0

func (d *Database) GetFloat(e datalog.Identity, a datalog.Keyword) (float64, bool, error)

GetFloat returns a float64 attribute value.

func (*Database) GetInt ¶ added in v0.8.0

func (d *Database) GetInt(e datalog.Identity, a datalog.Keyword) (int64, bool, error)

GetInt returns an int64 attribute value.

func (*Database) GetRef ¶ added in v0.8.0

func (d *Database) GetRef(e datalog.Identity, a datalog.Keyword) (datalog.Identity, bool, error)

GetRef returns an entity reference attribute value.

func (*Database) GetString ¶ added in v0.8.0

func (d *Database) GetString(e datalog.Identity, a datalog.Keyword) (string, bool, error)

GetString returns a string attribute value.

func (*Database) GetStrings ¶ added in v0.8.0

func (d *Database) GetStrings(e datalog.Identity, a datalog.Keyword) ([]string, error)

GetStrings returns all string values for a cardinality-many attribute.

func (*Database) GetVectorLength ¶ added in v0.6.0

func (d *Database) GetVectorLength(e datalog.Identity, a datalog.Keyword) (int64, error)

GetVectorLength returns the length of a vector attribute as the handle reads it, through the handle's own matcher, so an as-of handle answers as of its target. Uses the cache for O(1) access when the cache is fresh. Returns 0 if the attribute holds no vector, and an error if the attribute is not a vector. An attribute wider than storage holds is refused before any read, and a database that refuses unknown attributes refuses an attribute its schema does not declare, as every typed accessor does.

func (*Database) GetVectorNth ¶ added in v0.6.0

func (d *Database) GetVectorNth(e datalog.Identity, a datalog.Keyword, n int64) (any, error)

GetVectorNth returns the nth element of a vector attribute as the handle reads it, through the handle's own matcher, so an as-of handle answers as of its target. Uses the cache for O(1) access when the cache is fresh. Returns nil if the index is out of bounds or the attribute holds no vector, and an error if the attribute is not a vector. An attribute wider than storage holds is refused before any read, and a database that refuses unknown attributes refuses an attribute its schema does not declare, as every typed accessor does.

func (*Database) History ¶ added in v0.2.0

func (d *Database) History() *Database

History returns a read-only Database handle that returns all raw datoms without CRDT resolution. Every write is visible, including superseded values.

The temporal handle shares the parent's underlying store, cache, and schema. It supports reads (Query, NewExecutor, NewExecutorWithOptions, Matcher, Pull) but not writes: NewTransaction will panic. Close is a no-op — the parent owns the store lifetime.

func (*Database) Import ¶ added in v0.5.6

func (d *Database) Import(r io.Reader) error

Import loads an EDN dump into the database (replayEDN) and then composes the schema the database runs with from the definitions the dump carried, under a given schema if one was declared, whose facts take ElementIDs past the restored clock and so supersede the imported ones for the idents it names.

func (*Database) ImportBinary ¶ added in v0.15.0

func (d *Database) ImportBinary(r io.ReadSeeker, opts ...BinaryImportOptions) error

ImportBinary reads a JDZL file and asserts its datoms. r must be an io.ReadSeeker. Chunks are decoded and asserted in parallel up to Workers.

The first worker error cancels remaining launches and in-flight work between steps, then that error is returned. Import is not transactional across chunks: workers that already Asserted leave a nondeterministic partial subset of the file in the store. Retrying into the same database is not a safe recovery; use a fresh database (or discard the target) after failure.

func (*Database) ImportDump ¶ added in v0.15.2

func (d *Database) ImportDump(r io.ReadSeeker) error

ImportDump loads an exported dump (replayDump) and then composes the schema the database runs with from the definitions the dump carried, under a given schema if one was declared.

func (*Database) LookupAttribute ¶ added in v0.16.2

func (d *Database) LookupAttribute(entity datalog.Identity, attr datalog.Keyword) (interface{}, bool, error)

LookupAttribute implements executor.EntityLookupMatcher for a database passed as a named source, answering through its matcher.

func (*Database) LookupByUnique ¶ added in v0.11.2

func (d *Database) LookupByUnique(attr datalog.Keyword, value interface{}) (datalog.Identity, error)

Pull retrieves entity data according to a pull pattern This provides Datomic-style entity attribute retrieval with nested reference following.

The pattern syntax:

• Simple attributes: [:entity/name :entity/code]
• Wildcard: [*] - all attributes
• Nested references: [{:entity/region [:region/code :region/name]}]
• Default values: [(default :entity/status "unknown")]
• Limits (for cardinality-many): [(limit :entity/tags 10)]

Examples:

// Get name and code for an entity
result, err := db.Pull(entityID, `[:entity/name :entity/code]`)

// Get all attributes
result, err := db.Pull(entityID, `[*]`)

LookupByUnique returns the entity currently owning (attr, value) under (A, V)-LWW resolution. Returns a nil Identity with a nil error if no entity currently claims the value.

The attribute must be declared unique in the schema (UniqueValue or UniqueIdentity). Calling LookupByUnique on a non-unique attribute, an attribute not present in the schema, or a database without a schema returns an error.

LookupByUnique is the primitive for natural-key lookup in the CRDT model: application-layer upsert ("find-or-create by email") is built on top of it. See docs/proposals/CRDT_UNIQUE_SEMANTICS.md for the design rationale.

Concurrent writers may change the canonical owner between calls; treat the result as a snapshot. If an application needs to verify a write "won," it should call LookupByUnique after the commit and compare the returned Identity to its own.

func (*Database) LookupSource ¶ added in v0.16.2

func (d *Database) LookupSource(source query.Symbol) (executor.EntityLookupMatcher, error)

LookupSource implements executor.EntityLookupMatcher for a database passed as a named source: it is one source, so its matcher is the lookup of the source under any name, and get-else, missing? and get-some on that source read it, a get-else default typed by the schema it runs with.

func (*Database) Match ¶ added in v0.5.6

func (d *Database) Match(q *query.Query, bindings executor.Relations) (executor.Relation, error)

Match implements executor.PatternMatcher — the Database itself can answer pattern queries. This delegates to the Database's Matcher(), which uses the full BadgerDB index infrastructure.

func (*Database) Matcher ¶

func (d *Database) Matcher() executor.PatternMatcher

Matcher returns the default-source pattern matcher, configured from the database's effective planner options (override or defaults) so the relations it produces carry the same executor options the query runs with — not a hardcoded default set.

func (*Database) NewExecutor ¶

func (d *Database) NewExecutor() *executor.Executor

NewExecutor creates a new query executor under the database's effective options, with its plan cache and its registered annotation handler.

func (*Database) NewExecutorWithOptions ¶

func (d *Database) NewExecutorWithOptions(opts planner.PlannerOptions) *executor.Executor

NewExecutorWithOptions creates a new query executor with custom planner options and the database's plan cache.

Builds the pattern matcher from the same custom options via matcherWithExecOptions, so the executor and the matcher's relations agree on the effective options — including opts.Handler, which reaches every relation either constructs — and schema, cache, and temporal mode (AsOf/History) are all applied. The matcher carries whether the database refuses unknown attributes, and the executor has its plans carry their rosters when it does, for the check at its entry.

func (*Database) NewTransaction ¶

func (d *Database) NewTransaction() *Transaction

NewTransaction starts a new write transaction. It opens a read session, which holds the value the transaction's view reads until Commit or Rollback. A transaction begun while a TruncateTo holds writers is dropped: it opens no session, and its writes and every read of its view answer ErrRollbackInProgress.

Panics if called on a read-only temporal handle (AsOf/History). Temporal views share the parent's store and have no write-side state; use the parent handle for writes.

func (*Database) NewTransactionAt ¶

func (d *Database) NewTransactionAt(t time.Time) *Transaction

NewTransactionAt starts a new write transaction with a specific time This is a convenience method for financial/temporal data

func (*Database) ParseCache ¶ added in v0.9.0

func (d *Database) ParseCache() *ParseCache

ParseCache returns the database's query parse cache

func (*Database) PlanCache ¶

func (d *Database) PlanCache() *planner.PlanCache

PlanCache returns the database's query plan cache

func (*Database) Pull ¶ added in v0.2.0

func (d *Database) Pull(entityID datalog.Identity, patternStr string) (map[string]interface{}, error)

// Get attributes with nested reference
result, err := db.Pull(entityID, `[:entity/name {:entity/region [:region/code]}]`)

Returns nil if the entity does not exist.

func (*Database) PullInto ¶ added in v0.2.0

func (d *Database) PullInto(entityID datalog.Identity, v interface{}) error

PullInto retrieves entity data and populates the provided struct. The struct fields are mapped to attributes based on datalog struct tags. A pull pattern is automatically generated from the struct definition. Schema is used to properly handle cardinality-many attributes.

Example:

type Person struct {
    ID      datalog.Identity `datalog:"-,id"`
    Name    string           `datalog:"name"`
    Age     int64            `datalog:"age"`
    Friends []*Person        `datalog:"friends"`
}
var person Person
err := db.PullInto(entityID, &person)

func (*Database) PullIntoMany ¶ added in v0.2.0

func (d *Database) PullIntoMany(entityIDs []datalog.Identity, v interface{}) error

PullIntoMany retrieves data for multiple entities and populates the provided slice. The slice must be a pointer to a slice of structs (e.g., *[]Person or *[]*Person). Schema is used to properly handle cardinality-many attributes.

Example:

var people []Person
err := db.PullIntoMany(entityIDs, &people)

func (*Database) PullMany ¶ added in v0.2.0

func (d *Database) PullMany(entityIDs []datalog.Identity, patternStr string) ([]map[string]interface{}, error)

PullMany retrieves data for multiple entities using the same pull pattern This is more efficient than calling Pull multiple times.

Example:

results, err := db.PullMany(
    []datalog.Identity{entity1, entity2, entity3},
    `[:entity/name :entity/code]`,
)

Returns a slice of maps, one per entity. Nil entries indicate non-existent entities.

func (*Database) Query ¶ added in v0.8.0

func (d *Database) Query(queryInput interface{}, inputs ...interface{}) (executor.Relation, error)

Query executes a Datalog query and returns a streaming Relation. The caller should iterate via rel.Iterator() and must call iter.Close() when done. A registered handler sees the query invoked once and completed once: refused or failed before the result exists, or, for a query that runs, when the result's iterator is exhausted or closed.

func (*Database) QueryInto ¶ added in v0.2.0

func (d *Database) QueryInto(dest interface{}, queryInput interface{}, inputs ...interface{}) (err error)

QueryInto executes a Datalog query and populates a slice of structs with the results. The query can be either an EDN string or a *query.Query from the query builder. Fields are mapped by `datalog` tags (e.g., `datalog:"?name"`) or by position if untagged.

For aggregates, use the full expression as the tag (e.g., `datalog:"(sum ?salary)"`).

Example:

type PersonResult struct {
    Name string `datalog:"?name"`
    Age  int64  `datalog:"?age"`
}

var results []PersonResult
err := db.QueryInto(&results, `[:find ?name ?age :where [?e :person/name ?name] [?e :person/age ?age]]`)

Example with query builder:

e, name, age := qb.NewVar("e"), qb.NewVar("name"), qb.NewVar("age")
q := qb.Query().Find(name, age).Where(qb.Pat(e, PersonName, name), qb.Pat(e, PersonAge, age)).MustBuild()
err := db.QueryInto(&results, q)

Example with aggregates:

type DeptStats struct {
    Dept     string  `datalog:"?dept"`
    TotalPay float64 `datalog:"(sum ?salary)"`
}

var stats []DeptStats
err := db.QueryInto(&stats, `[:find ?dept (sum ?salary) :where [?e :employee/dept ?dept] [?e :employee/salary ?salary]]`)

func (*Database) QueryOneInto ¶ added in v0.2.0

func (d *Database) QueryOneInto(dest interface{}, queryInput interface{}, inputs ...interface{}) (found bool, err error)

QueryOneInto executes a Datalog query expecting at most one result and populates a value. The query can be either an EDN string or a *query.Query from the query builder. Supports both struct destinations (multi-symbol) and scalar destinations (single-symbol). Returns (true, nil) if a result was found and mapped successfully. Returns (false, nil) if the query returns no results (empty result is valid, not an error). Returns (false, ErrMultipleResults) if more than one result exists. Returns (false, err) for other errors (parse errors, type errors, etc.).

Example (struct):

var result PersonResult
found, err := db.QueryOneInto(&result, `[:find ?name ?age :where ...]`)

Example (scalar):

var name string
found, err := db.QueryOneInto(&name, `[:find ?name :where [?e :person/name ?name] [(= ?e eid)]]`)

func (*Database) RefusesUnknownAttributes ¶ added in v0.16.0

func (d *Database) RefusesUnknownAttributes(_ query.Symbol) bool

RefusesUnknownAttributes implements executor.AttributeVocabulary for a database passed as a named source: it refuses when opened with RefuseUnknownAttributes.

func (*Database) ReplicaID ¶ added in v0.6.0

func (d *Database) ReplicaID() uint64

ReplicaID returns this database's replica identifier for CRDT operations. Each database instance should have a unique ReplicaID for proper multi-replica merge semantics. The ID is auto-generated if not specified in DatabaseOptions.

func (*Database) ResolveAllAttributes ¶ added in v0.6.0

func (d *Database) ResolveAllAttributes(entity datalog.Identity) (resolved map[datalog.Keyword]interface{}, resolveErr error)

ResolveAllAttributes retrieves all CRDT-resolved attributes for an entity. This is used by wildcard pulls to get all attributes with proper CRDT resolution.

The attributes answered are the entity's own, kept to the set wildcardAttributes builds when the store declares any. In history mode an EAVT scan discovers them and ResolveEntityAttributes resolves each; otherwise one walk of the entity's EATV range discovers and resolves them, the batch wildcard walk applied to one entity. Per the codebase principle that the cache is an optimization, not a correctness requirement, this method works correctly under DisableCache: true.

Returns a map of keyword -> resolved value. The value type depends on cardinality:

• CardinalityOne: single value (LWW)
• CardinalityMany: []interface{} (add-wins set)
• CardinalityVector: []interface{} (RGA ordered list)

func (*Database) ResolveAllAttributesMany ¶ added in v0.14.2

func (d *Database) ResolveAllAttributesMany(
	entities []datalog.Identity,
) ([]map[datalog.Keyword]interface{}, error)

ResolveAllAttributesMany resolves wildcard pulls for a complete entity set. The dominant non-unique EATV traversal shares one store scan session and seeks forward per entity; unique-ownership walks and blob dereferences retain their specialized reads. Results preserve input order. Duplicate entities are scanned once.

func (*Database) ResolveEntityAttributes ¶ added in v0.6.0

func (d *Database) ResolveEntityAttributes(entity datalog.Identity, attrs []datalog.Keyword) (map[datalog.Keyword]interface{}, error)

ResolveEntityAttributes resolves CRDT values for the requested attributes of an entity. This is the core resolution method that properly applies CRDT semantics: - CardinalityOne: LWW (Last-Writer-Wins) - CardinalityMany: Add-wins set - CardinalityVector: RGA ordered list

With the cache on, it partitions the attributes by what the cache has tracked for the entity, and resolves each attribute of both parts through GetOrResolve, which serves a fresh entry and resolves from storage otherwise.

Returns a map of keyword -> resolved value. Missing attributes are not included. An attribute asked that is wider than storage holds is refused before any read, and a database that refuses unknown attributes refuses every attribute asked that its schema does not declare, joined in order, as every typed accessor does.

func (*Database) Schema ¶ added in v0.2.0

func (d *Database) Schema() schema.SchemaProvider

Schema returns the current schema (may be nil)

func (*Database) SetParseCache ¶ added in v0.9.0

func (d *Database) SetParseCache(cache *ParseCache)

SetParseCache sets a custom parse cache or disables caching (if nil)

func (*Database) SetPlanCache ¶

func (d *Database) SetPlanCache(cache *planner.PlanCache)

SetPlanCache sets a custom plan cache or disables caching (if nil)

func (*Database) SetSchema ¶ added in v0.2.0

func (d *Database) SetSchema(s schema.SchemaProvider) error

SetSchema declares s as the database's schema: its definitions are asserted into the store, superseding the stored ones for the idents it names, and the schema the database runs with is composed from both. A nil s withdraws the given schema, and the database runs with the store's definitions and what the ops of the other attributes infer; a database that refuses unknown attributes keeps a schema to check against and refuses nil, and a schema declaring an engine word is refused, each before anything changes, so a refused call leaves the given schema as it was. Schema changes take effect for new transactions. A read-only temporal handle has no store of its own to assert into and is refused.

func (*Database) Snapshot ¶ added in v0.13.3

func (d *Database) Snapshot(name string) (snap SnapshotInfo, snapErr error)

Snapshot names the current state of this handle as a :db.snapshot/* entity. It captures store.MaxElementID() as the snapshot point and writes the marker in a single transaction. Returns ErrSnapshotExists if the name is already in use.

func (*Database) Snapshots ¶ added in v0.13.3

func (d *Database) Snapshots() ([]SnapshotInfo, error)

Snapshots lists every snapshot, in causal order (by captured point, then name).

func (*Database) Stats ¶

func (d *Database) Stats() (map[string]interface{}, error)

Stats returns database statistics

func (*Database) Store ¶

func (d *Database) Store() Store

Store returns the underlying store for direct access (debugging/testing)

func (*Database) TruncateTo ¶ added in v0.13.3

func (d *Database) TruncateTo(name string) error

TruncateTo destructively rewinds this handle's writable timeline to the named snapshot. Every datom written after the snapshot's own marker is PHYSICALLY removed (not tombstoned), so it disappears from History() as well as from current reads; the clock resumes from the snapshot point so the next write does not collide. Snapshots taken after the target are pruned along with the timeline they indexed; the target snapshot and earlier ones survive. The record of a fork from a surviving snapshot survives with it, since a TruncateTo past that snapshot reads the record. See docs/proposals/BRANCHING_AND_SNAPSHOTS.md §12.1 (Slice B).

Concurrency (§12.1, "Rollback safety"): TruncateTo serializes against other rollbacks (rollbackMu), drains in-flight write transactions, and drops writes started while it runs (they return ErrRollbackInProgress). An in-flight write opened before the rollback is allowed to commit; its post-snapshot datoms are then erased like any other Tx > markerMax. Reads are never locked — BadgerDB MVCC keeps them consistent, and the cache in-flight window (BeginInFlight → delete → InvalidateRewind) keeps them from caching a soon-to-be- stale value while the rewind is visible mid-flight.

func (*Database) UnknownAttributes ¶ added in v0.16.0

func (d *Database) UnknownAttributes(_ query.Symbol, attrs []datalog.Keyword) error

UnknownAttributes implements executor.AttributeVocabulary for a database passed as a named source. Opened with RefuseUnknownAttributes, it refuses every attribute of the roster that its store does not declare and the engine does not reserve, joined in order; otherwise it refuses nothing, and the roster is not read.

func (*Database) WarmCache ¶ added in v0.6.0

func (d *Database) WarmCache(attributes []datalog.Keyword) error

WarmCache pre-populates cache entries for the specified attributes. Use this after process restart for attributes with high query frequency to avoid cold-start latency on first access.

For each attribute, this scans all entities and populates per-(E,A) cache entries with resolved CRDT values, each resolved through the handle's own matcher, so an as-of handle's entries hold the values as of its target.

This is O(n) where n = total datoms for the specified attributes. Call during application startup, not on the hot path.

A History handle resolves nothing, so its matcher refuses every cache key (cacheKey) and the call stores nothing.

With DisableCache there is no cache to warm and the call does nothing. Every other reader of d.cache in this file resolves from storage instead, because the cache is an optimization rather than a correctness requirement; warming has no such fallback, since warming is the whole of what it does.

func (Entity) String ¶

func (e Entity) String() string

String returns the entity as hex string (first 8 bytes)

func (IndexType) String ¶ added in v0.15.2

func (i IndexType) String() string

String names the index. It is the one rendering of an IndexType, so %v in an error or an annotation reads "AVET" rather than "5" — the numbering is an implementation detail of the key prefix and means nothing to a reader.

func (JoinStrategy) String ¶

func (js JoinStrategy) String() string

func (*KeyOnlyIterator) Close ¶ added in v0.15.0

func (i *KeyOnlyIterator) Close() error

func (*KeyOnlyIterator) Datom ¶

func (i *KeyOnlyIterator) Datom() (*datalog.Datom, error)

func (*KeyOnlyIterator) Error ¶ added in v0.11.2

func (i *KeyOnlyIterator) Error() error

func (*KeyOnlyIterator) Key ¶ added in v0.15.0

func (i *KeyOnlyIterator) Key() []byte

func (*KeyOnlyIterator) Next ¶

func (i *KeyOnlyIterator) Next() bool

Next advances to the next key the run holds, stepping over the keys its byte range over-covers.

func (*KeyOnlyIterator) Seek ¶ added in v0.15.0

func (i *KeyOnlyIterator) Seek(bound ScanBound)

func (*LamportClock) Current ¶ added in v0.6.0

func (c *LamportClock) Current() uint64

Current returns the current clock value without incrementing. This is the Lamport timestamp that would be returned by the PREVIOUS Next() call. The NEXT Next() call will return Current() + 1.

Thread-safe: uses atomic load.

func (*LamportClock) Next ¶ added in v0.6.0

func (c *LamportClock) Next() ElementID

Next generates the next ElementID for a local event. Implements rule 1: L = L + 1 before each event.

This is the primary method for generating timestamps during writes. Each call returns a unique, monotonically increasing ElementID.

Thread-safe: uses atomic increment.

func (*LamportClock) Peek ¶ added in v0.6.0

func (c *LamportClock) Peek() ElementID

Peek returns what the next ElementID would be without consuming it. Equivalent to ElementID{Lamport: Current() + 1, ReplicaID: ReplicaID()}.

Note: In a concurrent environment, the actual next ElementID may differ if another goroutine calls Next() between Peek() and your Next() call.

func (*LamportClock) ReadPoint ¶ added in v0.16.2

func (c *LamportClock) ReadPoint() ElementID

ReadPoint returns the greatest ElementID at the clock's current Lamport time. Every ElementID drawn so far, on any replica, is at or below it, and every ElementID this clock draws later is above it.

Thread-safe: uses atomic load.

func (*LamportClock) Receive ¶ added in v0.6.0

func (c *LamportClock) Receive(remote ElementID)

Receive updates the clock when receiving data from another node. Implements rule 3: L = max(L, L_remote) + 1

This is the critical Lamport property: receiving a message is an event, and the receiver's clock must be greater than both its previous value AND the sender's timestamp.

Use this when merging data from another replica. After Receive(), subsequent Next() calls will return ElementIDs greater than the remote.

Thread-safe: uses compare-and-swap loop.

func (*LamportClock) ReplicaID ¶ added in v0.6.0

func (c *LamportClock) ReplicaID() uint64

ReplicaID returns this clock's replica identifier. This is set at construction time and never changes.

func (*LamportClock) Restore ¶ added in v0.6.0

func (c *LamportClock) Restore(maxSeen ElementID)

Restore sets the clock to a known value without incrementing. Used ONLY for restoring state on database reopen, NOT for receiving messages.

Unlike Receive(), Restore() does not add 1. This is intentional: - Receive() models a causal event (message receipt) → must advance - Restore() models state recovery (not a causal event) → just set value

After Restore(maxSeen), the next Next() call returns maxSeen.Lamport + 1.

Thread-safe: uses compare-and-swap loop.

func (*MemoryTreeStore) Assert ¶ added in v0.15.2

func (s *MemoryTreeStore) Assert(datoms []datalog.Datom) error

Assert adds datoms. Every datom enters all eight orders in one batch, so the version that publishes them is indivisible.

func (*MemoryTreeStore) AssertEach ¶ added in v0.15.2

func (s *MemoryTreeStore) AssertEach(produce func(add func(*datalog.Datom) error) error) error

AssertEach adds what produce yields to the open batch, leaving the batch open for the next call; FinishBatch publishes it, and until then the run is invisible: readers hold the previously published version.

A batch over an empty base gathers its datoms — duplicate-free, the dump format's own property, trusted rather than swept for — and builds every index in one sorted pass at FinishBatch, leaves packed full. A batch over existing data inserts per datom into the version being built, paying one copy-on-write generation for the whole run.

func (*MemoryTreeStore) BeginTx ¶ added in v0.15.2

func (s *MemoryTreeStore) BeginTx() (StoreTx, error)

func (*MemoryTreeStore) Close ¶ added in v0.15.2

func (s *MemoryTreeStore) Close() error

func (*MemoryTreeStore) DatomsAfter ¶ added in v0.15.2

func (s *MemoryTreeStore) DatomsAfter(eid datalog.ElementID) (after []datalog.Datom, afterErr error)

DatomsAfter returns every datom committed after eid, in TAEV order.

TAEV orders Tx descending, so the walk starts at the newest and stops at the first entry not after eid — everything past that point is older still.

func (*MemoryTreeStore) DeleteDatoms ¶ added in v0.15.2

func (s *MemoryTreeStore) DeleteDatoms(datoms []datalog.Datom) (int, error)

DeleteDatoms removes exactly the datoms given — matched on every component, Tx included — and reports how many were there.

func (*MemoryTreeStore) Encoder ¶ added in v0.15.2

func (s *MemoryTreeStore) Encoder() *BinaryKeyEncoder

func (*MemoryTreeStore) FinishBatch ¶ added in v0.15.2

func (s *MemoryTreeStore) FinishBatch() error

FinishBatch publishes an open batch, and is what makes a run of AssertEach calls visible. With no batch open there is nothing to publish and it says so by doing nothing.

func (*MemoryTreeStore) Fork ¶ added in v0.15.4

func (s *MemoryTreeStore) Fork(ceiling datalog.ElementID) (Store, error)

Fork returns a branch store holding what this store's published version held as of ceiling, and writing independently of this store. It starts from the published version and deletes from its own trees every datom written past ceiling, the rewind TruncateTo performs. Neither store sees what the other commits afterward: a version is immutable, and a builder copies every node it did not create, so the two share each node until one of them writes beneath it. A batch AssertEach left open is not published, and the fork does not hold it.

The fork starts with no metadata. The replica id is a store's write identity, and a branch writes as a replica of its own, assigned by the Database that opens it. The encoder is shared: it is configuration, read and never written.

func (*MemoryTreeStore) GetMetadataUint64 ¶ added in v0.15.2

func (s *MemoryTreeStore) GetMetadataUint64(key string) (uint64, bool, error)

GetMetadataUint64 and SetMetadataUint64 sit outside the version. The only key is the replica id, written and read at database open, so it never reaches a query path and cannot participate in a torn snapshot.

func (*MemoryTreeStore) MaxElementID ¶ added in v0.15.2

func (s *MemoryTreeStore) MaxElementID() (datalog.ElementID, error)

func (*MemoryTreeStore) MaxTxForEntity ¶ added in v0.15.2

func (s *MemoryTreeStore) MaxTxForEntity(e datalog.Identity) (datalog.ElementID, bool, error)

func (*MemoryTreeStore) NewReadSession ¶ added in v0.15.2

func (s *MemoryTreeStore) NewReadSession() (ReadSession, error)

NewReadSession retains the current version. Every read through the session walks that one state however many batches commit afterward — the snapshot is a held pointer, not a lock and not a copy.

func (*MemoryTreeStore) Retract ¶ added in v0.15.2

func (s *MemoryTreeStore) Retract(datoms []datalog.Datom) error

Retract physically removes every stored datom sharing an (E, A, V) with one of those given, whatever its Tx.

This is deletion, not a CRDT Remove: nothing is tombstoned and the history is gone. Visible deletion in a user transaction is an OpCRDTRemove datom, which Assert writes like any other; truncate removes through DeleteDatoms. See BUG_RETRACT_NAMES_TWO_OPPOSITE_OPERATIONS on the name.

func (*MemoryTreeStore) Scan ¶ added in v0.15.2

func (s *MemoryTreeStore) Scan(bound ScanBound) (Iterator, error)

func (*MemoryTreeStore) ScanKeysOnly ¶ added in v0.15.2

func (s *MemoryTreeStore) ScanKeysOnly(bound ScanBound) (Iterator, error)

ScanKeysOnly is Scan. The distinction exists for a backend whose values live apart from its keys; a tree holds whole datoms, so there is nothing to skip fetching and nothing to defer.

func (*MemoryTreeStore) SetMetadataUint64 ¶ added in v0.15.2

func (s *MemoryTreeStore) SetMetadataUint64(key string, value uint64) error

func (*ParseCache) Clear ¶ added in v0.9.0

func (c *ParseCache) Clear()

Clear removes every cached query and rule set.

func (*ParseCache) Get ¶ added in v0.9.0

func (c *ParseCache) Get(queryString string) (*query.Query, bool)

Get retrieves a cached *query.Query for the given query string.

func (*ParseCache) GetRules ¶ added in v0.16.0

func (c *ParseCache) GetRules(text string) (*query.RuleSet, bool)

GetRules retrieves the cached *query.RuleSet for the given rule text.

func (*ParseCache) Set ¶ added in v0.9.0

func (c *ParseCache) Set(queryString string, q *query.Query)

Set stores a parsed *query.Query for the given query string, under the cache's one bound.

func (*ParseCache) SetRules ¶ added in v0.16.0

func (c *ParseCache) SetRules(text string, rs *query.RuleSet)

SetRules stores a parsed *query.RuleSet for the given rule text, under the cache's one bound.

func (*ParseCache) Stats ¶ added in v0.9.0

func (c *ParseCache) Stats() (hits, misses int64, size int)

Stats returns cache statistics: the hits and misses across both arms, and the entries both hold.

func (*PatternMatcher) AsOf ¶ added in v0.15.2

func (m *PatternMatcher) AsOf(target datalog.ElementID) *PatternMatcher

AsOf is a copy of this matcher reading the view as of target: each attribute resolved over the datoms at or before it.

func (*PatternMatcher) AttachReadSession ¶ added in v0.15.2

func (m *PatternMatcher) AttachReadSession(session ReadSession, readPoint datalog.ElementID)

AttachReadSession routes every subsequent storage read this matcher performs through the session, so the whole query observes one snapshot. readPoint is the read point the caller took before it opened the session: cache reads bound themselves to it (see cacheBound), so the shared EA cache serves this matcher only entries on whose key nothing arrived after it, and stores its resolutions only when nothing arrived after it. The caller owns the session's lifecycle; the matcher only reads through it.

func (*PatternMatcher) AttributeLookup ¶ added in v0.16.3

func (m *PatternMatcher) AttributeLookup(attr datalog.Keyword) (query.AttributeLookup, error)

AttributeLookup returns the lookup of attr, which answers at each entity what LookupAttribute answers for that entity and attr.

func (*PatternMatcher) CanFuseAttributeFetch ¶ added in v0.15.2

func (m *PatternMatcher) CanFuseAttributeFetch(_ query.Symbol, attr datalog.Keyword) bool

CanFuseAttributeFetch reports whether a match of attr on the matcher answers, per entity, the one value LookupAttribute answers: true in the latest and as-of views for an attribute the matcher resolves cardinality-one, whether its schema defines it so or holds no definition of it, since LookupAttribute and CRDTResolvingIterator both resolve an attribute with no definition by LWW. On an as-of matcher both read the datoms at or before its target. False for a cardinality-many attribute, whose match answers each member as a tuple of its own, for a cardinality-vector attribute, and on a History matcher, whose match answers every datom. The matcher is one source and answers for itself under any name, so the source is not read.

func (*PatternMatcher) ForceJoinStrategy ¶ added in v0.15.2

func (m *PatternMatcher) ForceJoinStrategy(strategy *JoinStrategy)

ForceJoinStrategy overrides the join strategy selection for testing Pass nil to restore default behavior

func (*PatternMatcher) GetCardinality ¶ added in v0.15.2

func (m *PatternMatcher) GetCardinality(attr datalog.Keyword) datalog.Keyword

GetCardinality returns the cardinality an attribute resolves under: the one its definition declares, and CardinalityOne for an attribute the schema does not declare or a matcher with no schema.

func (*PatternMatcher) History ¶ added in v0.15.2

func (m *PatternMatcher) History() *PatternMatcher

History is a copy of this matcher reading every datom as written, with no resolution: every version is visible, superseded and withdrawn ones included.

func (*PatternMatcher) LookupAllAttributes ¶ added in v0.15.2

func (m *PatternMatcher) LookupAllAttributes(
	entity datalog.Identity,
	attr datalog.Keyword,
) (values []interface{}, lookupErr error)

LookupAllAttributes retrieves all values of a cardinality-many attribute for an entity. Returns all matching values, or empty slice if none found.

func (*PatternMatcher) LookupAttribute ¶ added in v0.15.2

func (m *PatternMatcher) LookupAttribute(entity datalog.Identity, attr datalog.Keyword) (interface{}, bool, error)

LookupAttribute answers an entity's value of an attribute, the lookup the database functions get-else, missing? and get-some read. It answers (value, true) when the attribute holds a value and (nil, false) otherwise. A cardinality-one attribute, and one the schema holds no definition of, answers its current value by LWW. A cardinality-many attribute answers its current members as one value, in no fixed order. A cardinality-vector attribute answers its vector, typed by the schema's value type, once the vector has been written, an emptied vector included.

func (*PatternMatcher) LookupSource ¶ added in v0.16.2

func (m *PatternMatcher) LookupSource(_ query.Symbol) (executor.EntityLookupMatcher, error)

LookupSource implements executor.EntityLookupMatcher: the matcher is one source, so it is the lookup of the source under any name.

func (*PatternMatcher) Match ¶ added in v0.15.2

func (m *PatternMatcher) Match(q *query.Query, bindings executor.Relations) (executor.Relation, error)

Match implements PatternMatcher.Match - returns a Relation directly

func (*PatternMatcher) MatchWithConstraints ¶ added in v0.15.2

func (m *PatternMatcher) MatchWithConstraints(
	q *query.Query,
	bindings executor.Relations,
	constraints []executor.StorageConstraint,
) (executor.Relation, error)

MatchWithConstraints implements predicate-aware matching with storage-level filtering

func (*PatternMatcher) PrefetchEntities ¶ added in v0.15.2

func (m *PatternMatcher) PrefetchEntities(entities []datalog.Identity) error

PrefetchEntities loads all attributes for a set of entities into the EA cache in a single-pass EATV scan per entity. Entities are sorted by raw hash byte order (= disk order) for efficient forward-only iteration through BadgerDB.

CRDT resolution happens inline as attribute boundaries are crossed during iteration — no second pass. Each (E, A) group is dispatched to Cache.PopulateFromDatoms which uses the canonical Resolve*FromDatoms functions.

See ALGEBRA.md "Rule 6: Entity Prefetch into EA Cache" for design rationale.

The first storage failure aborts the prefetch and returns it: an error from the store means the store is broken, and callers fail the query — prefetch being an optimization does not make store failures ignorable. Groups cached before the failure hold valid data.

func (*PatternMatcher) RefusesUnknownAttributes ¶ added in v0.16.0

func (m *PatternMatcher) RefusesUnknownAttributes(_ query.Symbol) bool

RefusesUnknownAttributes implements executor.AttributeVocabulary: the matcher is one source and answers for itself under any name, refusing on a database opened with RefuseUnknownAttributes.

func (*PatternMatcher) ResolveAddWins ¶ added in v0.15.2

func (m *PatternMatcher) ResolveAddWins(e datalog.Identity, a datalog.Keyword, report *scanReport) (map[string]any, map[string]datalog.ElementID, datalog.ElementID, bool, error)

ResolveAddWins returns the current set members for cardinality-many, each under its memberKey, and each member's newest assertion's Tx under the same key, through resolveAddWinsSet.

func (*PatternMatcher) ResolveLWW ¶ added in v0.15.2

func (m *PatternMatcher) ResolveLWW(e datalog.Identity, a datalog.Keyword, def *schema.AttributeDefinition, report *scanReport) (v any, tx datalog.ElementID, version datalog.ElementID, present bool, resolveErr error)

ResolveLWW returns the current value for cardinality-one (highest ElementID wins), given def, the attribute's definition, nil for an attribute the schema does not declare.

When def declares no unique, and in History, it uses the EATV first-entry shortcut (highest Tx due to descending sort). History reads raw assertions with no resolution, so the unique walk would produce values corresponding to no datom. When def declares a unique and the matcher reads resolved state, it delegates to walkUniqueEntityValue for walk-based resolution: the returned value is the entity's first non-superseded assertion, which may fall back to an older entry if the latest has been claimed by another entity.

tx is the Tx of the datom the pair resolves to, the assertion the value was read from or the withdrawal that left it nil, and is what a pattern's transaction position reads. version is the highest ElementID the resolution read, the datom's own Tx under the plain rule and, under the walk, other entities' superseding claims included; it is what the cache's freshness reads. A unique pair no assertion of which survives the rule resolves to no datom, so its tx is the zero ElementID.

func (*PatternMatcher) ResolveRGA ¶ added in v0.15.2

func (m *PatternMatcher) ResolveRGA(e datalog.Identity, a datalog.Keyword, report *scanReport) ([]any, []datalog.ElementID, datalog.ElementID, bool, error)

ResolveRGA returns the ordered vector for cardinality-vector Returns (values, positionToElementID, maxElementID, present, error)

func (*PatternMatcher) SetCache ¶ added in v0.15.2

func (m *PatternMatcher) SetCache(c *Cache)

SetCache sets the CRDT resolution cache for O(1) access to resolved views. When cache is set, LookupAttribute() and related methods check the cache before scanning storage, providing O(1) access for cache hits.

func (*PatternMatcher) SetSchema ¶ added in v0.15.2

func (m *PatternMatcher) SetSchema(s schema.SchemaProvider)

SetSchema sets the schema for cardinality-aware index selection. When schema is set, the matcher uses EATV for cardinality-one attributes and EAVT for cardinality-many attributes (for add-wins resolution).

func (*PatternMatcher) TypeDefault ¶ added in v0.15.2

func (m *PatternMatcher) TypeDefault(attr datalog.Keyword, defaultVal interface{}) interface{}

TypeDefault converts a default value to match the attribute's schema type. For vector attributes with TypeString, converts []interface{} to []string, etc. This implements query.TypedDefaulter, which get-else asks of the lookup of the source it reads.

func (*PatternMatcher) UnknownAttributes ¶ added in v0.16.0

func (m *PatternMatcher) UnknownAttributes(_ query.Symbol, attrs []datalog.Keyword) error

UnknownAttributes implements executor.AttributeVocabulary. On a database opened with RefuseUnknownAttributes it refuses every attribute of the roster that the store does not declare and the engine does not reserve, joined in order. On any other database it refuses nothing, and the roster is not read. The matcher is one source and answers for itself under any name.

func (RGAElement) IsDeleted ¶ added in v0.6.0

func (e RGAElement) IsDeleted() bool

IsDeleted returns true if this element has been tombstoned.

func (RGAElement) String ¶ added in v0.6.0

func (e RGAElement) String() string

String returns a human-readable representation of the element.

func (ReuseType) String ¶

func (rt ReuseType) String() string

func (SetEntry) IsAdd ¶ added in v0.6.0

func (e SetEntry) IsAdd() bool

IsAdd returns true if this is an add operation

func (SetEntry) IsRemove ¶ added in v0.6.0

func (e SetEntry) IsRemove() bool

IsRemove returns true if this is a remove operation

func (SetEntry) String ¶ added in v0.6.0

func (e SetEntry) String() string

String returns a human-readable representation

func (StorageDatom) Bytes ¶

func (d StorageDatom) Bytes() []byte

Bytes returns the serialized form of the storage datom Format: E(20) + A(32) + Tx(16) + VSize(2) + VType(1) + V(variable)

func (StorageDatom) String ¶

func (d StorageDatom) String() string

String returns a string representation of the StorageDatom

func (StorageDatom) ToDatom ¶

func (d StorageDatom) ToDatom(resolver Resolver) datalog.Datom

ToDatom converts a storage datom to user-facing representation This requires a resolver to map hashes back to meaningful names

func (*Transaction) Add ¶

func (t *Transaction) Add(e datalog.Identity, a datalog.Keyword, v interface{}) error

Add adds a value using schema-aware CRDT semantics. The schema determines the semantics - callers don't need to know the cardinality.

Behavior by cardinality: - Cardinality-One: LWW semantics (highest ElementID wins) - Cardinality-Many: Add-wins set semantics (value added with OpCRDTAdd) - Cardinality-Vector: RGA append semantics (element chained after previous in tx)

For schemaless attributes (no schema or attribute not defined in schema), Add() stores the raw value with LWW semantics (cardinality-one behavior).

func (*Transaction) AddEntity ¶

func (t *Transaction) AddEntity(e datalog.Identity, attrs map[datalog.Keyword]interface{}) error

AddEntity adds all datoms for an entity map

func (*Transaction) AddMap ¶

func (t *Transaction) AddMap(attrs map[string]interface{}) (datalog.Identity, error)

AddMap is a convenience method that creates an entity ID and adds the attributes

func (*Transaction) Commit ¶

func (t *Transaction) Commit() (datalog.ElementID, error)

Commit commits the transaction's writes and a :db/txInstant mark in one storage transaction, and returns the mark's ElementID, the point at which AsOf reads the commit. A transaction holding no write commits nothing and returns the store's highest ElementID.

func (*Transaction) LookupAllAttributes ¶ added in v0.16.2

func (t *Transaction) LookupAllAttributes(e datalog.Identity, a datalog.Keyword) ([]interface{}, error)

LookupAllAttributes answers e's values of a as this transaction holds them, resolved as LookupAttribute resolves them: a cardinality-many attribute's members in no fixed order, a vector's elements in order, and any other attribute's value alone. It answers no values when the attribute holds none. Like LookupAttribute, it holds t.mu only while it copies the transaction's own datoms of a, and a closed transaction answers an error.

func (*Transaction) LookupAttribute ¶ added in v0.16.2

func (t *Transaction) LookupAttribute(e datalog.Identity, a datalog.Keyword) (interface{}, bool, error)

LookupAttribute answers e's value of a as this transaction holds it: the resolution of the datoms of (e, a) in the value it opened on together with its own writes. It answers (value, true) when the attribute holds a value and (nil, false) otherwise. A cardinality-one attribute, and one the schema holds no definition of, answers its value. A cardinality-many attribute answers its members as one value, in no fixed order. A cardinality-vector attribute answers its vector, typed by the schema's value type, once the view holds a datom of it, an emptied vector included. It holds t.mu only while it copies the transaction's own datoms of a (pendingOf), and reads the value it opened on through its read session without the lock. A closed transaction answers an error.

func (*Transaction) Remove ¶ added in v0.6.0

func (t *Transaction) Remove(e datalog.Identity, a datalog.Keyword, v interface{}) error

Remove removes a value using CRDT tombstone semantics.

Behavior by cardinality: - Cardinality-One: Writes OpCRDTRemove; attribute doesn't exist if tombstone has highest Tx - Cardinality-Many: Writes OpCRDTRemove; add-wins resolves per-value conflicts - Cardinality-Vector: RGA LIFO tombstone; removes most recently added matching element - Schemaless/undefined: Defaults to CardinalityOne

func (*Transaction) Retract ¶

func (t *Transaction) Retract(e datalog.Identity, a datalog.Keyword, v interface{}) error

Retract removes a datom

func (*Transaction) Rollback ¶

func (t *Transaction) Rollback() error

Rollback aborts the transaction

func (*Transaction) SaveStruct ¶ added in v0.2.0

func (t *Transaction) SaveStruct(v interface{}) (datalog.Identity, error)

SaveStruct persists a struct to the database with upsert semantics. Each field is compared against this transaction's view of the entity (LookupAttribute, LookupAllAttributes): the value it opened on with its own writes applied. It writes only what the struct changes in that view, so a field the struct holds unchanged leaves another writer's change to it standing. If the struct has an ID field (tagged with `datalog:"-,id"`) and it's empty, a new ID is generated. The generated or existing ID is returned and also set on the struct's ID field.

Upsert behavior:

• Cardinality-one fields: asserts the value when it differs from the view's
• Cardinality-many fields (nil slice): leaves existing values unchanged
• Cardinality-many fields (empty slice): withdraws every member the view holds
• Cardinality-many fields (non-empty): adds the members the view lacks and withdraws the ones the slice lacks

Example:

person := Person{Name: "Alice", Age: 30}
id, err := tx.SaveStruct(&person)
// person.ID is now set to the generated identity

// Later, modify and save again
person.Name = "Alice Smith"
id, err = tx.SaveStruct(&person)  // Updates name, age unchanged

func (*Transaction) Set ¶ added in v0.6.0

func (t *Transaction) Set(e datalog.Identity, a datalog.Keyword, v interface{}) error

Set sets a value for a cardinality-one attribute using CRDT LWW semantics. For cardinality-one: just appends the new value. The storage layer handles Last-Writer-Wins resolution - no read-before-write or retraction needed.

This method is part of the CRDT implementation: - Cardinality-One: Highest ElementID wins (LWW semantics) - Cardinality-Many: Replaces entire set (diffs against the set the transaction holds, generates Add/Remove ops) - Cardinality-Vector: Replaces entire vector

func (*Transaction) SetTime ¶

func (t *Transaction) SetTime(txTime time.Time)

SetTime sets a custom transaction time for this transaction This is useful for backdated data (e.g., historical prices)

func (Tx) String ¶

func (tx Tx) String() string

String returns a string representation of Tx (ElementID format)

func (Tx) ToElementID ¶ added in v0.6.0

func (tx Tx) ToElementID() datalog.ElementID

ToElementID converts Tx to ElementID

func (Tx) Uint64 ¶

func (tx Tx) Uint64() uint64

Uint64 returns the Lamport component of the transaction ID as uint64