collections

package
v0.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 1, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// DefaultIndexedWriteMemtableMaxDocuments bounds the native indexed
	// collection write-domain before it auto-flushes to persistent roots.
	DefaultIndexedWriteMemtableMaxDocuments = 96000
	// DefaultIndexedWriteMemtableAsyncFlushMaxDocuments uses a larger publish
	// cadence for async indexed flushes. Background publishing decouples writer
	// staging from root apply enough that larger immutable flush units reduce
	// root-apply amplification without penalizing synchronous/checkpoint-heavy
	// insert shapes that still use DefaultIndexedWriteMemtableMaxDocuments.
	DefaultIndexedWriteMemtableAsyncFlushMaxDocuments = 256000
	// DefaultIndexedWriteMemtableMaxRootRuns bounds accumulated root-local
	// mutation runs. When the document threshold is also enabled, hitting this
	// limit compacts mutable root runs in memory before publishing so many small
	// indexed update batches do not create an expensive pending-run chain before
	// the document threshold is reached.
	DefaultIndexedWriteMemtableMaxRootRuns = DefaultIndexedWriteMemtableMaxDocuments
	// DefaultIndexedWriteMemtableAsyncFlushMaxRootRuns pairs with
	// DefaultIndexedWriteMemtableAsyncFlushMaxDocuments.
	DefaultIndexedWriteMemtableAsyncFlushMaxRootRuns = DefaultIndexedWriteMemtableAsyncFlushMaxDocuments
	// DefaultIndexedWriteMemtableDirectBatchDocuments keeps large, already
	// well-amortized InsertBatch calls on the immediate publish path. Smaller
	// batches use the indexed write-domain memtable path by default.
	DefaultIndexedWriteMemtableDirectBatchDocuments = 16000
	// DefaultIndexedWriteMemtableAccumulatorBatchDocuments keeps small indexed
	// InsertBatch calls from creating one frozen root run per call. Larger
	// batches already amortize sorted frozen runs well and keep that path.
	DefaultIndexedWriteMemtableAccumulatorBatchDocuments = 1024
	// DefaultIndexedWriteMemtableAccumulatorLockedPlanningDocuments lets the
	// single-document accumulator path keep planning locked while uncontended,
	// avoiding a relock/catalog-validation round trip once per insert. Larger
	// calls can release the mutation lock while planning.
	DefaultIndexedWriteMemtableAccumulatorLockedPlanningDocuments = 1

	// DefaultIndexedWriteMemtableAsyncFlushMaxQueuedUnits bounds default
	// background indexed flush work. When the queue reaches this many immutable
	// flush units, the triggering writer publishes synchronously to cap memory
	// and visibility lag.
	DefaultIndexedWriteMemtableAsyncFlushMaxQueuedUnits = 4
)
View Source 
const (
	ColumnRetainedPayloadNonColumn ColumnRetainedPayloadPolicy = "non-column"
	ColumnRetainedPayloadFull      ColumnRetainedPayloadPolicy = "full"
	ColumnRetainedPayloadNone      ColumnRetainedPayloadPolicy = "none"

	// ColumnRetainedPayloadEncodingJSON records retained payload bodies stored as
	// JSON objects after applying the retained-payload policy.
	ColumnRetainedPayloadEncodingJSON = "json"
	// ColumnRetainedPayloadEncodingTemplateV1 records retained payload bodies
	// stored as Template-v1 documents with templates in the collection template root.
	ColumnRetainedPayloadEncodingTemplateV1 = "template-v1"
	// ColumnRetainedPayloadEncodingSemanticStreamV1 records multi-row retained
	// payload bodies as semantic path streams in a dedicated collection root.
	// Side-root blocks may be legacy raw crss1blk blocks or crss1zst blocks
	// containing a zstd-compressed crss1blk payload.
	ColumnRetainedPayloadEncodingSemanticStreamV1 = "semantic-stream-v1"
	// ColumnRetainedPayloadEncodingNone records that no retained body is active.
	ColumnRetainedPayloadEncodingNone = "none"
	// ColumnRetainedPayloadEncodingUnavailable is a reporting sentinel for
	// unsupported or unrecognized retained-payload encoding metadata.
	ColumnRetainedPayloadEncodingUnavailable = "unavailable"
)
View Source 
const (
	// ScalarU8AlphaPolicyMaxAbs uses the maximum absolute normalized component in
	// each existing storage/layout granule as that granule's alpha.
	ScalarU8AlphaPolicyMaxAbs ScalarU8AlphaPolicyName = "max_abs"
	// ScalarU8AlphaPolicyAbsQuantile uses a fixed allowed high quantile of absolute
	// normalized components. The quantile parameter is encoded as integer PPM to
	// keep config identity deterministic.
	ScalarU8AlphaPolicyAbsQuantile ScalarU8AlphaPolicyName = "abs_quantile"

	// ScalarU8AlphaPolicyAbsQuantilePPM999 is the only accepted quantile parameter
	// for ScalarU8AlphaPolicyAbsQuantile in the initial contract (0.999000).
	ScalarU8AlphaPolicyAbsQuantilePPM999 uint32 = 999000
)
View Source 
const (
	TextIndexRewriteMergeStateNotApplicable = "not_applicable"
	TextIndexPhysicalReclamationTreeDB      = "ordered_roots_value_log_gc_leaf_generation_index_vacuum_compact_storage"
)
View Source 
const (
	TextIndexMaintenanceSkipReasonNoDebt           = "no_debt"
	TextIndexMaintenanceSkipReasonBelowThresholds  = "below_thresholds"
	TextIndexMaintenanceSkipReasonDryRun           = "dry_run"
	TextIndexMaintenanceSkipReasonMaxIndexes       = "max_indexes"
	TextIndexMaintenanceTriggerReasonForce         = "force"
	TextIndexMaintenanceTriggerReasonDeletedDocs   = "deleted_docs"
	TextIndexMaintenanceTriggerReasonMicroBlocks   = "micro_posting_blocks"
	TextIndexMaintenanceTriggerReasonDeltaBlocks   = "delta_posting_blocks"
	TextIndexMaintenanceTriggerReasonStalePostings = "stale_postings"
	TextIndexMaintenanceTriggerReasonRewriteBlocks = "rewrite_posting_blocks"
)
View Source 
const (
	TextIndexRewriteMergeStateReady     = "ready"
	TextIndexRewriteMergeStatePending   = "rewrite_merge_pending"
	TextIndexRewriteMergeStateCompacted = "compacted"

	TextIndexRewriteBudgetReasonMaxTerms         = "max_terms"
	TextIndexRewriteBudgetReasonMaxPostingBlocks = "max_posting_blocks"
	TextIndexRewriteBudgetReasonMaxPostings      = "max_postings"
	TextIndexRewriteBudgetReasonMaxDuration      = "max_duration"
)
View Source 
const CollectionUpdateCombineBucketCount = 10

CollectionUpdateCombineBucketCount is the number of power-of-two buckets used for update-combiner queue-depth and batch-size observations.

View Source 
const HybridFusionDefaultRRFK = 60

HybridFusionDefaultRRFK is the contract default RRF denominator offset used when HybridFusionOptions.RRFK is zero.

View Source 
const QuantizedVectorCodecScalarU8 = "scalar_u8"

Variables

View Source 
var (
	ErrCollectionNotFound                = errors.New("collections: collection not found")
	ErrDocumentExists                    = errors.New("collections: document already exists")
	ErrDuplicateDocumentID               = errors.New("collections: duplicate document id in batch")
	ErrIndexNotFound                     = errors.New("collections: index not found")
	ErrUniqueIndexConflict               = errors.New("collections: unique index conflict")
	ErrConcurrentMutation                = errors.New("collections: concurrent mutation")
	ErrDurabilityUnavailable             = errors.New("collections: durability unavailable")
	ErrCommitAmbiguous                   = errors.New("collections: commit ambiguous")
	ErrRecoveryRequired                  = errors.New("collections: recovery required")
	ErrColumnAssetReachabilityIncomplete = errors.New("collections: column asset reachability incomplete")
)
View Source 
var (
	// ErrColumnManifestIdentityMissing is returned when a published column manifest
	// root is missing its required identity record.
	ErrColumnManifestIdentityMissing = errors.New("collections: column manifest missing identity record")
	// ErrColumnManifestIdentityMalformed is returned when a column manifest
	// identity record has the wrong binary shape.
	ErrColumnManifestIdentityMalformed = errors.New("collections: malformed column manifest identity record")
	// ErrColumnManifestIdentityBadMagic is returned when a column manifest
	// identity record has an unexpected magic value.
	ErrColumnManifestIdentityBadMagic = errors.New("collections: bad column manifest identity magic")
	// ErrColumnManifestIdentityUnsupportedVersion is returned when a column
	// manifest identity record uses an unsupported encoding version.
	ErrColumnManifestIdentityUnsupportedVersion = errors.New("collections: unsupported column manifest identity version")
	// ErrColumnManifestIdentityNonZeroReserved is returned when a column manifest
	// identity record has non-zero reserved trailer bytes.
	ErrColumnManifestIdentityNonZeroReserved = errors.New("collections: non-zero column manifest identity reserved trailer")
)
View Source 
var (
	// ErrHybridSearchUnsupported reports an unsupported hybrid query shape or a
	// not-yet-implemented hybrid executor.
	ErrHybridSearchUnsupported = errors.New("collections: hybrid search unsupported")
	// ErrHybridSearchIndexUnavailable reports a missing, closed, corrupt, or
	// otherwise unavailable text/vector/scalar source required by a hybrid query.
	ErrHybridSearchIndexUnavailable = errors.New("collections: hybrid search index unavailable")
	// ErrHybridSearchStaleIndex reports a source index whose epoch does not match
	// the collection snapshot selected for a hybrid query.
	ErrHybridSearchStaleIndex = errors.New("collections: hybrid search index stale")
)

Hybrid-search errors are fail-closed sentinels. Implementations may wrap them with source/index-specific detail, but must not silently scan all documents or downgrade to stale/unavailable indexes for normal hybrid queries.

View Source 
var ErrColumnDeclaredValueUnsupported = errors.New("collections: unsupported column declared value")
View Source 
var ErrColumnPublishPlanRequiresEnabledColumnStore = errors.New("collections: column publish plan requires enabled=true column_store")

ErrColumnPublishPlanRequiresEnabledColumnStore is returned when publish-plan construction or publication sees non-empty column-store metadata that is not enabled for column writes.

View Source 
var ErrColumnQueryPlanUnsupported = errors.New("collections: column query plan unsupported")
View Source 
var ErrTextIndexStorageCorrupt = errors.New("collections: malformed text index storage")
View Source 
var ErrTextIndexUnavailable = errors.New("collections: text index unavailable")

ErrTextIndexUnavailable reports that a declared collection text index cannot safely serve a requested text-search operation. Ranked SearchText executes from postings in #1764 M4, but bounded candidate-generation guardrails still fail closed instead of silently scanning all documents or returning incomplete text rankings.

View Source 
var ErrTypedStorageColumnPartUnsupported = errors.New("collections: typed_column_part ownership is unsupported for this field")

ErrTypedStorageColumnPartUnsupported is returned by fail-closed guards when a normalized layout contains a typed_column_part owner/value-type combination that the current durable typed-column publication path cannot represent.

View Source 
var ErrVectorIndexSearchUnavailable = errors.New("collections: vector index search unavailable")

ErrVectorIndexSearchUnavailable reports that the requested vector index is not currently searchable through the selected product path.

Functions

func AnalyzeTextToSink 

func AnalyzeTextToSink(analyzer TextAnalyzer, text string, sink TextTokenSink) error

AnalyzeTextToSink streams tokens from a named analyzer directly into sink. It avoids allocating the intermediate []TextToken used by AnalyzeText and is the preferred API for write-path collectors.

func AnalyzeTextToSinkWithOptions 

func AnalyzeTextToSinkWithOptions(analyzer TextAnalyzer, options *TextAnalyzerOptions, text string, sink TextTokenSink) error

AnalyzeTextToSinkWithOptions streams tokens using persisted analyzer options. Stopword filtering preserves original token positions so phrase/proximity matching can still account for gaps introduced by removed terms.

func CollectionUpdateCombineBucketLabel 

func CollectionUpdateCombineBucketLabel(index int) string

CollectionUpdateCombineBucketLabel returns the stable metric suffix for an update-combiner bucket. The final bucket is an overflow bucket.

func ColumnRetainedPayloadCompressionStatus 

func ColumnRetainedPayloadCompressionStatus(cfg *ColumnStoreConfig) (compression, policy, status string)

ColumnRetainedPayloadCompressionStatus reports the durable storage compression policy expected for retained payload bodies. Retained payload bytes are stored through TreeDB's persistent value-log/leaf-log path, whose default compression mode resolves to auto grouped-frame compression.

func ColumnRetainedPayloadEncodingStatus 

func ColumnRetainedPayloadEncodingStatus(cfg *ColumnStoreConfig) (encoding, status string)

ColumnRetainedPayloadEncodingStatus reports the retained payload body encoding currently implied by column-store metadata.

func ColumnRetainedPayloadFromJSONDocument 

func ColumnRetainedPayloadFromJSONDocument(cfg ColumnStoreConfig, document []byte) ([]byte, error)

ColumnRetainedPayloadFromJSONDocument applies the production retained-payload transform used when column-store declared fields are stripped from primary row payloads.

func EncodeCatalogCreateCollectionCommandWALPayload 

func EncodeCatalogCreateCollectionCommandWALPayload(meta CollectionMeta) ([]byte, error)

EncodeCatalogCreateCollectionCommandWALPayload returns the canonical local command-WAL payload used for catalog collection creates. R3a apply uses this as its lowering boundary before handing the pre-appended intent back to the normal catalog executor.

func EncodeTemplateV1Document 

func EncodeTemplateV1Document(fields []string, values []any) ([]byte, error)

func EncodeTemplateV1DocumentJSON 

func EncodeTemplateV1DocumentJSON(raw []byte) ([]byte, error)

func FuseHybridSearchCandidates 

func FuseHybridSearchCandidates(candidates []HybridSearchCandidate, fusion HybridFusionOptions, topK int) ([]HybridSearchResult, HybridSearchStats, error)

FuseHybridSearchCandidates deterministically fuses already-generated hybrid text/vector candidates into a bounded final result slice. The helper does not run text or vector searches, open storage, apply scalar filters, or fetch documents; callers must pass the already-bounded candidate lists they want to fuse.

The zero-value fusion method and tie policy use the #2502/#2729 contract defaults: reciprocal-rank fusion and fused_score_best_rank_source_order_id. For RRF methods, RRFK=0 means HybridFusionDefaultRRFK. Normalized-score fusion is exact over the supplied candidates only. topK bounds only the returned result slice; counters still describe the full supplied candidate set.

func IsDuplicateKeyError 

func IsDuplicateKeyError(err error) bool

func PlanColumnSkipScanInto 

func PlanColumnSkipScanInto(result *ColumnSkipScanResult, predicates []ColumnSkipScanPredicate, marks []ColumnSkipScanMark)

PlanColumnSkipScanInto reuses result.ScheduledMarks and result.SkippedMarks as caller-owned scratch. Assign a zero ColumnSkipScanResult to release retained slice capacity between unrelated planning workloads.

Predicate positions are interpreted as dense zero-based sort-key positions for the left-prefix contract. Only bounded predicates in the contiguous prefix starting at position zero can prune marks. A range predicate can terminate the prefix as its final column; predicates after that range are ignored because they are not safe left-prefix pruning inputs. Sparse later-column predicates are ignored until every lower position exists, positions >= len(predicates) are ignored rather than allocating sparse scratch, and duplicate positions use the last bounded predicate supplied.

func RegisterCommandWALReplayHandlers 

func RegisterCommandWALReplayHandlers()

RegisterCommandWALReplayHandlers installs collection command-WAL replay handlers for binaries that want deterministic registration instead of relying on a package side-effect import before opening a command_wal_v1 directory.

func TextIndexV2RequiredCounterNames 

func TextIndexV2RequiredCounterNames() []string

func ValidateCollectionName 

func ValidateCollectionName(name string) error

func ValidateIndexName 

func ValidateIndexName(name string) error

func ValidateIndexPath 

func ValidateIndexPath(path string) error

Types

type BSONSetField 

type BSONSetField struct {
	Key   string
	Value bson.RawValue
}

BSONSetField describes one top-level BSON field assignment for UpdateBSONSet. Nested dotted paths are intentionally not accepted yet; keeping this path top-level lets the planner know exactly which secondary indexes can change.

type BSONSetUpdateBatchItem 

type BSONSetUpdateBatchItem struct {
	DocumentID []byte
	Fields     []BSONSetField
}

BSONSetUpdateBatchItem describes one structured top-level BSON $set update in a batch. DocumentID must be non-empty and unique within the batch.

type BorrowedDocumentRecord 

type BorrowedDocumentRecord struct {
	ID       []byte
	Document []byte
}

BorrowedDocumentRecord is one primary collection record borrowed during a callback scan. This is an unsafe performance type: ID and Document are valid only until the callback returns and must not be retained or modified.

type Collection 

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

func (*Collection) AcquireColumnAssetLifecyclePinSet 

func (c *Collection) AcquireColumnAssetLifecyclePinSet(opts ColumnAssetLifecyclePinSetOptions) (*ColumnAssetLifecyclePinSet, error)

AcquireColumnAssetLifecyclePinSet registers a report-visible process-local pin set. Slice 1 deliberately does not make GC/rewrite consume this registry.

func (*Collection) AuditRetainedPayloadDeclaredPathsAbsent 

func (c *Collection) AuditRetainedPayloadDeclaredPathsAbsent(opts ColumnRetainedPayloadCollectionAuditOptions) (result ColumnRetainedPayloadCollectionAuditResult, err error)

AuditRetainedPayloadDeclaredPathsAbsent scans persisted retained primary-row bodies and verifies that declared typed-column paths were removed. It is read-only: it does not flush buffered writes, publish roots, compact, or mutate storage.

func (*Collection) BuildVectorIndex 

func (c *Collection) BuildVectorIndex(opts VectorIndexOptions) (*VectorIndex, error)

BuildVectorIndex builds an in-memory vector secondary index from the current live collection rows.

func (*Collection) CloseVectorIndexPreparedSearchCache 

func (c *Collection) CloseVectorIndexPreparedSearchCache() error

CloseVectorIndexPreparedSearchCache releases prepared no-document vector-index search state retained by this collection handle. Callers that cache collection handles across requests should use it when invalidating the handle for a service-level lifecycle boundary.

func (*Collection) ColumnAssetGC 

func (c *Collection) ColumnAssetGC(ctx context.Context, opts ColumnAssetGCOptions) (ColumnAssetGCStats, error)

ColumnAssetGC reclaims only complete, canonical column asset segments that M15A reachability proves wholly reclaimable. Mixed segments remain rewrite debt for M15C; incomplete reachability fails closed before deletion.

func (*Collection) ColumnAssetRewrite 

func (c *Collection) ColumnAssetRewrite(ctx context.Context, opts ColumnAssetRewriteOptions) (ColumnAssetRewriteStats, error)

ColumnAssetRewrite copies protected manifest refs out of complete mixed segments and remaps the column manifest to the copied refs. It never rewrites logical rows and never deletes the old mixed segment; M15B GC can reclaim the old segment once callers present the superseded refs as reclaimable candidates.

func (*Collection) ColumnStoreCacheIdentity 

func (c *Collection) ColumnStoreCacheIdentity() (ColumnStoreCacheIdentity, bool)

func (*Collection) ColumnStoreCompact 

func (c *Collection) ColumnStoreCompact(ctx context.Context, opts ColumnStoreCompactOptions) (ColumnStoreCompactStats, error)

ColumnStoreCompact collapses the current mutation-bearing column manifest lineage into one insert-only generation containing exactly latest-visible live rows. It rewrites only column assets/manifest metadata; primary document and index roots are unchanged.

func (*Collection) ColumnStorePhysicalAccounting 

func (c *Collection) ColumnStorePhysicalAccounting(ctx context.Context, opts ColumnStorePhysicalAccountingOptions) (ColumnStorePhysicalAccounting, error)

ColumnStorePhysicalAccounting decodes active production column-store storage accounting for the collection.

func (*Collection) CompactRootOverlays 

func (c *Collection) CompactRootOverlays(ctx context.Context) (CollectionRootOverlayCompactionStats, error)

CompactRootOverlays folds durable collection root overlays into their base collection roots and clears the overlay descriptors in the same backend commit. It is an explicit maintenance boundary for the overlay-root write-back architecture: hot writes may publish durable overlays quickly, then maintenance can restore the simple one-root read shape.

func (*Collection) CompactStorage 

func (c *Collection) CompactStorage(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStorage folds this collection's root overlays and then runs the recommended full TreeDB storage compaction sequence.

func (*Collection) CompactStoragePlan 

func (c *Collection) CompactStoragePlan(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStoragePlan reports collection-aware storage compaction debt without folding root overlays or mutating storage.

func (*Collection) CreateIndex 

func (c *Collection) CreateIndex(def IndexDefinition) (*CollectionMeta, error)

CreateIndex creates and backfills one secondary index as a schema barrier.

Current implementations drain pending writes before planning the backfill. Under the collection WAL target contract, success means the index descriptor and backfilled roots are atomically recoverable; unique conflicts remain pre-commit errors that expose no partial index state.

func (*Collection) CreateTextIndex 

func (c *Collection) CreateTextIndex(def TextIndexDefinition) (*CollectionMeta, TextIndexBackfillStats, error)

CreateTextIndex adds a collection-native text index and backfills persistent roots from the current documents. Explicit v1 indexes backfill postings, text-state, and text-stats roots. V2 indexes (the default for new text index declarations) backfill document ordinals, docmap, term/stat shells, posting blocks, packed norms, optional positions, and status/format roots for v2 BM25F serving.

func (*Collection) CreateVectorIndex 

func (c *Collection) CreateVectorIndex(def VectorIndexDefinition) (*CollectionMeta, error)

CreateVectorIndex adds vector index metadata to the collection schema.

This metadata-only API makes vector fields declarable as document-store indexes. Follow-on PRs persist and maintain the native HNSW graph under the declared index.

func (*Collection) Delete 

func (c *Collection) Delete(documentID []byte) error

Delete removes one document. See DeleteDocument for the matched/deleted result.

Under the collection WAL target contract, WAL-on success is process-crash recoverable; WAL-off relaxed success is not durable-at-ack until an explicit persistence boundary covers the write.

func (*Collection) DeleteBatch 

func (c *Collection) DeleteBatch(documentIDs [][]byte) (int, error)

DeleteBatch removes a caller-provided batch of document IDs as one collection root publish and returns the number of existing documents removed. Missing documents are ignored. Duplicate IDs in the request are rejected so callers do not depend on ordered same-ID semantics.

Under the collection WAL target contract, WAL-on success makes the whole delete batch recoverable as one mutation boundary. Pre-commit errors expose no partial batch; post-commit failures must be commit-ambiguous.

func (*Collection) DeleteBatchWithCommandWALIntent 

func (c *Collection) DeleteBatchWithCommandWALIntent(documentIDs [][]byte, commandWALIntent *backenddb.CommandWALIntent) (int, error)

DeleteBatchWithCommandWALIntent applies an already-appended collection delete command-WAL frame through the normal delete executor. It is reserved for R3a deterministic apply; ordinary callers should use DeleteBatch.

func (*Collection) DeleteDocument 

func (c *Collection) DeleteDocument(documentID []byte) (bool, error)

DeleteDocument removes a document and reports whether this call deleted an existing primary document.

func (*Collection) DropAllIndexes 

func (c *Collection) DropAllIndexes() (*CollectionMeta, error)

func (*Collection) DropIndex 

func (c *Collection) DropIndex(name string) (*CollectionMeta, error)

func (*Collection) DropIndexes 

func (c *Collection) DropIndexes(names []string) (*CollectionMeta, error)

func (*Collection) DropTextIndex 

func (c *Collection) DropTextIndex(name string) (*CollectionMeta, error)

DropTextIndex removes text index metadata and clears the persistent v1 and v2 text root descriptors for the index.

func (*Collection) DropVectorIndex 

func (c *Collection) DropVectorIndex(name string) (*CollectionMeta, error)

func (*Collection) FindByIndex 

func (c *Collection) FindByIndex(indexName, value string) ([][]byte, error)

func (*Collection) FindByIndexRange 

func (c *Collection) FindByIndexRange(indexName string, opts IndexRangeOptions) ([][]byte, bool, error)

func (*Collection) FindByIndexValue 

func (c *Collection) FindByIndexValue(indexName string, value any) ([][]byte, error)

FindByIndexValue returns document IDs whose named secondary index equals value. Query values must match the index value type. If indexName does not exist, it returns nil, nil.

func (*Collection) FindByIndexValueLimit 

func (c *Collection) FindByIndexValueLimit(indexName string, value any, maxResults int) ([][]byte, bool, error)

FindByIndexValueLimit is like FindByIndexValue but stops after maxResults document IDs and reports whether additional matches were present. If indexName does not exist, it returns nil, false, nil.

func (*Collection) FindDocumentsByIndexRange 

func (c *Collection) FindDocumentsByIndexRange(indexName string, opts IndexRangeOptions) ([]DocumentRecord, bool, error)

FindDocumentsByIndexRange returns primary documents whose named secondary index falls inside opts, preserving index order. Persisted index and primary reads share one snapshot/catalog; same-manager buffered documents are still consulted before the persisted primary root so pending indexed writes remain visible. Descending scans are not supported. Because this API holds a write-domain read lock while pairing secondary IDs with buffered primary documents, callers must provide a positive Limit.

func (*Collection) Flush 

func (c *Collection) Flush() error

Flush publishes buffered collection-local writes to the backend roots. Single no-index inserts use this boundary to match TreeDB's cached write path while still giving callers an explicit durability/visibility point.

func (*Collection) Get 

func (c *Collection) Get(documentID []byte) ([]byte, error)

Get returns an owned copy of the document for documentID.

Missing documents return (nil, nil), matching the existing collection API. Present-but-empty documents return a non-nil empty slice.

func (*Collection) GetInto 

func (c *Collection) GetInto(documentID []byte, dst []byte) ([]byte, bool, error)

GetInto appends the document for documentID into dst[:0].

The returned slice is owned by the caller. Missing documents return (dst[:0], false, nil).

func (*Collection) Insert 

func (c *Collection) Insert(id, document []byte) ([]byte, error)

Insert adds one document and returns the stored document ID.

Current durability is mode/path dependent; see docs/spec/contracts.md. Under the collection WAL target contract, WAL-on success is process-crash recoverable but not necessarily published, checkpointed, or fsynced. WAL-off relaxed success remains process-local until Flush, FlushAll, Checkpoint, or Close covers the write.

func (*Collection) InsertBatch 

func (c *Collection) InsertBatch(ids, documents [][]byte) ([][]byte, error)

InsertBatch adds a batch of documents and returns the stored document IDs.

Under the collection WAL target contract, WAL-on success makes the whole batch recoverable as one mutation boundary. Ordinary pre-commit errors expose no partial batch. Post-commit failures must be reported as commit-ambiguous.

func (*Collection) InsertBatchValidatedBSON 

func (c *Collection) InsertBatchValidatedBSON(ids, documents [][]byte) ([][]byte, error)

InsertBatchValidatedBSON inserts native BSON documents that the caller has already validated. It is intended for wire-protocol gateways that validate BSON while parsing the request and need to avoid a duplicate full-document validation pass on the insert hot path.

func (*Collection) InsertBatchWithCommandWALIntent 

func (c *Collection) InsertBatchWithCommandWALIntent(ids, documents [][]byte, trustedValidBSON bool, commandWALIntent *backenddb.CommandWALIntent) ([][]byte, error)

InsertBatchWithCommandWALIntent applies an already-appended collection insert command-WAL frame through the normal insert executor. It is reserved for R3a deterministic apply; ordinary callers should use InsertBatch or InsertBatchValidatedBSON so the collection owns command-WAL creation.

func (*Collection) InsertBatchWithTemplateV1Encoder 

func (c *Collection) InsertBatchWithTemplateV1Encoder(ids, documents [][]byte, encoder *TemplateV1Encoder) ([][]byte, error)

InsertBatchWithTemplateV1Encoder inserts template-v1 documents and teaches encoder any numeric template IDs resolved by the successful insert. Later EncodeDocument calls on the same encoder can then emit compact TD1D stored documents directly instead of hash-addressed TD1H insert documents.

func (*Collection) LastInsertStats 

func (c *Collection) LastInsertStats() CollectionInsertStats

LastInsertStats returns phase timings and counters from the most recent successful InsertBatch call on this Collection handle.

func (*Collection) LastUpdateStats 

func (c *Collection) LastUpdateStats() CollectionUpdateStats

LastUpdateStats returns phase timings and counters from the most recent successful UpdateBatch-style call on this Collection handle.

func (*Collection) LoadNativeVectorIndexSnapshot 

func (c *Collection) LoadNativeVectorIndexSnapshot(opts VectorIndexOptions) (*VectorIndex, VectorIndexLoadStatus, error)

LoadNativeVectorIndexSnapshot loads a declared vector index from its TreeDB collection root. Missing or invalid graph roots return a non-loaded status so callers can safely fall back to exact search.

func (*Collection) LoadVectorIndexSnapshot 

func (c *Collection) LoadVectorIndexSnapshot(opts VectorIndexOptions) (*VectorIndex, VectorIndexLoadStatus, error)

LoadVectorIndexSnapshot loads the currently published persisted vector index epoch. Missing, incomplete, or corrupt snapshots return a non-loaded status with ExactFallbackReason set and no error, so callers can safely use exact search as the correctness fallback.

func (*Collection) MaintainTextIndex 

func (c *Collection) MaintainTextIndex(ctx context.Context, indexName string, opts TextIndexMaintenanceOptions) (TextIndexMaintenanceStats, error)

func (*Collection) MaintainTextIndexes 

func (c *Collection) MaintainTextIndexes(ctx context.Context, opts TextIndexMaintenanceOptions) (TextIndexMaintenanceStats, error)

MaintainTextIndexes runs the bounded text-v2 rewrite policy across this collection's text-v2 indexes. MaxIndexes limits how many indexes are planned.

func (*Collection) Meta 

func (c *Collection) Meta() CollectionMeta

func (*Collection) MetaView 

func (c *Collection) MetaView() CollectionMeta

MetaView returns the collection metadata without deep-copying slice fields. The returned value is for read-only internal fast paths; callers must not mutate Indexes, VectorIndexes, TextIndexes, or other referenced fields.

func (*Collection) Name 

func (c *Collection) Name() string

func (*Collection) NativewireInsertBatchNoResultIDs 

func (c *Collection) NativewireInsertBatchNoResultIDs(ids, documents [][]byte, trustedValidBSON bool) error

NativewireInsertBatchNoResultIDs executes an insert batch without cloning response-owned result IDs. It exists for the nativewire gateway omit-result fast path; public callers that need returned IDs should keep using InsertBatch or InsertBatchValidatedBSON.

func (*Collection) NewStoredDocumentJSONMaterializer 

func (c *Collection) NewStoredDocumentJSONMaterializer() (*StoredDocumentJSONMaterializer, error)

NewStoredDocumentJSONMaterializer prepares a reusable materializer for stored collection documents. Callers that materialize multiple template-v1 documents should reuse one materializer so the backend snapshot and template resolver are shared across the request.

func (*Collection) OpenCollectionReadView 

func (c *Collection) OpenCollectionReadView() (*CollectionReadView, error)

OpenCollectionReadView opens a snapshot-bound document materializer. Buffered writes are flushed before the snapshot is acquired so the view matches normal Collection.Get visibility at open time; later writes are not visible through the view.

func (*Collection) OpenVectorIndexSearcher 

func (c *Collection) OpenVectorIndexSearcher(opts VectorIndexSearcherOptions) (*VectorIndexSearcher, error)

OpenVectorIndexSearcher opens a reusable search handle for steady-state vector queries. Setup/open/decode cost is paid at open; Search then measures graph traversal, vector scoring, top-k production, and optional post-top-k document fetch. For the current exact no-document high-QPS contract, pair a reusable searcher with SearchWithBuffer and a warmed caller-owned buffer.

func (*Collection) PlanColumnAssetLifecycle 

func (c *Collection) PlanColumnAssetLifecycle(ctx context.Context, opts ColumnAssetLifecycleOptions) (ColumnAssetLifecycleReport, error)

PlanColumnAssetLifecycle builds a report-only lifecycle inventory for the collection's column assets. It never deletes, quarantines, moves, rewrites, or changes query semantics.

func (*Collection) PlanColumnAssetReachability 

func (c *Collection) PlanColumnAssetReachability(ctx context.Context, opts ColumnAssetReachabilityOptions) (ColumnAssetReachabilityPlan, error)

PlanColumnAssetReachability builds the M15A dry-run/protect-only liveness plan for the collection's isolated column asset namespace. It never deletes, rewrites, or remaps assets; uncertain or untracked bytes are retained.

func (*Collection) PlanColumnQuery 

func (c *Collection) PlanColumnQuery(req ColumnQueryPlanRequest) (ColumnQueryPlan, error)

func (*Collection) PreflightCommandWALMutation 

func (c *Collection) PreflightCommandWALMutation(operation ColumnPublishOperation) error

PreflightCommandWALMutation checks collection-local command-WAL support for an already-classified deterministic apply mutation before R3a appends its local command-WAL frame.

func (*Collection) PreflightInsertBatchConflicts 

func (c *Collection) PreflightInsertBatchConflicts(ids, documents [][]byte, trustedValidBSON bool) error

PreflightInsertBatchConflicts checks deterministic insert-batch conflicts before an external command-WAL owner stages its local frame. It publishes any buffered writes first so the persisted primary and unique roots match the collection's visible state, then reuses normal insert planning conflict probes without publishing the planned mutation.

func (*Collection) PreflightReplaceBatchConflicts 

func (c *Collection) PreflightReplaceBatchConflicts(ids, documents [][]byte) error

PreflightReplaceBatchConflicts checks deterministic replacement conflicts before an external command-WAL owner stages its local frame. It publishes any buffered writes first so persisted roots match visible state, then reuses normal update planning without publishing the planned mutation.

func (*Collection) PrepareBSONSetUpdateBatchCommandWAL 

func (c *Collection) PrepareBSONSetUpdateBatchCommandWAL(items []BSONSetUpdateBatchItem) ([]UpdateBatchResult, []commitlog.CollectionDocument, error)

PrepareBSONSetUpdateBatchCommandWAL plans a BSON $set batch without applying it and returns the exact replacement documents that must be staged in an externally-owned collection update command-WAL frame. It is reserved for R3a deterministic apply.

func (*Collection) PrepareColumnPhysicalQuery 

func (c *Collection) PrepareColumnPhysicalQuery(req ColumnPhysicalQueryRequest) (*ColumnPhysicalQueryRunner, error)

PrepareColumnPhysicalQuery prepares a reusable direct physical query runner over the current recovery-authoritative manifest. The runner pins a snapshot until Close and fail-closes for mutation-bearing manifests or unsupported query shapes rather than silently changing semantics.

func (*Collection) PrepareTypedColumnBoolPredicateAggregate 

func (c *Collection) PrepareTypedColumnBoolPredicateAggregate(req TypedColumnBoolPredicateAggregateRequest) (*TypedColumnBoolPredicateAggregateSession, error)

func (*Collection) PrepareTypedColumnInt64PredicateAggregate 

func (c *Collection) PrepareTypedColumnInt64PredicateAggregate(req TypedColumnInt64PredicateAggregateRequest) (*TypedColumnInt64PredicateAggregateSession, error)

PrepareTypedColumnInt64PredicateAggregate prepares a scoped typed-column int64 predicate aggregate session over the current recovery-authoritative snapshot. The prepared path is intentionally direct typed-column only: unsupported columns or unavailable typed-column assets fail closed instead of falling back to document scans. In cached_verify mode, the session reuses the file identity captured when a segment reader is opened; use verify mode for per-run checksum validation during a long-lived session. Call Close when finished to release mapped assets and the pinned snapshot. Cached-verify prepared sessions validate each immutable typed-column asset ref once before using targeted section/range reads on later hot scans; verify mode keeps the full-asset validation path per Run, and skip-checksums remains an unsafe benchmark ceiling.

func (*Collection) RebuildVectorIndex 

func (c *Collection) RebuildVectorIndex(name string) (VectorIndexStatus, error)

RebuildVectorIndex scans canonical collection documents, rebuilds the declared HNSW graph, and publishes a full native vector-index root. It is an operational maintenance call: collection writes wait while the rebuild scans and publishes so the replacement graph cannot miss committed mutations.

func (*Collection) RegisterColumnAssetPendingPublish 

func (c *Collection) RegisterColumnAssetPendingPublish(opts ColumnAssetPendingPublishRegistrationOptions) (*ColumnAssetLifecycleRegistryLease, error)

RegisterColumnAssetPendingPublish registers pending-publish refs for lifecycle reports. It is process-local/report-only and does not alter publish, cleanup, GC, or rewrite behavior.

func (*Collection) RegisterColumnAssetPreparedAsset 

func (c *Collection) RegisterColumnAssetPreparedAsset(opts ColumnAssetPreparedAssetRegistrationOptions) (*ColumnAssetLifecycleRegistryLease, error)

RegisterColumnAssetPreparedAsset registers prepared asset refs for lifecycle reports. It is process-local/report-only and does not alter cleanup, GC, or rewrite behavior.

func (*Collection) RegisterColumnAssetPreparedAssets 

func (c *Collection) RegisterColumnAssetPreparedAssets(opts ColumnAssetPreparedAssetRegistrationOptions) (*ColumnAssetLifecycleRegistryLease, error)

RegisterColumnAssetPreparedAssets is a convenience alias for callers that register a batch of prepared asset refs in one record.

func (*Collection) RegisterColumnAssetQuarantine 

func (c *Collection) RegisterColumnAssetQuarantine(opts ColumnAssetQuarantineRegistrationOptions) (*ColumnAssetLifecycleRegistryLease, error)

RegisterColumnAssetQuarantine registers logical quarantine refs/segments for lifecycle reports. It does not perform physical quarantine or cleanup.

func (*Collection) RegisterVectorIndex 

func (c *Collection) RegisterVectorIndex(index *VectorIndex)

RegisterVectorIndex attaches an in-memory vector index to this collection so successful collection inserts, updates, and deletes keep the index in sync.

func (*Collection) Replace 

func (c *Collection) Replace(documentID, document []byte) (bool, error)

func (*Collection) ReplaceBatchWithCommandWALIntent 

func (c *Collection) ReplaceBatchWithCommandWALIntent(ids, documents [][]byte, commandWALIntent *backenddb.CommandWALIntent) (int, int, error)

ReplaceBatchWithCommandWALIntent applies existing-only full-document replacements with an already-appended collection update command-WAL frame. It is reserved for R3a deterministic apply; ordinary callers should use Update or UpdateBatch.

func (*Collection) RewriteTextIndex 

func (c *Collection) RewriteTextIndex(indexName string, opts TextIndexRewriteOptions) (TextIndexRewriteStats, error)

RewriteTextIndex performs text-v2 logical rewrite/merge maintenance for one explicit v2 text index. It coalesces micro/delta blocks into sealed blocks, removes stale generations and deleted-document postings, optionally purges tombstoned docID/docmap/norm entries, and updates term block counts/status via normal TreeDB collection-root publication. It does not run a private physical GC; callers can run ValueLogGC, value-log rewrite, or CompactStorage after old snapshots release to reclaim obsolete pointer-backed payloads.

func (*Collection) RunColumnPhysicalQuery 

func (c *Collection) RunColumnPhysicalQuery(req ColumnPhysicalQueryRequest) (ColumnPhysicalQueryResult, error)

RunColumnPhysicalQuery executes an explicit serial physical column query over the recovery-authoritative manifest. Insert-only manifests use direct physical reducers. Supported dense typed-column mutation queries use latest-visible typed-column reducers; unsupported mutation-bearing shapes fail closed or use the legacy typed-row visibility overlay only where explicitly routed.

func (*Collection) RunColumnPhysicalQueryParallel 

func (c *Collection) RunColumnPhysicalQueryParallel(req ColumnPhysicalQueryRequest, maxWorkers int) (ColumnPhysicalQueryResult, error)

RunColumnPhysicalQueryParallel executes an insert-only physical query by partitioning immutable manifest refs across worker-local serial scanners. Mutation-bearing manifests stay fail-closed until partitioned visibility reconstruction is available.

func (*Collection) RunTypedColumnBoolPredicateAggregate 

func (c *Collection) RunTypedColumnBoolPredicateAggregate(req TypedColumnBoolPredicateAggregateRequest) (TypedColumnBoolPredicateAggregateResult, error)

func (*Collection) RunTypedColumnInt64PredicateAggregate 

func (c *Collection) RunTypedColumnInt64PredicateAggregate(req TypedColumnInt64PredicateAggregateRequest) (TypedColumnInt64PredicateAggregateResult, error)

RunTypedColumnInt64PredicateAggregate executes a narrow count/sum/avg path for int64 predicates. When the requested int64 field is owned by typed_column_part, the aggregate is evaluated directly over durable typed_column_part assets. The direct path does not decode row locators, scan physical row assets, materialize result rows, or reconstruct documents. If no usable typed-column store is available for the field, the method falls back to a full document scan and marks Diagnostics.Fallback/FallbackReason.

func (*Collection) RunTypedColumnInt64PredicateScan 

func (c *Collection) RunTypedColumnInt64PredicateScan(req TypedColumnInt64PredicateScanRequest) (TypedColumnInt64PredicateScanResult, error)

RunTypedColumnInt64PredicateScan executes the scoped #1757 scalar predicate MVP. When the requested int64 field is owned by typed_column_part, the predicate is evaluated directly over durable typed_column_part assets and fails closed if those assets are unavailable or inconsistent. Non typed-column ownership keeps the existing typed-row/document fallback behavior and is identified in Diagnostics.Fallback.

func (*Collection) RunTypedColumnStringPredicateScan 

func (c *Collection) RunTypedColumnStringPredicateScan(req TypedColumnStringPredicateScanRequest) (TypedColumnStringPredicateScanResult, error)

RunTypedColumnStringPredicateScan executes the scoped #1785 string equality path. It only evaluates non-null string fields owned by typed_column_part. The predicate is evaluated directly over durable typed_column_part dictionary-code assets and fails closed for unsupported columns instead of reconstructing documents or using row-asset dictionary sidecars.

func (*Collection) SameCachedCatalog 

func (c *Collection) SameCachedCatalog(other *Collection) bool

SameCachedCatalog reports whether both handles are cached against the same collection catalog state. For commit-agnostic catalog shapes, the system root is the catalog identity; data-only commits can advance CommitSeq without changing collection metadata or root descriptors.

func (*Collection) ScanBorrowedDocumentsByIndexRange 

func (c *Collection) ScanBorrowedDocumentsByIndexRange(indexName string, opts IndexRangeOptions, fn func(BorrowedDocumentRecord) (bool, error)) (bool, error)

ScanBorrowedDocumentsByIndexRange calls fn with primary documents whose named secondary index falls inside opts, preserving index order. This is a borrowed performance API for gateway integrations: record slices are valid only during the callback, and fn may run while the collection write-domain read lock is held. The callback must not retain or modify slices, call back into Collection, or perform blocking work. Missing indexes are treated as empty scans. Descending scans are not supported, and opts.Limit must be positive. General callers should use FindDocumentsByIndexRange.

func (*Collection) ScanDocumentIDsFunc 

func (c *Collection) ScanDocumentIDsFunc(maxDocuments int, fn func([]byte) (bool, error)) (bool, error)

ScanDocumentIDsFunc flushes buffered writes before acquiring a snapshot, then calls fn for primary collection document IDs until maxDocuments is reached, the collection is exhausted, or fn returns false. Unlike ScanDocumentsFunc, it does not materialize or reconstruct document payloads.

func (*Collection) ScanDocuments 

func (c *Collection) ScanDocuments(maxDocuments int) ([]DocumentRecord, bool, error)

ScanDocuments flushes buffered writes before acquiring a snapshot, then scans the collection primary root up to maxDocuments. The returned boolean is true when additional documents were present beyond the limit.

func (*Collection) ScanDocumentsFunc 

func (c *Collection) ScanDocumentsFunc(maxDocuments int, fn func(DocumentRecord) (bool, error)) (bool, error)

ScanDocumentsFunc flushes buffered writes before acquiring a snapshot, then calls fn for primary collection records until maxDocuments is reached, the collection is exhausted, or fn returns false. The returned boolean is true only when additional documents were present beyond the maxDocuments limit.

func (*Collection) ScanIndexRange 

func (c *Collection) ScanIndexRange(indexName string, opts IndexRangeOptions, fn func(id []byte) (bool, error)) (bool, error)

func (*Collection) SearchHybrid 

func (c *Collection) SearchHybrid(opts HybridSearchOptions) (HybridSearchResponse, error)

SearchHybrid executes a bounded hybrid search over optional text and vector candidate sources, an optional scalar-index filter, deterministic rank fusion, and optional final top-k document materialization. It fails closed instead of scanning primary documents when a requested source/filter/fetch path is unavailable or unsupported.

func (*Collection) SearchHybridTextCandidates 

func (c *Collection) SearchHybridTextCandidates(query HybridTextQuery) (HybridCandidateResponse, error)

SearchHybridTextCandidates adapts collection-native ranked text search into the shared hybrid candidate shape. It is candidate-only: it requests no documents from SearchText, reuses response-owned result IDs for response-owned HybridSearchCandidate values, assigns one-based source ranks, and fails closed if the backing text path reports any full document materialization or scan fallback. Match attribution is opt-in through HybridTextQuery.IncludeTextMatches; the default candidate path is score-only.

func (*Collection) SearchHybridVectorCandidates 

func (c *Collection) SearchHybridVectorCandidates(query HybridVectorQuery) (HybridCandidateResponse, error)

SearchHybridVectorCandidates adapts an existing collection vector-index search into the shared hybrid candidate shape.

Candidate generation is no-document by construction: it uses SearchVectorIndexWithBuffer with IncludeDocuments=false, copies stable result IDs into response-owned HybridSearchCandidate values, assigns one-based source ranks, and fails closed if the backing vector path reports any document materialization or unavailable vector-index state.

func (*Collection) SearchText 

func (c *Collection) SearchText(opts TextSearchOptions) (TextSearchResponse, error)

SearchText executes a bounded postings-backed lexical search for a declared collection text index. It never scans/ranks all collection documents.

func (*Collection) SearchVectorIndex 

func (c *Collection) SearchVectorIndex(opts VectorIndexSearchOptions) (VectorIndexSearchResponse, error)

SearchVectorIndex searches a collection vector index through the public collection lifecycle. V4 wires only explicit column_graph indexes to the native physical column reader; native_runtime remains reported as native rather than silently falling back or pretending to use column storage. When availability or staleness checks fail, the returned response may still carry the index status so callers can distinguish rebuild-needed/unavailable cases.

With IncludeDocuments=false, SearchVectorIndex returns response-owned result IDs and scores only and must not materialize documents. With IncludeDocuments=true, document fetch happens after top-k selection and is reported through document counters. Exact no-document calls use the collection-owned prepared hnsw_search_pack_v1 cache when healthy; unsupported shapes and unavailable packs fall back to the one-shot searcher path. Use SearchVectorIndexWithBuffer for the zero-allocation caller-owned result-buffer seam, and OpenVectorIndexSearcher plus SearchWithBuffer when callers can keep open/prepared state outside the timed query boundary. Callers that want a split search/fetch shape can run a no-document search first, then use CollectionReadView.FetchDocumentsForVectorIndexSearchResults as a separate materialization phase with separate counters.

func (*Collection) SearchVectorIndexWithBuffer 

func (c *Collection) SearchVectorIndexWithBuffer(opts VectorIndexSearchOptions, buffer *VectorIndexSearchBuffer) (VectorIndexSearchResponse, error)

SearchVectorIndexWithBuffer searches a collection vector index through a no-document high-QPS seam using caller-owned result storage. Returned Results and result IDs alias buffer and remain valid only until buffer is reused or Reset is called. The same buffer must not be reused concurrently; parallel callers should use independent buffers.

This method supports exact/zero QueryMode through the exact hnsw_search_pack_v1 route, and explicit quantized_only / quantized_rerank modes through a collection-owned prepared quantized route selected by QuantizedIndexName; rabitq_1bit uses the prepared hnsw_search_pack_v1 score-plane traversal when eligible. It intentionally fails closed for document materialization, projections, filters, benchmark-debug stats mode, missing or invalid prepared assets, stale route identities, and legacy/fallback routes. Healthy prepared state is opened once into the collection cache keyed by the current collection/vector-index/score-plane manifest identity; steady-state searches reuse that prepared state and caller-owned result buffer instead of opening a VectorIndexSearcher per call.

func (*Collection) SearchVectorsExact 

func (c *Collection) SearchVectorsExact(query []float32, opts VectorSearchOptions) ([]VectorSearchResult, error)

SearchVectorsExact scans live collection documents, extracts the configured vector field from each document, computes exact distances, and returns the nearest TopK matches. The collection primary row remains the canonical vector storage; missing or null vector fields are skipped.

func (*Collection) StoredDocumentJSON 

func (c *Collection) StoredDocumentJSON(document []byte) ([]byte, error)

StoredDocumentJSON materializes one stored collection document as JSON bytes. JSON-format collections return an owned copy of document. BSON-format collections return canonical Extended JSON. Template-v1 collections resolve the document's template from the collection template root and any buffered template runs.

func (*Collection) TextIndexStatus 

func (c *Collection) TextIndexStatus(indexName string) (TextIndexStatus, error)

func (*Collection) TextIndexStorageStats 

func (c *Collection) TextIndexStorageStats(indexName string) (TextIndexStorageStats, error)

TextIndexStorageStats validates and summarizes persistent text roots for a declared text index. It scans durable text roots and is intended for maintenance/accounting/benchmark use; serving health paths should prefer the lightweight TextIndexStatus.

func (*Collection) UnregisterVectorIndex 

func (c *Collection) UnregisterVectorIndex(name string)

UnregisterVectorIndex detaches a registered in-memory vector index.

func (*Collection) Update 

func (c *Collection) Update(documentID []byte, update func(current []byte) (replacement []byte, changed bool, err error)) (bool, bool, error)

Update applies update to the latest document value and retries if another collection write changes the root before this update publishes. For indexed collections with BufferedIndexedWrites enabled, updates that do not change secondary unique index values may be staged in the write domain and become durable at Flush/Close or auto-flush.

For no-secondary-index collections, generic callback-based Update operations preserve synchronous publish semantics in every durability mode: pending writes are flushed before planning, and modified documents publish to the primary root before Update returns. Single-document BSON $set updates use a separate direct buffered path and may stage when durability mode allows deferred flush/publish behavior (WAL-off relaxed and WAL-on relaxed).

Callback panics are recovered and returned as errors in both direct and combined execution. When the collection write domain combines concurrent updates, update may run on an internal combiner goroutine. The callback must not rely on caller goroutine behavior such as recover, runtime.Goexit, or testing.T.Fatal.

Under the collection WAL target contract, WAL-on success is process-crash recoverable for update operations that publish before returning. Direct- buffered BSON $set updates in WAL-on relaxed mode defer that recoverability boundary until Flush/Close publishes the staged root runs. Retry after timeout or commit-ambiguous failure is safe only when the update function is idempotent or protected by an application-level guard or durable idempotency key.

func (*Collection) UpdateBSONSet 

func (c *Collection) UpdateBSONSet(documentID []byte, fields []BSONSetField) (bool, bool, error)

UpdateBSONSet applies a structured top-level BSON $set update to one document. The collection must use DocumentFormatBSON. Missing documents return matched=false. If all assigned values already match the stored document, modified=false. Callers must not mutate fields or RawValue byte slices until UpdateBSONSet returns.

For no-index collections, this path may stage buffered root runs in WAL-off relaxed and WAL-on relaxed modes. In command-WAL (WAL-on) modes, staged updates append their deterministic command frame before returning, and Flush/Close later publishes the covered roots.

func (*Collection) UpdateBSONSetBatchIfNoSecondaryUniqueIndexChanges 

func (c *Collection) UpdateBSONSetBatchIfNoSecondaryUniqueIndexChanges(items []BSONSetUpdateBatchItem) ([]UpdateBatchResult, bool, error)

UpdateBSONSetBatchIfNoSecondaryUniqueIndexChanges applies a batch of structured top-level BSON $set updates only when no secondary unique index value changes in the planning snapshot. This is the BSON-set equivalent of UpdateBatchIfNoSecondaryUniqueIndexChanges.

func (*Collection) UpdateBSONSetBatchWithCommandWALIntent 

func (c *Collection) UpdateBSONSetBatchWithCommandWALIntent(setItems []BSONSetUpdateBatchItem, commandWALDocuments []commitlog.CollectionDocument, commandWALIntent *backenddb.CommandWALIntent) ([]UpdateBatchResult, error)

UpdateBSONSetBatchWithCommandWALIntent applies the exact BSON $set replacement documents that were precomputed and encoded into an already-appended collection update command-WAL frame. It is reserved for R3a deterministic apply; ordinary callers should use UpdateBSONSet or UpdateBSONSetBatchIfNoSecondaryUniqueIndexChanges.

func (*Collection) UpdateBatch 

func (c *Collection) UpdateBatch(items []UpdateBatchItem) ([]UpdateBatchResult, error)

UpdateBatch applies a unique set of document updates under one collection mutation. Missing documents report Matched=false. Duplicate document IDs are rejected so callers that require same-document ordering can fall back to sequential Update calls.

Under the collection WAL target contract, WAL-on success makes the whole batch recoverable as one mutation boundary. Item/callback errors are pre-commit unless explicitly documented otherwise and must expose no partial batch. Post-commit failures must be commit-ambiguous for the whole batch.

func (*Collection) UpdateBatchIfNoSecondaryUniqueIndexChanges 

func (c *Collection) UpdateBatchIfNoSecondaryUniqueIndexChanges(items []UpdateBatchItem) ([]UpdateBatchResult, bool, error)

UpdateBatchIfNoSecondaryUniqueIndexChanges applies UpdateBatch only when no secondary unique index value changes in the planning snapshot. This lets the write combiner batch updates that touch non-unique fields on schemas that also have unique indexes, while preserving per-document fallback semantics for unique value mutations. When batched=false and err=nil, the returned results are zero-valued with len(items).

func (*Collection) UpdateBatchIfNoSecondaryUniqueIndexes 

func (c *Collection) UpdateBatchIfNoSecondaryUniqueIndexes(items []UpdateBatchItem) ([]UpdateBatchResult, bool, error)

UpdateBatchIfNoSecondaryUniqueIndexes applies UpdateBatch only when the collection has no secondary unique indexes in the planning snapshot. It reports batched=false without applying updates if a unique secondary index is present so callers can preserve ordered per-document update semantics. When batched=false and err=nil, the returned results are zero-valued with len(items).

func (*Collection) VectorIndexStatus 

func (c *Collection) VectorIndexStatus(name string) (VectorIndexStatus, error)

VectorIndexStatus returns persisted-root and runtime status for a declared vector index.

func (*Collection) WarmVectorIndexPreparedSearch 

func (c *Collection) WarmVectorIndexPreparedSearch(opts VectorIndexSearchOptions) (VectorIndexSearchResponse, error)

WarmVectorIndexPreparedSearch opens and retains the collection-level prepared vector-index search state for opts without executing a query. It is intended for service lifecycle boundaries, such as optimize, that need the first request after a rebuild to reuse already-prepared no-document search assets.

type CollectionInsertStats 

type CollectionInsertStats struct {
	Documents                    int
	Indexes                      int
	Runs                         int
	BufferedIndexedBatches       int
	BufferedIndexedBypassBatches int
	ValidationPreflightReused    int
	ValidationPreflightRechecked int
	PrepareDocuments             time.Duration
	IndexStateExtraction         time.Duration
	// DuplicateDocumentPreflight includes duplicate-ID detection and
	// existing-document conflict checks.
	DuplicateDocumentPreflight time.Duration
	// RetainedPayloadPrepare includes retained-payload transforms for column
	// stores before the primary run is built.
	RetainedPayloadPrepare                          time.Duration
	RetainedPayloadRows                             int
	RetainedPayloadDeclaredRows                     int
	RetainedPayloadSemanticStreamBlocks             int
	RetainedPayloadSemanticStreamWorkerCount        int
	RetainedPayloadSemanticStreamDeclaredRowPrepare time.Duration
	RetainedPayloadSemanticStreamBlockPrepareWall   time.Duration
	RetainedPayloadSemanticStreamBlockCollect       time.Duration
	RetainedPayloadSemanticStreamBlockEncoderSetup  time.Duration
	RetainedPayloadSemanticStreamBlockRawEncode     time.Duration
	RetainedPayloadSemanticStreamBlockStoredEncode  time.Duration
	RetainedPayloadSemanticStreamBlockFinalize      time.Duration
	RetainedPayloadSemanticStreamTableBuild         time.Duration
	RetainedPayloadValueLogPointerize               time.Duration
	RetainedPayloadValueLogValues                   int
	RetainedPayloadValueLogBytes                    int64
	RetainedStreamValueLogPointerize                time.Duration
	RetainedStreamValueLogValues                    int
	RetainedStreamValueLogBytes                     int64
	// ColumnPublish* fields are populated for typed-column InsertBatch paths
	// that route through the command-WAL column manifest publish path.
	ColumnPublishBuildColumnDelta       time.Duration
	ColumnPublishBuildSystemDelta       time.Duration
	ColumnPublishCommit                 time.Duration
	ColumnPublishDocumentExtraction     time.Duration
	ColumnPublishDeclaredColumnEncoding time.Duration
	ColumnPublishAssetPreparation       time.Duration
	ColumnPublishRowAssetPreparation    time.Duration
	ColumnPublishTypedColumnPreparation time.Duration

	ColumnPublishTypedColumnDictionaryBuild    time.Duration
	ColumnPublishTypedColumnRowMaterialization time.Duration
	ColumnPublishTypedColumnPartBuild          time.Duration
	ColumnPublishTypedColumnImageBuild         time.Duration

	ColumnPublishDictionaryPreparation                 time.Duration
	ColumnPublishInt64Preparation                      time.Duration
	ColumnPublishAggregateMetadataPrepare              time.Duration
	ColumnPublishRowSidecarSharedBuild                 time.Duration
	ColumnPublishAssetAppend                           time.Duration
	ColumnPublishAssetAppendOpen                       time.Duration
	ColumnPublishAssetAppendWrite                      time.Duration
	ColumnPublishAssetAppendClose                      time.Duration
	ColumnPublishAssetAppendFileSync                   time.Duration
	ColumnPublishAssetAppendFileClose                  time.Duration
	ColumnPublishAssetAppendDirSync                    time.Duration
	ColumnPublishAssetAppendCleanup                    time.Duration
	ColumnPublishAssetAppenderCloseCount               int
	ColumnPublishAssetAppendFileSyncCount              int
	ColumnPublishAssetSyncEpochCount                   int
	ColumnPublishSharedSegmentAppenderCloseCount       int
	ColumnPublishSharedSegmentAppendFileSyncCount      int
	ColumnPublishSharedSegmentAppendSyncEpochCount     int
	ColumnPublishDirectViewSegmentAppenderCloseCount   int
	ColumnPublishDirectViewSegmentAppendFileSyncCount  int
	ColumnPublishDirectViewSegmentAppendSyncEpochCount int
	ColumnPublishManifestEncode                        time.Duration
	ColumnPublishAssetClosureValidation                time.Duration
	ColumnPublishRootDeltaConstruction                 time.Duration
	ColumnPublishSystemDeltaConstruction               time.Duration
	ColumnPublishRootDeltaMaterialization              time.Duration
	ColumnPublishRows                                  int
	ColumnPublishPreparedAssets                        int
	ColumnPublishRowAssetBytes                         int64
	ColumnPublishRowAssetCount                         int
	ColumnPublishTypedColumnBytes                      int64
	ColumnPublishTypedColumnCount                      int
	ColumnPublishDictionaryBytes                       int64
	ColumnPublishDictionaryCount                       int
	ColumnPublishInt64Bytes                            int64
	ColumnPublishInt64Count                            int
	ColumnPublishAggregateMetadataBytes                int64
	ColumnPublishAggregateMetadataCount                int
	ColumnPublishSharedAppendBytes                     int64
	ColumnPublishSharedAppendCount                     int
	ColumnPublishSharedSegmentAppendBytes              int64
	ColumnPublishSharedSegmentAppendCount              int
	ColumnPublishDirectViewSegmentAppendBytes          int64
	ColumnPublishDirectViewSegmentAppendCount          int
	ColumnPublishRequiredAssetBytes                    int64
	ColumnPublishManifestBytes                         int64
	UniqueIndexPreflight                               time.Duration
	TemplateRunBuild                                   time.Duration
	PrimaryRunBuild                                    time.Duration
	IndexStateRunBuild                                 time.Duration
	SecondaryRunBuild                                  time.Duration
	Publish                                            time.Duration
	SecondaryEntries                                   int
	SecondaryKeyBytes                                  int
	SecondarySortedRuns                                int
	SecondaryUnsortedRuns                              int
	SecondaryRuns                                      []CollectionSecondaryRunStats
}

CollectionInsertStats captures phase timings and counters from the most recent successful InsertBatch call on a Collection handle.

type CollectionManager 

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

func NewCollectionManager 

func NewCollectionManager(database *backenddb.DB) *CollectionManager

func NewCommandWALReplayCollectionManager 

func NewCommandWALReplayCollectionManager(db *backenddb.DB) *CollectionManager

NewCommandWALReplayCollectionManager returns a collection manager for command-WAL replay and deterministic apply paths. It intentionally skips the backend publish-barrier and close-hook registrations used by public live managers so replay/apply can own those boundaries explicitly.

func (*CollectionManager) CompactStorage 

func (m *CollectionManager) CompactStorage(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStorage folds root overlays for all known collections and then runs the recommended full TreeDB storage compaction sequence.

func (*CollectionManager) CompactStoragePlan 

func (m *CollectionManager) CompactStoragePlan(ctx context.Context, opts CompactStorageOptions) (CompactStorageStats, error)

CompactStoragePlan reports collection-manager storage compaction debt without folding root overlays or mutating storage.

func (*CollectionManager) CreateCollection 

func (m *CollectionManager) CreateCollection(meta *CollectionMeta) (*CollectionMeta, error)

CreateCollection publishes a collection catalog entry.

Current implementations publish metadata through backend roots before success. Under the collection WAL target contract, success remains process-crash recoverable under WAL-on modes and is not an fsync guarantee unless composed with a sync-capable barrier.

func (*CollectionManager) CreateCollectionWithCommandWALIntent 

func (m *CollectionManager) CreateCollectionWithCommandWALIntent(meta CollectionMeta, commandWALIntent *backenddb.CommandWALIntent) (*CollectionMeta, error)

CreateCollectionWithCommandWALIntent applies a catalog create through the normal collection catalog executor while covering a command-WAL frame that was already appended by a deterministic apply layer.

func (*CollectionManager) CreateCollectionWithPreparedCommandWALIntent 

func (m *CollectionManager) CreateCollectionWithPreparedCommandWALIntent(meta CollectionMeta, prepareCommandWALIntent func() (*backenddb.CommandWALIntent, error)) (*CollectionMeta, error)

CreateCollectionWithPreparedCommandWALIntent applies a catalog create through the normal collection catalog executor while prepareCommandWALIntent appends and returns the already-covered command-WAL intent. The callback runs after the collection schema lock is held, preserving the public create lock order.

func (*CollectionManager) CreateCollectionWithPreparedCommandWALIntentStatus 

func (m *CollectionManager) CreateCollectionWithPreparedCommandWALIntentStatus(meta CollectionMeta, prepareCommandWALIntent func() (*backenddb.CommandWALIntent, error)) (*CollectionMeta, bool, error)

CreateCollectionWithPreparedCommandWALIntentStatus is the status-returning form of CreateCollectionWithPreparedCommandWALIntent. alreadyExisted is derived after the collection schema lock is held.

func (*CollectionManager) CreateCollectionWithPreparedCommandWALIntentStatusAndPreflight 

func (m *CollectionManager) CreateCollectionWithPreparedCommandWALIntentStatusAndPreflight(meta CollectionMeta, prepareCommandWALIntent func() (*backenddb.CommandWALIntent, error), extraPreflight backenddb.OrderedRootGroupPreflight) (*CollectionMeta, bool, error)

CreateCollectionWithPreparedCommandWALIntentStatusAndPreflight is the status-returning form of CreateCollectionWithPreparedCommandWALIntent with an extra publish preflight composed after the existing-schema no-op check.

func (*CollectionManager) FlushAll 

func (m *CollectionManager) FlushAll() error

FlushAll publishes buffered writes for every collection write domain known to this manager, then persists dirty native vector indexes registered through collection handles. The backend DB also calls this as a close hook while write APIs are still available.

func (*CollectionManager) ListCollections 

func (m *CollectionManager) ListCollections() ([]CollectionMeta, error)

func (*CollectionManager) MaintainTextIndexes 

func (m *CollectionManager) MaintainTextIndexes(ctx context.Context, opts TextIndexMaintenanceOptions) (TextIndexMaintenanceManagerStats, error)

MaintainTextIndexes runs the bounded text-v2 rewrite policy across all collections known to the manager. It performs logical rewrites first and, when requested, runs one manager-level CompactStorage pass afterward.

func (*CollectionManager) OpenCollection 

func (m *CollectionManager) OpenCollection(name string) (*Collection, error)

func (*CollectionManager) ResetUpdateCombineQueueDepthMax 

func (m *CollectionManager) ResetUpdateCombineQueueDepthMax()

ResetUpdateCombineQueueDepthMax clears the process-local update-combiner queue-depth maximum. It is intended for benchmark/profiling windows; it does not affect collection contents or pending writes.

func (*CollectionManager) ResetUpdateCombinersForProfiling 

func (m *CollectionManager) ResetUpdateCombinersForProfiling()

ResetUpdateCombinersForProfiling stops current update combiners so subsequent profiling operations recreate them inside the measured context. It is intended for benchmark/profiling harnesses; it may block while a combiner drains in-flight updates. Call it after benchmark warmup and before the measured phase; it does not flush collection contents or change update semantics.

func (*CollectionManager) SetUpdateBatchDetailedStatsEnabled 

func (m *CollectionManager) SetUpdateBatchDetailedStatsEnabled(enabled bool)

SetUpdateBatchDetailedStatsEnabled toggles high-resolution update-batch phase timings for this manager's collection write domains. Lightweight counters remain enabled either way; timings are opt-in so normal write paths do not pay for repeated clock reads unless a benchmark or profiler explicitly asks.

func (*CollectionManager) SetUpdateCombineLaneWorkersForProfiling 

func (m *CollectionManager) SetUpdateCombineLaneWorkersForProfiling(enabled bool)

SetUpdateCombineLaneWorkersForProfiling switches sharded update-combiner ingress between the global-combiner path and a lane-worker path. Lane workers prepare direct buffered update plans concurrently by document-id shard, then merge plans through the same buffered staging layer used by ordinary updates.

func (*CollectionManager) SetUpdateCombineShardsForProfiling 

func (m *CollectionManager) SetUpdateCombineShardsForProfiling(shards int)

SetUpdateCombineShardsForProfiling sets the update-combiner ingress shard count for already-opened collection write domains managed by m. It is intended for benchmark/profiling experiments and resets active combiners so subsequent updates use the new lane count.

func (*CollectionManager) Stats 

func (m *CollectionManager) Stats() map[string]string

Stats returns aggregate process-local collection write-domain metrics with stable TreeDB benchmark key names.

func (*CollectionManager) StatsSnapshot 

func (m *CollectionManager) StatsSnapshot() CollectionManagerStats

StatsSnapshot returns aggregate process-local collection write-domain counters in typed form for tests and in-process diagnostics.

type CollectionManagerStats 

type CollectionManagerStats struct {
	Domains                            int
	PendingDocuments                   int
	PendingBytes                       int64
	PendingRootRuns                    int
	PendingIndexedFlushUnits           int
	OverlayMutableDocuments            int
	OverlayQueuedIndexedFlushUnits     int
	OverlayActiveIndexedFlushUnits     int
	OverlayVisibleDepth                int
	IndexedAsyncFlushRunning           int
	MutationLockCalls                  uint64
	MutationLockWait                   time.Duration
	MutationLockHold                   time.Duration
	IndexedStageBatches                uint64
	IndexedStageDocs                   uint64
	IndexedStageBytes                  uint64
	IndexedStageRootRuns               uint64
	InsertValidationPreflightReused    uint64
	InsertValidationPreflightRechecked uint64
	IndexedAutoFlushes                 uint64
	IndexedAsyncFlushScheduled         uint64
	IndexedAsyncFlushBackpressure      uint64
	IndexedAsyncFlushWait              time.Duration
	IndexedAsyncFlushErrors            uint64
	IndexedFlushCalls                  uint64
	IndexedFlushErrors                 uint64
	IndexedFlushForcedDrains           uint64
	IndexedFlushUnits                  uint64
	IndexedFlushDocs                   uint64
	IndexedFlushBytes                  uint64
	IndexedFlushRootRuns               uint64
	IndexedFlushRoots                  uint64
	IndexedFlushDuration               time.Duration
	IndexedFlushMaterialize            time.Duration
	IndexedFlushPublish                time.Duration
	RootDeltaPlanPrimaryRoots          uint64
	RootDeltaPlanTemplateRoots         uint64
	RootDeltaPlanIndexStateRoots       uint64
	RootDeltaPlanSecondaryRoots        uint64
	RootDeltaPlanEntries               uint64
	RootDeltaPlanKeyBytes              uint64
	RootDeltaPlanValueBytes            uint64
	RootDeltaPlanTombstones            uint64
	PrimaryOnlyUpdateCalls             uint64
	PrimaryOnlyMatched                 uint64
	PrimaryOnlyModified                uint64
	PrimaryOnlyBufferedCalls           uint64
	PrimaryOnlyRootPublishes           uint64
	PrimaryOnlyRootDeltaEntries        uint64
	PrimaryOnlyRootDeltaKeyBytes       uint64
	PrimaryOnlyRootDeltaValueBytes     uint64
	PrimaryOnlyCoalescedDocs           uint64
	UpdateCombineRequests              uint64
	UpdateCombineBatches               uint64
	UpdateCombineBatchedRequests       uint64
	UpdateCombineFallbackRequests      uint64
	UpdateCombineQueueDepthMax         uint64
	UpdateCombineInlineRequests        uint64
	UpdateCombineEnqueue               time.Duration
	UpdateCombineWait                  time.Duration
	UpdateCombineQueueWait             time.Duration
	UpdateCombineDrain                 time.Duration
	UpdateCombineRun                   time.Duration
	UpdateCombineResultDelivery        time.Duration
	UpdateCombineQueueDepthBuckets     [CollectionUpdateCombineBucketCount]uint64
	UpdateCombineBatchSizeBuckets      [CollectionUpdateCombineBucketCount]uint64
	UpdateBatchCalls                   uint64
	UpdateBatchItems                   uint64
	UpdateBatchMatched                 uint64
	UpdateBatchModified                uint64
	UpdateBatchRuns                    uint64
	UpdateBatchBufferedBatches         uint64
	UpdateBatchCurrentRead             time.Duration
	UpdateBatchCallback                time.Duration
	UpdateBatchStructuredApply         time.Duration
	UpdateBatchPrepareDocuments        time.Duration
	// UpdateBatchIndexStateExtract includes UpdateBatchOldIndexStateExtract
	// and UpdateBatchNewIndexStateExtract; do not add all three together.
	UpdateBatchIndexStateExtract    time.Duration
	UpdateBatchOldIndexStateExtract time.Duration
	UpdateBatchNewIndexStateExtract time.Duration
	UpdateBatchUniquePreflight      time.Duration
	UpdateBatchTemplateRunBuild     time.Duration
	UpdateBatchPrimaryRunBuild      time.Duration
	UpdateBatchIndexStateRunBuild   time.Duration
	UpdateBatchSecondaryRunBuild    time.Duration
	UpdateBatchBufferStage          time.Duration
	// Detailed buffer-stage aggregate timings are populated only when
	// CollectionManager.SetUpdateBatchDetailedStatsEnabled(true) is enabled.
	// UpdateBatchBufferLockHold is an enclosing domain mutex hold-time metric
	// and overlaps the validation/root/index/root-append subphases; it is not
	// additive with those child counters.
	UpdateBatchBufferPrecheck        time.Duration
	UpdateBatchBufferLockWait        time.Duration
	UpdateBatchBufferLockHold        time.Duration
	UpdateBatchBufferValidation      time.Duration
	UpdateBatchBufferRootScan        time.Duration
	UpdateBatchBufferDomainPrepare   time.Duration
	UpdateBatchBufferFreeze          time.Duration
	UpdateBatchBufferRootTable       time.Duration
	UpdateBatchBufferPrimaryIdx      time.Duration
	UpdateBatchBufferUniqueIdx       time.Duration
	UpdateBatchBufferPrimaryAppend   time.Duration
	UpdateBatchBufferSecondaryAppend time.Duration
	// UpdateBatchBufferRootAppend is the total root-append time and overlaps
	// with UpdateBatchBufferPrimaryAppend and UpdateBatchBufferSecondaryAppend.
	UpdateBatchBufferRootAppend time.Duration
	// UpdateBatchBufferFlush measures only threshold-flush work that was
	// actually scheduled/executed while staging indexed buffered update batches.
	UpdateBatchBufferFlush         time.Duration
	UpdateBatchPublish             time.Duration
	UpdateBatchSecondaryDeletes    uint64
	UpdateBatchSecondarySets       uint64
	UpdateBatchSecondaryKeyBytes   uint64
	UpdateBatchIndexValueChanges   uint64
	UpdateBatchIndexValueUnchanged uint64
	UpdateBatchMaskFallbacks       uint64
	UpdateBatchUniqueChecks        uint64
	UpdateBatchUniqueCheckSkips    uint64
	UpdateBatchIndexStatsCount     int
	UpdateBatchIndexStats          [maxCollectionUpdateInlineIndexStats]CollectionUpdateIndexStats
	IndexedFlushRequeues           uint64
	IndexedFlushRequeuedUnits      uint64
	IndexedFlushLostOwnership      uint64
	IndexedFlushRootBaseMismatches uint64
}

CollectionManagerStats captures aggregate write-domain counters for a CollectionManager. The counters are process-local observability; they are not persisted with collection metadata.

The update-batch timing aggregates preserve the same nesting semantics as CollectionUpdateStats: UpdateBatchIndexStateExtract includes old/new index extraction, UpdateBatchBufferRootAppend overlaps with primary/secondary append timings, and UpdateBatchBufferLockHold encloses other buffer-stage work done while holding the write-domain mutex.

type CollectionMeta 

type CollectionMeta struct {
	Name          string                  `json:"name"`
	Options       CollectionOptions       `json:"options,omitempty"`
	Indexes       []IndexDefinition       `json:"indexes,omitempty"`
	VectorIndexes []VectorIndexDefinition `json:"vector_indexes,omitempty"`
	TextIndexes   []TextIndexDefinition   `json:"text_indexes,omitempty"`
}

type CollectionOptions 

type CollectionOptions struct {
	AllowArrayValuesInIndex bool           `json:"allow_array_values_in_index,omitempty"`
	DocumentFormat          DocumentFormat `json:"document_format,omitempty"`
	// ColumnStore enables the production-facing column-lane control-plane
	// metadata for this collection. The actual column assets, mutation adapter,
	// and command-WAL publication path are staged by later milestones.
	ColumnStore *ColumnStoreConfig `json:"column_store,omitempty"`
	// DataRootStoragePolicy selects the requested collection data-root layout.
	// Cached TreeDB backends with a persistent value-log appender promote
	// default/fast data roots to value-log leaf roots at runtime so large
	// documents can be stored through stable value pointers.
	DataRootStoragePolicy   RootStoragePolicy `json:"data_root_storage_policy,omitempty"`
	IndexStateStoragePolicy RootStoragePolicy `json:"index_state_storage_policy,omitempty"`
	// DisableIndexedWriteMemtables opts an indexed collection out of the native
	// write-domain memtable path. It is intended for debugging and baseline
	// comparisons; indexed collections use memtables by default.
	DisableIndexedWriteMemtables bool `json:"disable_indexed_write_memtables,omitempty"`
	// DisableBufferedIndexedAsyncFlush opts an indexed collection out of the
	// default background threshold-publish path. It is intended for debugging,
	// baseline comparisons, and workloads that explicitly prefer foreground
	// threshold publish. This is a publish policy, not a per-update durability
	// boundary.
	DisableBufferedIndexedAsyncFlush bool `json:"disable_buffered_indexed_async_flush,omitempty"`
	// BufferedIndexedWrites is normalized metadata describing whether indexed
	// inserts and safe update root deltas are staged in the collection write
	// domain before Flush/Close or auto-flush. Staged writes are visible to
	// primary and secondary reads on the same manager, but durability remains at
	// the flush boundary, matching the existing no-index buffered path.
	BufferedIndexedWrites bool `json:"buffered_indexed_writes,omitempty"`
	// BufferedIndexedWriteMaxDocuments flushes indexed write buffers once this
	// many staged documents are pending. Zero uses the native default for indexed
	// memtables unless DisableIndexedWriteMemtables is set or the schema has no
	// indexes.
	BufferedIndexedWriteMaxDocuments int `json:"buffered_indexed_write_max_documents,omitempty"`
	// BufferedIndexedWriteMaxBytes flushes indexed write buffers once the staged
	// root-run payload estimate reaches this many bytes. Zero leaves flushing to
	// explicit Flush/Close calls.
	BufferedIndexedWriteMaxBytes int64 `json:"buffered_indexed_write_max_bytes,omitempty"`
	// BufferedIndexedWriteMaxRootRuns flushes indexed write buffers once this
	// many root-local mutation runs are pending. Zero disables the run-count
	// trigger when another flush limit is explicitly configured; when all
	// indexed buffer limits are zero, metadata normalization installs native
	// defaults.
	BufferedIndexedWriteMaxRootRuns int `json:"buffered_indexed_write_max_root_runs,omitempty"`
	// BufferedIndexedAsyncFlush lets threshold-triggered indexed memtable flushes
	// publish from a background goroutine. Indexed schemas enable this by
	// default unless DisableBufferedIndexedAsyncFlush is set. Flush, FlushAll,
	// and backend Close still drain pending indexed writes before returning, but
	// auto-flush thresholds do not imply per-update durability.
	BufferedIndexedAsyncFlush bool `json:"buffered_indexed_async_flush,omitempty"`
	// BufferedIndexedOverlayRoots publishes indexed memtable flush units as
	// durable overlay roots instead of immediately applying them into base roots.
	// Maintenance can later compact overlay roots into base roots; reads merge
	// overlay roots over base roots while they are pending.
	BufferedIndexedOverlayRoots bool `json:"buffered_indexed_overlay_roots,omitempty"`
	// BufferedIndexedAsyncFlushMaxQueuedUnits bounds immutable indexed flush
	// units queued for the background publisher. Zero uses the native default
	// when async flush is enabled on an indexed schema.
	BufferedIndexedAsyncFlushMaxQueuedUnits int `json:"buffered_indexed_async_flush_max_queued_units,omitempty"`
}

type CollectionReadView 

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

CollectionReadView is a closeable snapshot-bound document materializer for a collection. It preserves the catalog/root visibility that existed when the view was opened. Returned documents are owned by the fetch response. The view is not concurrency-safe; callers that fetch concurrently should open one view per worker or synchronize externally.

func (*CollectionReadView) Close 

func (v *CollectionReadView) Close() error

Close releases the snapshot owned by the read view. Views that are bound to a caller-owned snapshot still become closed, but leave snapshot release to the owner.

func (*CollectionReadView) FetchDocumentsByID 

func (v *CollectionReadView) FetchDocumentsByID(ids [][]byte, opts DocumentFetchOptions) (DocumentFetchResponse, error)

FetchDocumentsByID materializes full documents for ids in input order. Missing documents produce Found=false results without failing the whole fetch.

func (*CollectionReadView) FetchDocumentsByRowRef 

func (v *CollectionReadView) FetchDocumentsByRowRef(refs []DocumentRowRef, opts DocumentFetchOptions) (DocumentFetchResponse, error)

FetchDocumentsByRowRef materializes full documents for row refs in input order. Supported typed-row refs are point-fetched by generation/part/row_index and validated against the decoded physical row before reconstruction. Row-ref fetches are strict: a missing primary-root document, stale ref, or physical mismatch fails the request instead of silently returning a partial batch.

func (*CollectionReadView) FetchDocumentsForVectorIndexSearchResults 

func (v *CollectionReadView) FetchDocumentsForVectorIndexSearchResults(results []VectorIndexSearchResult, opts DocumentFetchOptions) (DocumentFetchResponse, error)

FetchDocumentsForVectorIndexSearchResults materializes documents for an already completed vector-index search result list, preserving result order. It is an explicit post-search fetch helper for callers that keep the ANN search/scoring path no-document (IncludeDocuments=false) and then decide to materialize the returned top-k IDs outside the high-QPS search boundary.

The fetch is bound to this CollectionReadView's snapshot, not implicitly to the snapshot used by the search call that produced results. Open the read view at the visibility point you want to materialize. If same-snapshot search plus document materialization is required, use IncludeDocuments=true on SearchVectorIndex or VectorIndexSearcher.Search instead and report those document counters as part of that explicit with-documents path.

Results returned by SearchVectorIndexWithBuffer alias the caller's VectorIndexSearchBuffer; do not reuse or reset that buffer until this helper returns if those IDs are the fetch input.

func (*CollectionReadView) LookupDocumentRowRefsByID 

func (v *CollectionReadView) LookupDocumentRowRefsByID(ids [][]byte, opts DocumentFetchOptions) (DocumentRowRefLookupResponse, error)

LookupDocumentRowRefsByID resolves document IDs to snapshot-visible typed-row refs in input order. It builds or reuses a generic materializer row-locator map for the read view; missing or deleted documents return Found=false.

type CollectionRootOverlayCompactionStats 

type CollectionRootOverlayCompactionStats struct {
	Roots        int
	OverlayRoots int
}

type CollectionSecondaryRunStats 

type CollectionSecondaryRunStats struct {
	IndexName     string
	Entries       int
	KeyBytes      int
	AlreadySorted bool
	Build         time.Duration
}

CollectionSecondaryRunStats captures per-secondary-index run construction counters from an InsertBatch call.

type CollectionUpdateIndexStats 

type CollectionUpdateIndexStats struct {
	CollectionName    string
	IndexName         string
	IndexOrdinal      int
	Unique            bool
	Changed           int
	Unchanged         int
	UniqueChecks      int
	UniqueCheckSkips  int
	SecondaryRuns     int
	SecondaryDeletes  int
	SecondarySets     int
	SecondaryKeyBytes int
}

CollectionUpdateIndexStats captures per-index update planning decisions from an UpdateBatch-style call. Changed/unchanged are counted per modified document for each cached index runtime.

type CollectionUpdateSecondaryRunStats 

type CollectionUpdateSecondaryRunStats struct {
	IndexName string
	Deletes   int
	Sets      int
	KeyBytes  int
}

CollectionUpdateSecondaryRunStats captures per-secondary-index delta counters from an UpdateBatch-style call.

type CollectionUpdateStats 

type CollectionUpdateStats struct {
	Items           int
	Matched         int
	Modified        int
	Indexes         int
	Runs            int
	BufferedBatches int
	CurrentRead     time.Duration
	Callback        time.Duration
	// StructuredUpdateApply measures built-in structured update application,
	// such as BSON $set, separately from user callback time.
	StructuredUpdateApply        time.Duration
	StructuredUpdateApplications int
	PrepareDocuments             time.Duration
	// IndexStateExtraction includes both OldIndexStateExtract and
	// NewIndexStateExtract; do not add all three together.
	IndexStateExtraction time.Duration
	OldIndexStateExtract time.Duration
	NewIndexStateExtract time.Duration
	UniqueIndexPreflight time.Duration
	TemplateRunBuild     time.Duration
	PrimaryRunBuild      time.Duration
	IndexStateRunBuild   time.Duration
	SecondaryRunBuild    time.Duration
	BufferStage          time.Duration
	// Buffer-stage subphase timings are populated only when
	// CollectionManager.SetUpdateBatchDetailedStatsEnabled(true) is enabled.
	// BufferStageLockHold is an enclosing domain mutex hold-time metric and
	// overlaps the validation/root/index/root-append subphases; it is not
	// additive with those child counters.
	BufferStagePrecheck time.Duration
	// BufferStageLockWait measures domain mutex acquisition time, including
	// relock contention after an async flush wait. It does not include async
	// flush completion waits performed after releasing the mutex for
	// backpressure.
	BufferStageLockWait        time.Duration
	BufferStageLockHold        time.Duration
	BufferStageValidation      time.Duration
	BufferStageRootScan        time.Duration
	BufferStageDomainPrepare   time.Duration
	BufferStageFreeze          time.Duration
	BufferStageRootTable       time.Duration
	BufferStagePrimaryIdx      time.Duration
	BufferStageUniqueIdx       time.Duration
	BufferStagePrimaryAppend   time.Duration
	BufferStageSecondaryAppend time.Duration
	// BufferStageRootAppend is the total root-append time and overlaps with
	// BufferStagePrimaryAppend and BufferStageSecondaryAppend.
	BufferStageRootAppend time.Duration
	// BufferStageFlush measures local threshold-flush schedule/publish work
	// performed while staging an indexed buffered update batch. It excludes
	// waits for an already-running async flush that leave no local schedule or
	// publish work for the current batch.
	BufferStageFlush       time.Duration
	Publish                time.Duration
	SecondaryDeleteEntries int
	SecondarySetEntries    int
	SecondaryKeyBytes      int
	SecondaryRuns          []CollectionUpdateSecondaryRunStats
	IndexValueChanges      int
	IndexValueUnchanged    int
	MaskFallbacks          int
	UniqueIndexChecks      int
	UniqueIndexCheckSkips  int
	// IndexStats is populated for the first inline index runtimes when detailed
	// update-batch stats are enabled. The first IndexStatsCount entries are
	// valid; remaining indexes are represented only by aggregate counters.
	IndexStatsCount int
	IndexStats      [maxCollectionUpdateInlineIndexStats]CollectionUpdateIndexStats
}

CollectionUpdateStats captures phase timings and counters from the most recent successful Update/UpdateBatch-style call on a Collection handle.

Some timings are nested rather than additive siblings. IndexStateExtraction is the total time spent extracting old and new index state; OldIndexStateExtract and NewIndexStateExtract are components of that total. BufferStageRootAppend overlaps with BufferStagePrimaryAppend and BufferStageSecondaryAppend, and BufferStageLockHold encloses other buffer-stage subphases while the write domain mutex is held.

type ColumnAdjacencyListLayout 

type ColumnAdjacencyListLayout string
const (
	// Empty preserves the existing fixed-degree dense adjacency layout selected
	// by adjacency_degree. The #1901 v1 variable-list primitive must be selected
	// explicitly and must not be inferred from a missing degree.
	ColumnAdjacencyListLayoutFixedDense        ColumnAdjacencyListLayout = ""
	ColumnAdjacencyListLayoutUint32OffsetsList ColumnAdjacencyListLayout = "uint32_offsets_list"
)

type ColumnAggregateKind 

type ColumnAggregateKind string
const (
	ColumnAggregateCount          ColumnAggregateKind = "count"
	ColumnAggregateGroupHourCount ColumnAggregateKind = "group-hour-count"
	ColumnAggregateMin            ColumnAggregateKind = "min"
	ColumnAggregateMax            ColumnAggregateKind = "max"
	ColumnAggregateSum            ColumnAggregateKind = "sum"
	ColumnAggregateCountDistinct  ColumnAggregateKind = "count-distinct"
)

type ColumnAggregateMetadata 

type ColumnAggregateMetadata struct {
	Name        string                         `json:"name"`
	Column      string                         `json:"column,omitempty"`
	GroupColumn string                         `json:"group_column,omitempty"`
	Kind        ColumnAggregateKind            `json:"kind"`
	Predicates  []ColumnPhysicalQueryPredicate `json:"predicates,omitempty"`
}

type ColumnAssetCacheIdentity 

type ColumnAssetCacheIdentity struct {
	Segment  uint32
	Offset   uint64
	Length   uint32
	Checksum uint32
}

type ColumnAssetGCOptions 

type ColumnAssetGCOptions struct {
	DryRun bool
	// Detailed keeps detailed ref and segment entries in the returned plan.
	Detailed bool
	// SegmentDetails keeps segment-level entries in the returned plan without
	// retaining per-ref entries.
	SegmentDetails     bool
	CandidateRefs      []ColumnAssetRef
	PendingRefs        []ColumnAssetRef
	PreparedRefs       []ColumnAssetRef
	PreparedQueryRefs  []ColumnAssetRef
	QuarantineRefs     []ColumnAssetRef
	QuarantineSegments []ColumnAssetQuarantineSegment
	PinnedRefs         []ColumnAssetRef
}

ColumnAssetGCOptions controls safe M15B column asset segment reclamation.

type ColumnAssetGCStats 

type ColumnAssetGCStats struct {
	DryRun bool

	Plan ColumnAssetReachabilityPlan

	SegmentsEligible int
	SegmentsDeleted  int
	SegmentsRetained int
	BytesEligible    int64
	BytesDeleted     int64
	BytesRetained    int64
}

ColumnAssetGCStats summarizes safe whole-segment column asset reclamation.

type ColumnAssetKind 

type ColumnAssetKind string

ColumnAssetKind identifies the storage format behind a column asset ref. 

const (
	// ColumnAssetKindTCS1PartImage references an immutable typed-row TCS1/TCPA
	// part image retained for compatibility.
	ColumnAssetKindTCS1PartImage ColumnAssetKind = "tcs1_part_image"
	// ColumnAssetKindTCS1TypedColumnPart references an immutable sectioned
	// typed-column TCS1 part image.
	ColumnAssetKindTCS1TypedColumnPart ColumnAssetKind = "tcs1_typed_column_part"
	// ColumnAssetKindTCS1AggregateMetadata references grouped aggregate metadata
	// stored as a typed column asset beside physical part images.
	ColumnAssetKindTCS1AggregateMetadata ColumnAssetKind = "tcs1_aggregate_metadata"
	// ColumnAssetKindTCS1DictionaryCodes references low-cardinality dictionary
	// codes derived from one declared dictionary string column in a TCS1 part.
	ColumnAssetKindTCS1DictionaryCodes ColumnAssetKind = "tcs1_dictionary_codes"
	// ColumnAssetKindTCS1Int64Values references dense int64 values derived from
	// one non-null declared int64 column in a TCS1 part.
	ColumnAssetKindTCS1Int64Values ColumnAssetKind = "tcs1_int64_values"
	// ColumnAssetKindTCS1HNSWSearchPack references one durable
	// hnsw_search_pack_v1 serving artifact owned by vector-index state.
	ColumnAssetKindTCS1HNSWSearchPack ColumnAssetKind = "tcs1_hnsw_search_pack"
)

type ColumnAssetLifecycleActionSummary 

type ColumnAssetLifecycleActionSummary struct {
	DestructiveActionsEnabled bool  `json:"destructive_actions_enabled"`
	GCEligibleSegments        int   `json:"gc_eligible_segments"`
	GCEligibleBytes           int64 `json:"gc_eligible_bytes"`
	RewriteDebtBytes          int64 `json:"rewrite_debt_bytes"`
}

ColumnAssetLifecycleActionSummary is intentionally non-destructive.

type ColumnAssetLifecycleByteClasses 

type ColumnAssetLifecycleByteClasses struct {
	ManifestCatalogBytes      int64 `json:"manifest_catalog_bytes"`
	ReferencedAssetBytes      int64 `json:"referenced_asset_bytes"`
	LiveBytes                 int64 `json:"live_bytes"`
	StaleBytes                int64 `json:"stale_bytes"`
	ProtectedBytes            int64 `json:"protected_bytes"`
	RewriteDebtBytes          int64 `json:"rewrite_debt_bytes"`
	ReclaimableBytes          int64 `json:"reclaimable_bytes"`
	ActivePinBytes            int64 `json:"active_pin_bytes"`
	PreparedAssetBytes        int64 `json:"prepared_asset_bytes"`
	PreparedQueryBytes        int64 `json:"prepared_query_bytes"`
	PendingPublishBytes       int64 `json:"pending_publish_bytes"`
	SnapshotPinnedBytes       int64 `json:"snapshot_pinned_bytes"`
	MappedResourcePinnedBytes int64 `json:"mappedresource_pinned_bytes"`
	QuarantineBytes           int64 `json:"quarantine_bytes"`
}

ColumnAssetLifecycleByteClasses keeps manifest/catalog bytes separate from referenced asset/section bytes and exposes overlapping safety classes used by JSONBench lifecycle diagnostics.

type ColumnAssetLifecycleIdentity 

type ColumnAssetLifecycleIdentity struct {
	Collection                 string `json:"collection,omitempty"`
	Namespace                  string `json:"namespace,omitempty"`
	ManifestRootName           string `json:"manifest_root_name,omitempty"`
	ManifestRootID             uint64 `json:"manifest_root_id,omitempty"`
	SystemRoot                 uint64 `json:"system_root,omitempty"`
	PlanCommitSeq              uint64 `json:"plan_commit_seq,omitempty"`
	LifecycleRunID             string `json:"lifecycle_run_id,omitempty"`
	ActiveManifestGeneration   uint64 `json:"active_manifest_generation,omitempty"`
	ActiveManifestChecksum     uint64 `json:"active_manifest_checksum,omitempty"`
	RecoveryManifestGeneration uint64 `json:"recovery_manifest_generation,omitempty"`
	RecoveryManifestChecksum   uint64 `json:"recovery_manifest_checksum,omitempty"`
}

ColumnAssetLifecycleIdentity records the system/catalog/manifest identity used to build a lifecycle report.

type ColumnAssetLifecycleIncompleteReason 

type ColumnAssetLifecycleIncompleteReason string

ColumnAssetLifecycleIncompleteReason is a stable report label describing why the lifecycle report is not complete enough for destructive consumers. 

const (
	ColumnAssetLifecycleIncompleteReachabilityPlan               ColumnAssetLifecycleIncompleteReason = "reachability_plan_incomplete"
	ColumnAssetLifecycleIncompleteUnknownSegments                ColumnAssetLifecycleIncompleteReason = "unknown_segments"
	ColumnAssetLifecycleIncompleteMissingSegments                ColumnAssetLifecycleIncompleteReason = "missing_segments"
	ColumnAssetLifecycleIncompleteOutOfBoundsRefs                ColumnAssetLifecycleIncompleteReason = "out_of_bounds_refs"
	ColumnAssetLifecycleIncompleteMappedResourcePins             ColumnAssetLifecycleIncompleteReason = "mappedresource_unconvertible_pins"
	ColumnAssetLifecycleIncompletePendingPublishRegistry         ColumnAssetLifecycleIncompleteReason = "pending_publish_registry_unavailable"
	ColumnAssetLifecycleIncompletePreparedAssetRegistry          ColumnAssetLifecycleIncompleteReason = "prepared_asset_registry_unavailable"
	ColumnAssetLifecycleIncompleteQuarantineRegistry             ColumnAssetLifecycleIncompleteReason = "quarantine_registry_unavailable"
	ColumnAssetLifecycleIncompletePendingPublishProcessLocalOnly ColumnAssetLifecycleIncompleteReason = "pending_publish_registry_process_local_only"
	ColumnAssetLifecycleIncompletePreparedAssetProcessLocalOnly  ColumnAssetLifecycleIncompleteReason = "prepared_asset_registry_process_local_only"
	ColumnAssetLifecycleIncompleteQuarantineProcessLocalOnly     ColumnAssetLifecycleIncompleteReason = "quarantine_registry_process_local_only"
	ColumnAssetLifecycleIncompletePinnedSnapshotExactRoots       ColumnAssetLifecycleIncompleteReason = "pinned_snapshot_exact_roots_unavailable"
	ColumnAssetLifecycleIncompleteQuarantineSegmentUncertain     ColumnAssetLifecycleIncompleteReason = "quarantine_segment_uncertain"
)

type ColumnAssetLifecycleOptions 

type ColumnAssetLifecycleOptions struct {
	Detailed           bool                           `json:"detailed,omitempty"`
	SegmentDetails     bool                           `json:"segment_details,omitempty"`
	CandidateRefs      []ColumnAssetRef               `json:"candidate_refs,omitempty"`
	SupersededRefs     []ColumnAssetRef               `json:"superseded_refs,omitempty"`
	PendingRefs        []ColumnAssetRef               `json:"pending_refs,omitempty"`
	PreparedRefs       []ColumnAssetRef               `json:"prepared_refs,omitempty"`
	PreparedQueryRefs  []ColumnAssetRef               `json:"prepared_query_refs,omitempty"`
	QuarantineRefs     []ColumnAssetRef               `json:"quarantine_refs,omitempty"`
	QuarantineSegments []ColumnAssetQuarantineSegment `json:"quarantine_segments,omitempty"`
	PinnedRefs         []ColumnAssetRef               `json:"pinned_refs,omitempty"`
}

ColumnAssetLifecycleOptions controls the report-only collection asset lifecycle planner. CandidateRefs and SupersededRefs are both supplied to the underlying reachability plan as reclaimable candidates, but are counted separately in the report.

type ColumnAssetLifecyclePinSet 

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

ColumnAssetLifecyclePinSet is a process-local lease over a caller-supplied set of column asset refs. Close releases the lease from lifecycle reports.

func (*ColumnAssetLifecyclePinSet) Close 

func (p *ColumnAssetLifecyclePinSet) Close() error

Close releases the process-local lifecycle pin set. It is idempotent.

func (*ColumnAssetLifecyclePinSet) ID 

func (p *ColumnAssetLifecyclePinSet) ID() uint64

ID returns the process-local lease identifier.

func (*ColumnAssetLifecyclePinSet) Refs 

func (p *ColumnAssetLifecyclePinSet) Refs() []ColumnAssetRef

Refs returns a defensive copy of the pinned refs.

func (*ColumnAssetLifecyclePinSet) Source 

func (p *ColumnAssetLifecyclePinSet) Source() ColumnAssetLifecyclePinSource

Source returns the logical pin source supplied at acquisition time.

type ColumnAssetLifecyclePinSetOptions 

type ColumnAssetLifecyclePinSetOptions struct {
	Source ColumnAssetLifecyclePinSource `json:"source"`
	Owner  string                        `json:"owner"`
	Reason string                        `json:"reason,omitempty"`
	Refs   []ColumnAssetRef              `json:"refs,omitempty"`
}

ColumnAssetLifecyclePinSetOptions describes an explicit process-local pin set lease. It is intentionally in-memory/report-only in slice 1; callers must not assume this changes destructive maintenance behavior yet.

type ColumnAssetLifecyclePinSource 

type ColumnAssetLifecyclePinSource string

ColumnAssetLifecyclePinSource identifies the logical owner of an explicit process-local lifecycle pin set. Slice 1 reports these pins but does not wire them into GC/rewrite deletion policy. 

const (
	ColumnAssetLifecyclePinSourcePreparedQuery  ColumnAssetLifecyclePinSource = "prepared_query"
	ColumnAssetLifecyclePinSourcePreparedAsset  ColumnAssetLifecyclePinSource = "prepared_asset"
	ColumnAssetLifecyclePinSourcePendingPublish ColumnAssetLifecyclePinSource = "pending_publish"
	ColumnAssetLifecyclePinSourcePinnedSnapshot ColumnAssetLifecyclePinSource = "pinned_snapshot"
)

type ColumnAssetLifecyclePinSourceSummary 

type ColumnAssetLifecyclePinSourceSummary struct {
	Source       ColumnAssetLifecyclePinSource `json:"source"`
	OpenSessions int                           `json:"open_sessions"`
	Refs         int                           `json:"refs"`
	Bytes        int64                         `json:"bytes"`
}

ColumnAssetLifecyclePinSourceSummary is a per-source rollup for lifecycle pin sets.

type ColumnAssetLifecyclePinSummary 

type ColumnAssetLifecyclePinSummary struct {
	OpenSessions  int                                    `json:"open_sessions"`
	Refs          int                                    `json:"refs"`
	Bytes         int64                                  `json:"bytes"`
	CloseErrors   int                                    `json:"close_errors"`
	LeakedLeases  int                                    `json:"leaked_leases"`
	ExpiredLeases int                                    `json:"expired_leases"`
	Sources       []ColumnAssetLifecyclePinSourceSummary `json:"sources,omitempty"`
}

ColumnAssetLifecyclePinSummary summarizes explicit process-local lifecycle pin sets across all lifecycle pin sources. The close/leak/expiry counters are scaffolding slots for later durable registries and remain zero in slice 1.

type ColumnAssetLifecycleQuarantineSummary 

type ColumnAssetLifecycleQuarantineSummary struct {
	RegistryAvailable bool                                        `json:"registry_available"`
	Durable           bool                                        `json:"durable"`
	ProcessLocal      bool                                        `json:"process_local"`
	OpenRecords       int                                         `json:"open_records"`
	Refs              int                                         `json:"refs"`
	Bytes             int64                                       `json:"bytes"`
	Segments          int                                         `json:"segments"`
	SegmentBytes      int64                                       `json:"segment_bytes"`
	Sources           []ColumnAssetLifecycleRegistrySourceSummary `json:"sources,omitempty"`
}

ColumnAssetLifecycleQuarantineSummary is report-only scaffolding for the future durable quarantine registry. Slice 2 records are process-local logical records only; no asset is moved, renamed, deleted, or truncated.

type ColumnAssetLifecycleRegistryClass 

type ColumnAssetLifecycleRegistryClass string

ColumnAssetLifecycleRegistryClass identifies the logical registry a process-local lifecycle record belongs to. 

const (
	ColumnAssetLifecycleRegistryPendingPublish ColumnAssetLifecycleRegistryClass = "pending_publish"
	ColumnAssetLifecycleRegistryPreparedAsset  ColumnAssetLifecycleRegistryClass = "prepared_asset"
	ColumnAssetLifecycleRegistryQuarantine     ColumnAssetLifecycleRegistryClass = "quarantine"
)

type ColumnAssetLifecycleRegistryLease 

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

ColumnAssetLifecycleRegistryLease is an idempotent close/release handle for a process-local lifecycle registry record.

func (*ColumnAssetLifecycleRegistryLease) Class 

func (l *ColumnAssetLifecycleRegistryLease) Class() ColumnAssetLifecycleRegistryClass

Class returns the lifecycle registry class for this lease.

func (*ColumnAssetLifecycleRegistryLease) Close 

func (l *ColumnAssetLifecycleRegistryLease) Close() error

Close releases the process-local registry record. It is idempotent.

func (*ColumnAssetLifecycleRegistryLease) ID 

func (l *ColumnAssetLifecycleRegistryLease) ID() uint64

ID returns the process-local registry record identifier.

func (*ColumnAssetLifecycleRegistryLease) Refs 

func (l *ColumnAssetLifecycleRegistryLease) Refs() []ColumnAssetRef

Refs returns a defensive copy of the registered refs.

func (*ColumnAssetLifecycleRegistryLease) Release 

func (l *ColumnAssetLifecycleRegistryLease) Release() error

Release releases the process-local registry record. It is idempotent.

func (*ColumnAssetLifecycleRegistryLease) Segments 

func (l *ColumnAssetLifecycleRegistryLease) Segments() []ColumnAssetQuarantineSegment

Segments returns a defensive copy of the registered quarantine segments.

func (*ColumnAssetLifecycleRegistryLease) Source 

func (l *ColumnAssetLifecycleRegistryLease) Source() string

Source returns the caller-supplied source label for this lease.

type ColumnAssetLifecycleRegistrySourceSummary 

type ColumnAssetLifecycleRegistrySourceSummary struct {
	Source       string `json:"source"`
	OpenRecords  int    `json:"open_records"`
	Refs         int    `json:"refs"`
	Bytes        int64  `json:"bytes"`
	Segments     int    `json:"segments,omitempty"`
	SegmentBytes int64  `json:"segment_bytes,omitempty"`
}

ColumnAssetLifecycleRegistrySourceSummary is a per-source-label rollup for pending publish, prepared asset, and quarantine registry records.

type ColumnAssetLifecycleRegistrySummary 

type ColumnAssetLifecycleRegistrySummary struct {
	RegistryAvailable bool                                        `json:"registry_available"`
	Durable           bool                                        `json:"durable"`
	ProcessLocal      bool                                        `json:"process_local"`
	OpenRecords       int                                         `json:"open_records"`
	Refs              int                                         `json:"refs"`
	Bytes             int64                                       `json:"bytes"`
	Sources           []ColumnAssetLifecycleRegistrySourceSummary `json:"sources,omitempty"`
}

ColumnAssetLifecycleRegistrySummary summarizes process-local explicit registry records that feed lifecycle reports. Durable remains false until a future slice defines on-disk registry storage/recovery semantics.

type ColumnAssetLifecycleReport 

type ColumnAssetLifecycleReport struct {
	DryRun               bool                                       `json:"dry_run"`
	ReportOnly           bool                                       `json:"report_only"`
	Complete             bool                                       `json:"complete"`
	ReachabilityComplete bool                                       `json:"reachability_complete"`
	IncompleteReasons    []ColumnAssetLifecycleIncompleteReason     `json:"incomplete_reasons,omitempty"`
	Identity             ColumnAssetLifecycleIdentity               `json:"identity"`
	Roots                ColumnAssetLifecycleRootCounts             `json:"roots"`
	SnapshotFence        ColumnAssetLifecycleSnapshotFence          `json:"snapshot_fence"`
	MappedResources      ColumnAssetReachabilityMappedResourceStats `json:"mappedresource"`
	PinSets              ColumnAssetLifecyclePinSummary             `json:"pin_sets"`
	PendingPublish       ColumnAssetLifecycleRegistrySummary        `json:"pending_publish"`
	PreparedAssets       ColumnAssetLifecycleRegistrySummary        `json:"prepared_assets"`
	Quarantine           ColumnAssetLifecycleQuarantineSummary      `json:"quarantine"`
	Bytes                ColumnAssetLifecycleByteClasses            `json:"bytes"`
	Actions              ColumnAssetLifecycleActionSummary          `json:"actions"`
	Reachability         ColumnAssetReachabilityPlan                `json:"reachability"`
}

ColumnAssetLifecycleReport is the stable JSON/report shape for collection- level lifecycle roots. It is report-only and fail-closed; Complete remains false while registries are process-local/non-durable or exact pinned snapshot roots are not available to the planner.

type ColumnAssetLifecycleRootCounts 

type ColumnAssetLifecycleRootCounts struct {
	ManifestRoots                 int `json:"manifest_roots"`
	ManifestRecords               int `json:"manifest_records"`
	ActiveManifestRefs            int `json:"active_manifest_refs"`
	RecoveryManifestRefs          int `json:"recovery_manifest_refs"`
	CandidateRefs                 int `json:"candidate_refs"`
	SupersededRefs                int `json:"superseded_refs"`
	PendingPublishRefs            int `json:"pending_publish_refs"`
	PreparedAssetRefs             int `json:"prepared_asset_refs"`
	PreparedQueryRefs             int `json:"prepared_query_refs"`
	PinnedSnapshotRefs            int `json:"pinned_snapshot_refs"`
	MappedResourcePins            int `json:"mappedresource_pins"`
	LifecyclePinSets              int `json:"lifecycle_pin_sets"`
	LifecyclePinnedRefs           int `json:"lifecycle_pinned_refs"`
	PendingPublishRegistryRecords int `json:"pending_publish_registry_records"`
	PreparedAssetRegistryRecords  int `json:"prepared_asset_registry_records"`
	QuarantineRegistryRecords     int `json:"quarantine_registry_records"`
	QuarantineRefs                int `json:"quarantine_refs"`
	QuarantineSegments            int `json:"quarantine_segments"`
}

ColumnAssetLifecycleRootCounts summarizes refs by lifecycle root source.

type ColumnAssetLifecycleSnapshotFence 

type ColumnAssetLifecycleSnapshotFence struct {
	PlanCommitSeq               uint64 `json:"plan_commit_seq,omitempty"`
	MinPinnedSnapshotCommitSeq  uint64 `json:"min_pinned_snapshot_commit_seq,omitempty"`
	OlderSnapshotPinned         bool   `json:"older_snapshot_pinned"`
	ExactSnapshotRootsAvailable bool   `json:"exact_snapshot_roots_available"`
}

ColumnAssetLifecycleSnapshotFence reports the process-local pinned snapshot fence available today. Exact historical manifest roots are not available in slice 1, so older pinned snapshots make the lifecycle report incomplete.

type ColumnAssetManagerConfig 

type ColumnAssetManagerConfig struct {
	// Kind names the typed column asset manager backend. The V1 value-log-shaped
	// backend owns an isolated column asset namespace; it is not ordinary value_vlog.
	Kind              ColumnAssetManagerKind `json:"kind,omitempty"`
	IsolatedNamespace bool                   `json:"isolated_namespace,omitempty"`
	Namespace         string                 `json:"namespace,omitempty"`
}

type ColumnAssetManagerKind 

type ColumnAssetManagerKind string
const (
	// ColumnAssetManagerValueLogShaped is an isolated typed column asset manager
	// that reuses value-log-like segment refs. It must not mean ordinary TreeDB
	// value_vlog ownership.
	ColumnAssetManagerValueLogShaped ColumnAssetManagerKind = "value-log-shaped"
	// ColumnAssetManagerValueLog is kept as a source-compatible alias for the
	// value-log-shaped column asset manager.
	ColumnAssetManagerValueLog = ColumnAssetManagerValueLogShaped
)

type ColumnAssetPendingPublishRegistrationOptions 

type ColumnAssetPendingPublishRegistrationOptions struct {
	Owner  string           `json:"owner"`
	Source string           `json:"source"`
	Reason string           `json:"reason,omitempty"`
	Refs   []ColumnAssetRef `json:"refs,omitempty"`
}

ColumnAssetPendingPublishRegistrationOptions registers refs that are staged for a manifest/root publish whose outcome is not yet unambiguous. Slice 2 records are process-local and report-only.

type ColumnAssetPreparedAssetRegistrationOptions 

type ColumnAssetPreparedAssetRegistrationOptions struct {
	Owner  string           `json:"owner"`
	Source string           `json:"source"`
	Reason string           `json:"reason,omitempty"`
	Refs   []ColumnAssetRef `json:"refs,omitempty"`
}

ColumnAssetPreparedAssetRegistrationOptions registers prepared/staged asset refs that must be reported as protected roots until the lease is released.

type ColumnAssetQuarantineRegistrationOptions 

type ColumnAssetQuarantineRegistrationOptions struct {
	Owner    string                         `json:"owner"`
	Source   string                         `json:"source"`
	Reason   string                         `json:"reason,omitempty"`
	Refs     []ColumnAssetRef               `json:"refs,omitempty"`
	Segments []ColumnAssetQuarantineSegment `json:"segments,omitempty"`
}

ColumnAssetQuarantineRegistrationOptions registers logical quarantine records for refs or whole segments. It does not move, rename, delete, truncate, or otherwise mutate the recorded assets.

type ColumnAssetQuarantineSegment 

type ColumnAssetQuarantineSegment struct {
	Namespace string `json:"namespace,omitempty"`
	FileID    uint32 `json:"file_id"`
	Bytes     int64  `json:"bytes,omitempty"`
	Reason    string `json:"reason,omitempty"`
}

ColumnAssetQuarantineSegment describes a logical segment-level quarantine record. Bytes may be zero when the caller has not measured the segment size.

type ColumnAssetReachabilityMappedResourceStats 

type ColumnAssetReachabilityMappedResourceStats struct {
	ActiveHandles              int
	ActiveMappedBytes          int64
	ActiveHeapCopyBytes        int64
	ActiveDerivedMetadataBytes int64
	PinnedRefs                 int
	PinnedBytes                int64
	UnconvertiblePins          int
	DeniedResources            uint64
	FallbackReads              uint64
}

ColumnAssetReachabilityMappedResourceStats summarizes active #1736 mappedresource handles observed while building a maintenance plan. The byte counters are active process-local handle bytes, not heap allocations by the planner itself.

type ColumnAssetReachabilityOptions 

type ColumnAssetReachabilityOptions struct {
	Detailed       bool
	SegmentDetails bool
	// ProtectCandidateRefsForOlderSnapshots conservatively treats candidate
	// refs as pinned while any active TreeDB snapshot predates the planning
	// snapshot. Destructive GC enables this; non-destructive rewrite leaves it
	// off so it can remap current manifest refs while retaining old segments.
	ProtectCandidateRefsForOlderSnapshots bool
	CandidateRefs                         []ColumnAssetRef
	PendingRefs                           []ColumnAssetRef
	PreparedRefs                          []ColumnAssetRef
	PreparedQueryRefs                     []ColumnAssetRef
	QuarantineRefs                        []ColumnAssetRef
	QuarantineSegments                    []ColumnAssetQuarantineSegment
	PinnedRefs                            []ColumnAssetRef
}

ColumnAssetReachabilityOptions controls protect-only reachability planning. CandidateRefs are possible reclamation inputs supplied by the typed column asset manager/catalog index; pending, prepared, and pinned refs are always retained. Detailed emits per-ref and per-segment entries. SegmentDetails emits only per-segment entries and is implied by Detailed.

type ColumnAssetReachabilityPlan 

type ColumnAssetReachabilityPlan struct {
	ProtectOnly                bool
	Complete                   bool
	Collection                 string
	Namespace                  string
	ManifestRootName           string
	ManifestRootID             uint64
	SystemRoot                 uint64
	PlanCommitSeq              uint64
	ActiveManifestGeneration   uint64
	ActiveManifestChecksum     uint64
	RecoveryManifestGeneration uint64
	RecoveryManifestChecksum   uint64
	ManifestCatalogBytes       int64
	Sources                    ColumnAssetReachabilitySourceStats
	Refs                       ColumnAssetReachabilityRefStats
	Segments                   ColumnAssetReachabilitySegmentStats
	MappedResources            ColumnAssetReachabilityMappedResourceStats
	RewriteDebtBytes           int64
	Entries                    []ColumnAssetReachabilityRefEntry
	SegmentEntries             []ColumnAssetReachabilitySegmentEntry
}

type ColumnAssetReachabilityRefEntry 

type ColumnAssetReachabilityRefEntry struct {
	Ref     ColumnAssetRef
	Status  ColumnAssetReachabilityStatus
	Sources []ColumnAssetReachabilitySource
}

type ColumnAssetReachabilityRefStats 

type ColumnAssetReachabilityRefStats struct {
	Total            int
	Protected        int
	Reclaimable      int
	Uncertain        int
	BytesTotal       int64
	BytesProtected   int64
	BytesReclaimable int64
	BytesUncertain   int64
}

type ColumnAssetReachabilitySegmentEntry 

type ColumnAssetReachabilitySegmentEntry struct {
	Namespace        string
	FileID           uint32
	Path             string
	Bytes            int64
	Status           ColumnAssetReachabilitySegmentStatus
	ProtectedBytes   int64
	ReclaimableBytes int64
	UnknownBytes     int64
	RefCount         int
}

type ColumnAssetReachabilitySegmentStats 

type ColumnAssetReachabilitySegmentStats struct {
	Total                       int
	Protected                   int
	Reclaimable                 int
	Mixed                       int
	Unknown                     int
	Missing                     int
	OutOfBoundsRefs             int
	QuarantineSegments          int
	QuarantineSegmentMismatches int
	BytesTotal                  int64
	BytesProtected              int64
	BytesReclaimable            int64
	BytesWholeReclaimable       int64
	BytesUnknown                int64
	BytesQuarantined            int64
}

type ColumnAssetReachabilitySegmentStatus 

type ColumnAssetReachabilitySegmentStatus string
const (
	ColumnAssetReachabilitySegmentProtected   ColumnAssetReachabilitySegmentStatus = "protected"
	ColumnAssetReachabilitySegmentReclaimable ColumnAssetReachabilitySegmentStatus = "reclaimable"
	ColumnAssetReachabilitySegmentMixed       ColumnAssetReachabilitySegmentStatus = "mixed"
	ColumnAssetReachabilitySegmentUnknown     ColumnAssetReachabilitySegmentStatus = "unknown"
	ColumnAssetReachabilitySegmentMissing     ColumnAssetReachabilitySegmentStatus = "missing"
)

type ColumnAssetReachabilitySource 

type ColumnAssetReachabilitySource string
const (
	ColumnAssetReachabilitySourceActiveManifest    ColumnAssetReachabilitySource = "active_manifest"
	ColumnAssetReachabilitySourceRecoveryManifest  ColumnAssetReachabilitySource = "recovery_manifest"
	ColumnAssetReachabilitySourceCandidate         ColumnAssetReachabilitySource = "candidate"
	ColumnAssetReachabilitySourcePinnedSnapshot    ColumnAssetReachabilitySource = "pinned_snapshot"
	ColumnAssetReachabilitySourcePendingPublish    ColumnAssetReachabilitySource = "pending_publish"
	ColumnAssetReachabilitySourcePreparedAsset     ColumnAssetReachabilitySource = "prepared_asset"
	ColumnAssetReachabilitySourcePreparedQuery     ColumnAssetReachabilitySource = "prepared_query"
	ColumnAssetReachabilitySourceQuarantine        ColumnAssetReachabilitySource = "quarantine"
	ColumnAssetReachabilitySourceMappedResourcePin ColumnAssetReachabilitySource = "mappedresource_pin"
)

type ColumnAssetReachabilitySourceStats 

type ColumnAssetReachabilitySourceStats struct {
	ManifestRoots            int
	ManifestRecords          int
	ActiveManifestRefs       int
	RecoveryManifestRefs     int
	CandidateRefs            int
	PendingRefs              int
	PreparedRefs             int
	PreparedQueryRefs        int
	QuarantineRefs           int
	QuarantineSegmentRecords int
	PinnedRefs               int
	MappedResourcePins       int
	ActiveManifestBytes      int64
	RecoveryManifestBytes    int64
	CandidateBytes           int64
	PendingBytes             int64
	PreparedBytes            int64
	PreparedQueryBytes       int64
	QuarantineBytes          int64
	QuarantineSegmentBytes   int64
	PinnedBytes              int64
	MappedResourcePinBytes   int64
}

ColumnAssetReachabilitySourceStats counts unique ref contributions by logical reachability source. M15A only plans from an active recovery-authoritative manifest view, so active and recovery manifest refs are intentionally the same logical liveness set unless a future milestone introduces distinct roots.

type ColumnAssetReachabilityStatus 

type ColumnAssetReachabilityStatus string
const (
	ColumnAssetReachabilityProtected   ColumnAssetReachabilityStatus = "protected"
	ColumnAssetReachabilityReclaimable ColumnAssetReachabilityStatus = "reclaimable"
	ColumnAssetReachabilityUncertain   ColumnAssetReachabilityStatus = "uncertain"
)

type ColumnAssetReadIntegrity 

type ColumnAssetReadIntegrity string

ColumnAssetReadIntegrity controls hot physical column asset read validation. It does not change durability, manifest/header/schema validation, or the checksum fields written into typed column asset refs. 

const (
	ColumnAssetReadIntegrityVerify ColumnAssetReadIntegrity = "verify"
	// ColumnAssetReadIntegrityCachedVerify verifies each immutable typed asset
	// ref on first process read, then skips repeated hot-read CRC work for the
	// same ref. Explicit prepared read sessions may also reuse the file identity
	// captured when the segment reader was opened. It is a benchmark-relaxed mode:
	// post-verification file corruption can be missed until the cache entry is
	// evicted, the prepared session is closed, or the process restarts.
	ColumnAssetReadIntegrityCachedVerify ColumnAssetReadIntegrity = "cached_verify"
	// ColumnAssetReadIntegritySkipChecksums is an unsafe relaxed hot-read mode
	// for benchmark/performance attribution. It skips per-read payload checksum
	// verification and may skip redundant per-row tags after the asset header and
	// schema have been validated.
	ColumnAssetReadIntegritySkipChecksums ColumnAssetReadIntegrity = "skip_checksums"
)

type ColumnAssetRef 

type ColumnAssetRef struct {
	Kind       ColumnAssetKind
	Namespace  string
	Generation uint64
	PartID     uint64
	FileID     uint32
	Offset     int64
	Length     int64
	Checksum   uint32
}

ColumnAssetRef is the durable typed address of a column-asset-manager-owned object. It is value-log-shaped, but it must not imply ordinary value_vlog ownership.

type ColumnAssetRewriteOptions 

type ColumnAssetRewriteOptions struct {
	DryRun bool
	// Detailed keeps detailed ref and segment entries in the returned plan.
	Detailed           bool
	CandidateRefs      []ColumnAssetRef
	PendingRefs        []ColumnAssetRef
	PreparedRefs       []ColumnAssetRef
	PreparedQueryRefs  []ColumnAssetRef
	QuarantineRefs     []ColumnAssetRef
	QuarantineSegments []ColumnAssetQuarantineSegment
	PinnedRefs         []ColumnAssetRef
}

ColumnAssetRewriteOptions controls M15C mixed-segment rewrite/remap.

type ColumnAssetRewriteStats 

type ColumnAssetRewriteStats struct {
	DryRun bool

	Plan ColumnAssetReachabilityPlan

	SegmentsEligible  int
	SegmentsRewritten int
	SegmentsRetained  int
	RefsEligible      int
	RefsRemapped      int
	RefsRetained      int
	BytesEligible     int64
	// BytesCopied is committed copied bytes for destructive rewrites. Dry-run
	// reports the bytes that would be copied.
	BytesCopied      int64
	BytesReclaimable int64
	// BytesRetained is the pre-GC physical bytes in segments observed by the
	// reachability plan. Successful rewrite remaps protected refs, but the old
	// mixed segment remains on disk until ColumnAssetGC reclaims SupersededRefs.
	BytesRetained int64

	SupersededRefs     []ColumnAssetRef
	RemappedRefs       []ColumnAssetRef
	RemapManifestRoot  uint64
	RemapSystemRoot    uint64
	RemapSegmentFileID uint32
}

ColumnAssetRewriteStats summarizes mixed-segment rewrite/remap.

type ColumnBlockCacheKey 

type ColumnBlockCacheKey struct {
	Identity ColumnStoreCacheIdentity
	Kind     ColumnCacheEntryKind
	PartID   uint64
	Asset    ColumnAssetCacheIdentity
	Block    uint32
}

type ColumnCacheEntryKind 

type ColumnCacheEntryKind string
const (
	ColumnCacheEntryMarks        ColumnCacheEntryKind = "marks"
	ColumnCacheEntryDictionary   ColumnCacheEntryKind = "dictionary"
	ColumnCacheEntryDecodedBlock ColumnCacheEntryKind = "decoded-block"
)

type ColumnFixedWidthEncoding 

type ColumnFixedWidthEncoding string
const (
	// Empty means the current compatibility encoding: manifest-style big-endian
	// fixed-width element bytes inside the physical part image.
	ColumnFixedWidthEncodingDefault      ColumnFixedWidthEncoding = ""
	ColumnFixedWidthEncodingLittleEndian ColumnFixedWidthEncoding = "little_endian"
)

type ColumnLocatorConfig 

type ColumnLocatorConfig struct {
	Strategy ColumnLocatorStrategy `json:"strategy,omitempty"`
}

type ColumnLocatorStrategy 

type ColumnLocatorStrategy string
const (
	ColumnLocatorStrategySideIndex ColumnLocatorStrategy = "side-index"
	ColumnLocatorStrategyRoot      ColumnLocatorStrategy = "primary-id-row-root"
)

type ColumnManifestIdentity 

type ColumnManifestIdentity struct {
	Generation uint64 `json:"generation,omitempty"`
	Format     string `json:"format,omitempty"`
	Version    uint16 `json:"version,omitempty"`
	Checksum   uint64 `json:"checksum,omitempty"`
}

type ColumnManifestPartRole 

type ColumnManifestPartRole string
const (
	// ColumnManifestPartRoleBase identifies a complete base part in the typed-storage lineage.
	ColumnManifestPartRoleBase ColumnManifestPartRole = "base"
	// ColumnManifestPartRoleDelta identifies a mutation/append delta part layered over older bases/deltas.
	ColumnManifestPartRoleDelta ColumnManifestPartRole = "delta"
	// ColumnManifestPartRoleTombstone identifies a typed-row tombstone part with no typed-column payload.
	ColumnManifestPartRoleTombstone ColumnManifestPartRole = "tombstone"
)

type ColumnManifestPublishSystemDeltaInput 

type ColumnManifestPublishSystemDeltaInput struct {
	BaseMeta           CollectionMeta
	BaseCommitSeq      uint64
	BaseSystemRoot     uint64
	BaseManifestRootID uint64
	Plan               ColumnPublishPlan
}

ColumnManifestPublishSystemDeltaInput contains the collection metadata base and publish plan used to build the atomic system-root update.

type ColumnManifestRootDelta 

type ColumnManifestRootDelta struct {
	RootName       string
	BaseRootID     uint64
	StoragePolicy  RootStoragePolicy
	Identity       ColumnManifestIdentity
	IdentityRecord [columnManifestIdentityRecordSize]byte
	Records        []columnManifestRecord
}

ColumnManifestRootDelta is the ordered-root publish descriptor for the collection column manifest root.

func (ColumnManifestRootDelta) OrderedRootDeltaBatchPublishInput 

func (delta ColumnManifestRootDelta) OrderedRootDeltaBatchPublishInput() (backenddb.OrderedRootDeltaBatchPublishInput, func(), error)

func (ColumnManifestRootDelta) OrderedRootDeltaPublishInput 

func (delta ColumnManifestRootDelta) OrderedRootDeltaPublishInput() (backenddb.OrderedRootDeltaPublishInput, error)

func (ColumnManifestRootDelta) OrderedRootPublishInput 

func (delta ColumnManifestRootDelta) OrderedRootPublishInput() (backenddb.OrderedRootPublishInput, error)

OrderedRootPublishInput converts the root delta into a backend ordered-root publish input while preserving the already-validated identity record bytes.

type ColumnManifestRootDescriptor 

type ColumnManifestRootDescriptor struct {
	Name          string            `json:"name,omitempty"`
	StoragePolicy RootStoragePolicy `json:"storage_policy,omitempty"`
}

type ColumnPhysicalQueryDiagnostics 

type ColumnPhysicalQueryDiagnostics struct {
	ManifestRoot                          uint64
	ManifestRootName                      string
	ManifestGeneration                    uint64
	ActiveManifestChecksum                uint64
	RecoveryManifestGeneration            uint64
	RecoveryManifestChecksum              uint64
	AppliedCommandLSN                     uint64
	ManifestRecords                       int
	AssetRefs                             int
	MutationParts                         int
	DecodedBlocks                         int
	DirectReduceBlocks                    int
	TypedColumnPartSections               int
	TypedColumnPartSectionBytes           uint64
	MetadataHits                          int
	MetadataEntries                       int
	MetadataMisses                        int
	DictionaryCodeHits                    int
	PredicateDictionaryCodeHits           int
	Int64ValueHits                        int
	ScheduledGranules                     int
	SkippedGranules                       int
	DecodedGranules                       int
	RowsScanned                           int
	RowsMatched                           int
	DeletedRows                           int
	ProjectedColumns                      int
	PredicateCount                        int
	PredicateColumns                      []string
	PredicateKinds                        []string
	PredicateLiterals                     int
	SortKeyPrefixPlanned                  bool
	SortKeyPrefixColumns                  []string
	SortKeyPrefixLiterals                 int
	SortKeyMarkChecks                     int
	SortKeyMarkMatches                    int
	SortKeyMarkSkips                      int
	SortKeyMarkFallbackReason             string
	SortedGroupedDistinctReady            bool
	SortedGroupedDistinctUsed             bool
	SortedGroupedDistinctFallbackReason   string
	DenseGroupCountUsed                   bool
	DenseGroupCountDistinctUsed           bool
	DenseGroupCountDistinctReducer        string
	DenseGroupCountDistinctGroups         int
	DenseGroupCountDistinctValues         int
	DenseGroupCountDistinctPairBitWords   int
	DenseGroupHourCountUsed               bool
	DenseInt64SpanUsed                    bool
	DenseInt64SpanReducer                 string
	DenseInt64SpanPredicateBlocksSkipped  int
	TimeOrderTopKUsed                     bool
	DecodedPayloadBytes                   uint64
	FallbackReads                         int
	RowMaterializations                   int
	DocumentMaterializations              int
	PhysicalBytesScanned                  int64
	DecodedMetadataBytes                  uint64
	MappedBytes                           uint64
	HeapCopyBytes                         uint64
	ReduceRows                            int
	TopKLimit                             int
	TopKCandidates                        int
	TopKOrder                             string
	VisibilityRows                        int
	ReconstructionRows                    int
	ResultGroups                          int
	WorkerCount                           int
	SegmentFileCacheHits                  uint64
	SegmentFileCacheMisses                uint64
	TypedColumnOneShotCacheHit            bool
	TypedColumnOneShotCacheMiss           bool
	TypedColumnOneShotCacheBuild          bool
	TypedColumnOneShotBuildNanos          int64
	TypedColumnPrepareWorkerCount         int
	TypedColumnPreparePlanNanos           int64
	TypedColumnPrepareRefsNanos           int64
	TypedColumnPreparePairingNanos        int64
	TypedColumnPreparePartDecodeNanos     int64
	TypedColumnPreparePostPrepareNanos    int64
	TypedColumnPrepareSummaryNanos        int64
	TypedColumnOneShotCacheStoreNanos     int64
	TypedColumnPrepareReadImageNanos      int64
	TypedColumnPrepareStateBuildNanos     int64
	TypedColumnPrepareDictionaryNanos     int64
	TypedColumnPreparePruningNanos        int64
	TypedColumnPrepareSortKeyNanos        int64
	TypedColumnPrepareStatsNanos          int64
	TypedColumnPrepareRangeReadNanos      int64
	TypedColumnPrepareRangeReadBytes      int64
	TypedColumnPrepareAdapterNanos        int64
	TypedColumnPrepareDenseGroupNanos     int64
	TypedColumnPrepareDenseValueNanos     int64
	TypedColumnPrepareDensePredicateNanos int64
	TypedColumnPrepareDensePreapplyNanos  int64

	TypedColumnPrepareQ2GroupRankNanos                    int64
	TypedColumnPrepareQ2DistinctRankNanos                 int64
	TypedColumnPrepareQ2LocalRankNanos                    int64
	TypedColumnPrepareQ2DenseGroupGlobalRankNanos         int64
	TypedColumnPrepareQ2DenseDistinctGlobalRankNanos      int64
	TypedColumnPrepareQ2DensePartLocalRankNanos           int64
	TypedColumnPrepareQ2DenseDistinctRankPlanNanos        int64
	TypedColumnPrepareQ2DenseDistinctRankCollectRefsNanos int64
	TypedColumnPrepareQ2DenseDistinctRankBuildShardsNanos int64
	TypedColumnPrepareQ2DenseDistinctRankShardCount       int
	TypedColumnPrepareQ2DenseDistinctRankRefs             int
	TypedColumnPrepareQ2DenseDistinctRankMaxShardRefs     int
	TypedColumnPrepareQ2DenseDistinctGlobalRanks          int

	TypedColumnPrepareQ2GroupGlobalDictionaryRankNanos    int64
	TypedColumnPrepareQ2DistinctGlobalDictionaryRankNanos int64
	TypedColumnPrepareQ2GroupGlobalCodeRemapNanos         int64
	TypedColumnPrepareQ2DistinctGlobalCodeRemapNanos      int64

	ColumnAssetReadIntegrity string
	StorageSource            ColumnPhysicalQueryStorageSource
	FallbackReason           ColumnPhysicalQueryFallbackReason
	ScanNanos                int64
	VisibilityNanos          int64
	ReduceNanos              int64
	ResultShapeNanos         int64
	ReconstructionNanos      int64
}

ColumnPhysicalQueryDiagnostics reports scan and reduce work for a physical query without counting full-document row materialization.

type ColumnPhysicalQueryFallbackReason 

type ColumnPhysicalQueryFallbackReason string

ColumnPhysicalQueryFallbackReason explains why a benchmark/report row did not use its most direct physical source. The "none" value is intentionally explicit so baseline tables can carry a value for every row. 

const (
	ColumnPhysicalQueryFallbackNone                          ColumnPhysicalQueryFallbackReason = "none"
	ColumnPhysicalQueryFallbackDirectAssetReduceUnsupported  ColumnPhysicalQueryFallbackReason = "direct_asset_reduce_unsupported"
	ColumnPhysicalQueryFallbackAggregateMetadataUnsupported  ColumnPhysicalQueryFallbackReason = "aggregate_metadata_unsupported"
	ColumnPhysicalQueryFallbackMutationVisibilityOverlay     ColumnPhysicalQueryFallbackReason = "mutation_visibility_overlay"
	ColumnPhysicalQueryFallbackMutationVisibilityUnsupported ColumnPhysicalQueryFallbackReason = "mutation_visibility_unsupported"
	ColumnPhysicalQueryFallbackDocumentRootRowScan           ColumnPhysicalQueryFallbackReason = "document_root_row_scan"
	ColumnPhysicalQueryFallbackMixed                         ColumnPhysicalQueryFallbackReason = "mixed"
)

type ColumnPhysicalQueryGroup 

type ColumnPhysicalQueryGroup struct {
	Key           string
	Hour          int
	Count         int
	DistinctCount int
	Int64         int64
}

ColumnPhysicalQueryGroup is one reduced result row. Key is the group key. Count is populated for count-style queries and remains the distinct count for group_count_distinct. Hour is populated by group_hour_count. DistinctCount is populated by group_count_and_distinct; Int64 is populated for min/max/span/sum expression queries.

type ColumnPhysicalQueryKind 

type ColumnPhysicalQueryKind string

ColumnPhysicalQueryKind names the small M13B physical aggregate/projection shapes supported directly by the column asset scanner. 

const (
	// ColumnPhysicalQueryGroupCount counts rows by a string group column.
	ColumnPhysicalQueryGroupCount            ColumnPhysicalQueryKind = "group_count"
	ColumnPhysicalQueryGroupCountDistinct    ColumnPhysicalQueryKind = "group_count_distinct"
	ColumnPhysicalQueryGroupCountAndDistinct ColumnPhysicalQueryKind = "group_count_and_distinct"
	ColumnPhysicalQueryHourCount             ColumnPhysicalQueryKind = "hour_count"
	ColumnPhysicalQueryGroupHourCount        ColumnPhysicalQueryKind = "group_hour_count"
	ColumnPhysicalQueryGroupMinInt64         ColumnPhysicalQueryKind = "group_min_int64"
	ColumnPhysicalQueryGroupMaxInt64         ColumnPhysicalQueryKind = "group_max_int64"
	ColumnPhysicalQueryGroupInt64Span        ColumnPhysicalQueryKind = "group_int64_span"
	ColumnPhysicalQuerySumSecondOfDaySquare  ColumnPhysicalQueryKind = "sum_second_of_day_square"
)

type ColumnPhysicalQueryPredicate 

type ColumnPhysicalQueryPredicate struct {
	Column string                           `json:"column"`
	Kind   ColumnPhysicalQueryPredicateKind `json:"kind,omitempty"`
	Value  string                           `json:"value"`
	Values []string                         `json:"values,omitempty"`
}

ColumnPhysicalQueryPredicate describes one dictionary string predicate. Equal uses Value, including the empty string as a valid literal. In-list uses Values so callers can distinguish an empty-string member from a missing literal. Predicates are combined with AND.

type ColumnPhysicalQueryPredicateKind 

type ColumnPhysicalQueryPredicateKind string

ColumnPhysicalQueryPredicateKind names the narrow predicate shapes supported by explicit physical column queries. The first implementation intentionally supports only dictionary string equality and small IN lists. 

const (
	ColumnPhysicalQueryPredicateEqual  ColumnPhysicalQueryPredicateKind = "equal"
	ColumnPhysicalQueryPredicateInList ColumnPhysicalQueryPredicateKind = "in_list"
)

type ColumnPhysicalQueryRequest 

type ColumnPhysicalQueryRequest struct {
	Kind                     ColumnPhysicalQueryKind
	GroupColumn              string
	ValueColumn              string
	DistinctColumn           string
	AggregateMetadataName    string
	TopK                     int
	TopKOrder                ColumnPhysicalQueryTopKOrder
	SkipEmptyGroupKey        bool
	Predicates               []ColumnPhysicalQueryPredicate
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

ColumnPhysicalQueryRequest describes one explicit physical column query. It does not invoke planner routing; M14 owns forced/automatic route selection. Predicates are an AND-list of dictionary string equality/IN filters for the insert-only physical sidecar path; unsupported predicate shapes fail closed. TopK is optional for int64 aggregate reducers. When TopK is set, TopKOrder chooses value order and Key is the tie-break; SkipEmptyGroupKey omits empty-string group keys before applying the limit.

type ColumnPhysicalQueryResult 

type ColumnPhysicalQueryResult struct {
	Groups      []ColumnPhysicalQueryGroup
	Diagnostics ColumnPhysicalQueryDiagnostics
}

ColumnPhysicalQueryResult is the reduced result and diagnostics from an explicit physical column query.

type ColumnPhysicalQueryRunner 

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

ColumnPhysicalQueryRunner pins one immutable snapshot and reuses direct-query execution state across repeated scans. It is intentionally limited to insert-only direct physical reducers; mutation visibility and planner routing remain owned by RunColumnPhysicalQuery.

The runner is not safe for concurrent use; callers must externally synchronize Run and Close. Result groups returned by Run alias runner-owned storage and are valid only until the next Run or Close.

func (*ColumnPhysicalQueryRunner) Close 

func (r *ColumnPhysicalQueryRunner) Close() error

Close releases the pinned snapshot, lifecycle pin set, and typed column asset readers owned by the prepared physical query runner.

func (*ColumnPhysicalQueryRunner) PrepareDiagnostics 

func (r *ColumnPhysicalQueryRunner) PrepareDiagnostics() ColumnPhysicalQueryDiagnostics

PrepareDiagnostics reports setup work captured while constructing this prepared runner. It is intentionally sparse for runner types without instrumented setup subphases.

func (*ColumnPhysicalQueryRunner) Run 

func (r *ColumnPhysicalQueryRunner) Run() (ColumnPhysicalQueryResult, error)

Run executes the prepared direct physical query against the pinned snapshot. The returned Groups slice aliases runner-owned storage to keep hot loops allocation-free; copy Groups before calling Run again or Close if the result must be retained.

type ColumnPhysicalQueryStorageSource 

type ColumnPhysicalQueryStorageSource string

ColumnPhysicalQueryStorageSource names the physical storage family that satisfied a query/report row. It is diagnostic vocabulary for JSONBench baselines and must not be used as a route selector. 

const (
	ColumnPhysicalQueryStorageSourceRowScan                               ColumnPhysicalQueryStorageSource = "row_scan"
	ColumnPhysicalQueryStorageSourceTypedRowAsset                         ColumnPhysicalQueryStorageSource = "typed_row_asset"
	ColumnPhysicalQueryStorageSourceCompatibilityDictionaryCodeInt64Asset ColumnPhysicalQueryStorageSource = "compatibility_dictionary_code_int64_asset"
	ColumnPhysicalQueryStorageSourceTypedColumnPartSection                ColumnPhysicalQueryStorageSource = "typed_column_part_section"
	ColumnPhysicalQueryStorageSourceAggregateMetadata                     ColumnPhysicalQueryStorageSource = "aggregate_metadata"
	ColumnPhysicalQueryStorageSourceFallback                              ColumnPhysicalQueryStorageSource = "fallback"
	ColumnPhysicalQueryStorageSourceMixed                                 ColumnPhysicalQueryStorageSource = "mixed"
)

type ColumnPhysicalQueryTopKOrder 

type ColumnPhysicalQueryTopKOrder string

ColumnPhysicalQueryTopKOrder selects ordering for optional Top-K int64 physical query result shaping. 

const (
	// ColumnPhysicalQueryTopKInt64Asc keeps the smallest Int64 groups first,
	// using Key as the deterministic tie-break.
	ColumnPhysicalQueryTopKInt64Asc ColumnPhysicalQueryTopKOrder = "int64_asc"
	// ColumnPhysicalQueryTopKInt64Desc keeps the largest Int64 groups first,
	// using Key as the deterministic tie-break.
	ColumnPhysicalQueryTopKInt64Desc ColumnPhysicalQueryTopKOrder = "int64_desc"
)

type ColumnPreparedAsset 

type ColumnPreparedAsset struct {
	Ref          ColumnAssetRef
	Rows         int
	Bytes        int64
	PublishID    uint64
	GenerationID uint64
	Reason       string
	PartRole     ColumnManifestPartRole
	SortKey      string
}

ColumnPreparedAsset describes an immutable asset staged for manifest publish.

type ColumnPublishAssetPreparationMetrics 

type ColumnPublishAssetPreparationMetrics struct {
	RowAssetDuration                      time.Duration
	RowAssetBytes                         int64
	RowAssetCount                         int
	TypedColumnPartDuration               time.Duration
	TypedColumnDictionaryBuild            time.Duration
	TypedColumnRowMaterialization         time.Duration
	TypedColumnPartBuild                  time.Duration
	TypedColumnImageBuild                 time.Duration
	TypedColumnPartBytes                  int64
	TypedColumnPartCount                  int
	DictionarySidecarDuration             time.Duration
	DictionarySidecarBytes                int64
	DictionarySidecarCount                int
	Int64SidecarDuration                  time.Duration
	Int64SidecarBytes                     int64
	Int64SidecarCount                     int
	AggregateMetadataDuration             time.Duration
	AggregateMetadataBytes                int64
	AggregateMetadataCount                int
	RowSidecarSharedBuildDuration         time.Duration
	SharedAppendOpenDuration              time.Duration
	SharedAppendWriteDuration             time.Duration
	SharedAppendCloseDuration             time.Duration
	SharedAppendFileSyncDuration          time.Duration
	SharedAppendFileCloseDuration         time.Duration
	SharedAppendDirSyncDuration           time.Duration
	SharedAppendCleanupDuration           time.Duration
	SharedAppendCloseCount                int
	SharedAppendFileSyncCount             int
	SharedAppendSyncEpochCount            int
	SharedAppendDuration                  time.Duration
	SharedAppendBytes                     int64
	SharedAppendCount                     int
	SharedSegmentAppendBytes              int64
	SharedSegmentAppendCount              int
	SharedSegmentAppendCloseCount         int
	SharedSegmentAppendFileSyncCount      int
	SharedSegmentAppendSyncEpochCount     int
	DirectViewSegmentAppendBytes          int64
	DirectViewSegmentAppendCount          int
	DirectViewSegmentAppendCloseCount     int
	DirectViewSegmentAppendFileSyncCount  int
	DirectViewSegmentAppendSyncEpochCount int
}

ColumnPublishAssetPreparationMetrics breaks the production asset-preparation stage down by the asset families that make up column-store insert/load cost. Subphase durations are producer-attributed and may overlap; AssetPreparation remains the enclosing wall-clock duration for the full prepare stage. Fused row-sidecar build time is byte-attributed to dictionary/int64/aggregate families by the producer; SharedAppendDuration remains separately reported so callers can choose exact upper-bound or byte-share accounting.

type ColumnPublishAssetPrepareInput 

type ColumnPublishAssetPrepareInput struct {
	Collection        string
	ColumnStore       ColumnStoreConfig
	Operation         ColumnPublishOperation
	AppliedCommandLSN uint64
	CurrentManifest   *ColumnManifestIdentity
}

ColumnPublishAssetPrepareInput is passed to the asset preparation stage.

type ColumnPublishClosureValidationInput 

type ColumnPublishClosureValidationInput struct {
	Collection        string
	ColumnStore       ColumnStoreConfig
	Operation         ColumnPublishOperation
	AppliedCommandLSN uint64
	Prepared          ColumnPublishPreparedAssets
	Manifest          ColumnPublishManifestEncodeResult
}

ColumnPublishClosureValidationInput is passed to the durability-closure validation stage.

type ColumnPublishDeclaredColumnEncodeInput 

type ColumnPublishDeclaredColumnEncodeInput struct {
	Collection  string
	ColumnStore ColumnStoreConfig
	Operation   ColumnPublishOperation
}

ColumnPublishDeclaredColumnEncodeInput is passed to the declared-column encoding stage.

type ColumnPublishDurabilityClosure 

type ColumnPublishDurabilityClosure struct {
	// PreparedAssets is owned by the closure/plan boundary. BuildColumnPublishPlan
	// compares it as an order-independent multiset against the manifest snapshot
	// before publishing.
	PreparedAssets []ColumnPreparedAsset
	RequiredAssets int
	RequiredBytes  int64
	FlushRequired  bool
	SyncRequired   bool
}

ColumnPublishDurabilityClosure records the assets that must be flushed and synced before the manifest root can become authoritative.

type ColumnPublishLifecycleSummary 

type ColumnPublishLifecycleSummary struct {
	PublishedRefs         int
	PublishedBytes        int64
	PreparedRefs          int
	PreparedBytes         int64
	SupersededRefs        int
	SupersededBytes       int64
	CleanupSafeGeneration uint64
	CleanupSafeRefs       int
	CleanupSafeBytes      int64
	RewriteDebtBytes      int64
}

ColumnPublishLifecycleSummary summarizes lifecycle/GC-relevant asset effects of the publish.

type ColumnPublishManifestEncodeInput 

type ColumnPublishManifestEncodeInput struct {
	Collection               string
	ColumnStore              ColumnStoreConfig
	ActiveVectorIndexes      []VectorIndexDefinition
	ActiveVectorIndexesKnown bool
	Operation                ColumnPublishOperation
	AppliedCommandLSN        uint64
	CurrentManifest          *ColumnManifestIdentity
	CurrentManifestRecords   []columnManifestRecord
	Prepared                 ColumnPublishPreparedAssets
}

ColumnPublishManifestEncodeInput is passed to the manifest encoding stage.

type ColumnPublishManifestEncodeResult 

type ColumnPublishManifestEncodeResult struct {
	Identity      ColumnManifestIdentity
	ManifestBytes int64
	Records       []columnManifestRecord
}

ColumnPublishManifestEncodeResult identifies the encoded manifest generation.

type ColumnPublishOperation 

type ColumnPublishOperation string
const (
	// ColumnPublishOperationInsert publishes column assets for inserted rows.
	ColumnPublishOperationInsert ColumnPublishOperation = "insert"
	// ColumnPublishOperationUpdate publishes column assets for updated rows.
	ColumnPublishOperationUpdate ColumnPublishOperation = "update"
	// ColumnPublishOperationDelete publishes column tombstone/delete metadata.
	ColumnPublishOperationDelete ColumnPublishOperation = "delete"
)

type ColumnPublishPlan 

type ColumnPublishPlan struct {
	Enabled                                bool
	Collection                             string
	Operation                              ColumnPublishOperation
	AppliedCommandLSN                      uint64
	ManifestRootName                       string
	ManifestRootBaseID                     uint64
	UpdatedActiveManifest                  ColumnManifestIdentity
	RecoveryAuthoritativeManifest          ColumnManifestIdentity
	RecoveryAuthoritativeAppliedCommandLSN uint64
	RootDelta                              ColumnManifestRootDelta
	PreparedAssets                         []ColumnPreparedAsset
	RequiredAssetCount                     int
	RequiredAssetBytes                     int64
	RequiredAssetFlush                     bool
	RequiredAssetSync                      bool
	Rows                                   int
	CommandBytes                           int64
	RowRemainderBytes                      int64
	ColumnPayloadBytes                     int64
	ManifestBytes                          int64
	Lifecycle                              ColumnPublishLifecycleSummary
	StageMetrics                           ColumnPublishStageMetrics
}

ColumnPublishPlan is the complete, validated plan for publishing a column manifest generation and making it recovery-authoritative.

func BuildColumnPublishPlan 

func BuildColumnPublishPlan(input ColumnPublishPlanInput) (ColumnPublishPlan, error)

BuildColumnPublishPlan validates and stages an atomic column manifest publish plan. A nil or completely empty disabled column_store is a zero-work fast path.

type ColumnPublishPlanHooks 

type ColumnPublishPlanHooks struct {
	ExtractDocuments      func() error
	EncodeDeclaredColumns func(ColumnPublishDeclaredColumnEncodeInput) error
	PrepareAssets         func(ColumnPublishAssetPrepareInput) (ColumnPublishPreparedAssets, error)
	EncodeManifest        func(ColumnPublishManifestEncodeInput) (ColumnPublishManifestEncodeResult, error)
	ValidateClosure       func(ColumnPublishClosureValidationInput) (ColumnPublishDurabilityClosure, error)
	BuildRootDelta        func(ColumnPublishRootDeltaInput) (ColumnManifestRootDelta, error)
	BuildSystemDelta      func(ColumnPublishSystemDeltaInput) error
}

ColumnPublishPlanHooks provide the engine-specific stages for a publish plan.

type ColumnPublishPlanInput 

type ColumnPublishPlanInput struct {
	Collection               string
	ColumnStore              *ColumnStoreConfig
	ColumnStoreNormalized    bool
	ActiveVectorIndexes      []VectorIndexDefinition
	ActiveVectorIndexesKnown bool
	Operation                ColumnPublishOperation
	CurrentManifest          *ColumnManifestIdentity
	CurrentManifestRecords   []columnManifestRecord
	AppliedCommandLSN        uint64
	BaseManifestRootID       uint64
	Hooks                    ColumnPublishPlanHooks
}

ColumnPublishPlanInput contains the normalized collection state and stage hooks required to build an atomic column manifest publish plan.

type ColumnPublishPreparedAssets 

type ColumnPublishPreparedAssets struct {
	Assets             []ColumnPreparedAsset
	RowCount           int
	CommandBytes       int64
	RowRemainderBytes  int64
	ColumnPayloadBytes int64
	AssetMetrics       ColumnPublishAssetPreparationMetrics
}

ColumnPublishPreparedAssets is the row/byte/accounting summary for staged column assets before they are referenced by a manifest generation.

type ColumnPublishRootDeltaInput 

type ColumnPublishRootDeltaInput struct {
	Collection         string
	ColumnStore        ColumnStoreConfig
	BaseManifestRootID uint64
	Manifest           ColumnPublishManifestEncodeResult
	Closure            ColumnPublishDurabilityClosure
}

ColumnPublishRootDeltaInput is passed to the manifest-root delta stage.

type ColumnPublishStageMetrics 

type ColumnPublishStageMetrics struct {
	// DocumentExtraction also includes the production command-WAL JSON-to-
	// declared-row conversion when that path prepares declared rows before
	// BuildColumnPublishPlan. Typed-column asset encoding remains charged to
	// AssetPreparation unless an explicit EncodeDeclaredColumns hook runs.
	DocumentExtraction      time.Duration
	DeclaredColumnEncoding  time.Duration
	AssetPreparation        time.Duration
	AssetMetrics            ColumnPublishAssetPreparationMetrics
	AssetClosureValidation  time.Duration
	ManifestEncode          time.Duration
	RootDeltaConstruction   time.Duration
	SystemDeltaConstruction time.Duration
}

ColumnPublishStageMetrics records stage timings and optional allocation counters for publish-plan construction.

type ColumnPublishSystemDeltaInput 

type ColumnPublishSystemDeltaInput struct {
	Plan ColumnPublishPlan
}

ColumnPublishSystemDeltaInput is passed to the metadata/system-root stage.

type ColumnQueryPlan 

type ColumnQueryPlan struct {
	Kind        ColumnQueryPlanKind
	Supported   bool
	IndexName   string
	IndexField  string
	Diagnostics ColumnQueryPlanDiagnostics
}

type ColumnQueryPlanDiagnostics 

type ColumnQueryPlanDiagnostics struct {
	Reason                 string
	CandidatePlans         int
	ProjectedColumns       int
	Predicates             int
	RecoveryAuthoritative  bool
	CapabilityError        string
	PhysicalAssetCount     int
	PartCount              int
	GranuleCount           int
	MutationParts          int
	DeclaredColumnCount    int
	AggregateMetadataCount int
	VisibilityMetadata     bool
	ParallelWorkUnits      int
	MaxParallelWorkers     int
	WorkerCount            int
	ScheduledGranules      int
	SkippedGranules        int
	SegmentFileCacheHits   uint64
	SegmentFileCacheMisses uint64
	SelectedIndexName      string
	SelectedIndexField     string
	SelectedManifestRoot   uint64
	SelectedManifestGen    uint64
	RecoveryManifestGen    uint64
	AppliedCommandLSN      uint64
	UnsupportedPlanKind    ColumnQueryPlanKind
	UnsupportedPlanReason  string
}

type ColumnQueryPlanKind 

type ColumnQueryPlanKind string
const (
	ColumnQueryPlanRowStoreBaseline   ColumnQueryPlanKind = "row_store_baseline"
	ColumnQueryPlanBTreeIndexBaseline ColumnQueryPlanKind = "b_tree_index_baseline"
	ColumnQueryPlanSerialColumnScan   ColumnQueryPlanKind = "serial_column_scan"
	ColumnQueryPlanAggregateMetadata  ColumnQueryPlanKind = "aggregate_metadata"
	ColumnQueryPlanParallelColumnScan ColumnQueryPlanKind = "parallel_column_scan"
)

type ColumnQueryPlanRequest 

type ColumnQueryPlanRequest struct {
	Name                  string
	ProjectedColumns      []string
	Predicates            []ColumnQueryPredicate
	CandidateIndexColumns []string
	AggregateMetadataName string
	EstimatedRows         int
	ForceKind             ColumnQueryPlanKind
	Capabilities          ColumnQueryPlannerCapabilities
}

ColumnQueryPlanRequest describes one planner decision. Column, index, and aggregate metadata names are matched case-sensitively after trimming surrounding whitespace; callers should canonicalize catalog names before storing them rather than relying on planner-time normalization. Physical column plans also require every non-empty ProjectedColumns and predicate column entry to be declared in the collection's ColumnStore config; row/B-tree baselines read source documents and do not enforce that projection gate.

type ColumnQueryPlannerCapabilities 

type ColumnQueryPlannerCapabilities struct {
	SerialColumnScan   bool
	AggregateMetadata  bool
	ParallelColumnScan bool
	// CapabilityError mirrors an internally derived physical capability
	// discovery failure for diagnostics. Caller-supplied values are ignored for
	// gating so public requests cannot forge a planner fail-closed reason.
	CapabilityError string

	PhysicalAssetCount int
	// PartCount is a fallback schedulable-unit estimate when GranuleCount is
	// not populated by the column asset layer.
	PartCount int
	// GranuleCount is the authoritative schedulable-unit count for parallel
	// planning when the column asset layer exposes adaptive marks/granules.
	GranuleCount           int
	MaxParallelWorkers     int
	SegmentFileCacheHits   uint64
	SegmentFileCacheMisses uint64
	PlannerCandidateBudget int
	// M14A manifest-derived diagnostics. These do not enable execution by
	// themselves; M14B owns routing physical plans to physical scanners.
	MutationParts          int
	DeclaredColumnCount    int
	AggregateMetadataCount int
	VisibilityMetadata     bool
	ParallelWorkUnits      int
	// contains filtered or unexported fields
}

type ColumnQueryPredicate 

type ColumnQueryPredicate struct {
	Column string
	// Operator participates in planner candidate ordering: equality and
	// unspecified predicates are preferred before range predicates for index
	// baselines. Unknown operators are ignored rather than driving B-tree
	// baseline selection; physical predicate pushdown is a later column-store
	// milestone.
	Operator ColumnQueryPredicateOperator
}

type ColumnQueryPredicateOperator 

type ColumnQueryPredicateOperator string
const (
	ColumnQueryPredicateEqual          ColumnQueryPredicateOperator = "="
	ColumnQueryPredicateGreaterOrEqual ColumnQueryPredicateOperator = ">="
	ColumnQueryPredicateGreaterThan    ColumnQueryPredicateOperator = ">"
	ColumnQueryPredicateLessOrEqual    ColumnQueryPredicateOperator = "<="
	ColumnQueryPredicateLessThan       ColumnQueryPredicateOperator = "<"
)

type ColumnReconstructionPolicy 

type ColumnReconstructionPolicy string
const (
	ColumnReconstructionRetainedPayloadAndColumns ColumnReconstructionPolicy = "retained-payload-and-columns"
)

type ColumnRetainedPayloadCollectionAuditOptions 

type ColumnRetainedPayloadCollectionAuditOptions struct {
	Paths                   []string
	MaxDocuments            int
	IncludeShapeStats       bool
	ShapeMaxDepth           int
	ShapeMaxPaths           int
	IncludeValueFamilyStats bool
	ValueFamilyMaxDepth     int
	ValueFamilyMaxPaths     int
	ValueFamilyMaxUnique    int
	IncludeSemanticStreams  bool
	SemanticStreamMaxDepth  int
	SemanticStreamMaxPaths  int
	// IncludeSemanticStreamBlockLayout parses semantic-stream-v1 side-root
	// blocks directly. It is only valid for semantic-stream-v1 collections.
	IncludeSemanticStreamBlockLayout bool
	SemanticStreamBlockMaxPaths      int
}

ColumnRetainedPayloadCollectionAuditOptions controls the retained-payload path audit over the collection's persisted primary rows.

type ColumnRetainedPayloadCollectionAuditResult 

type ColumnRetainedPayloadCollectionAuditResult struct {
	Collection                               string                                          `json:"collection"`
	Status                                   string                                          `json:"status"`
	RetainedPayloadPolicy                    ColumnRetainedPayloadPolicy                     `json:"retained_payload_policy"`
	RetainedPayloadEncoding                  string                                          `json:"retained_payload_encoding"`
	RetainedPayloadEncodingStatus            string                                          `json:"retained_payload_encoding_status"`
	RetainedPayloadCompression               string                                          `json:"retained_payload_compression"`
	RetainedPayloadCompressionPolicy         string                                          `json:"retained_payload_compression_policy"`
	RetainedPayloadCompressionStatus         string                                          `json:"retained_payload_compression_status"`
	DeclaredPaths                            []string                                        `json:"declared_paths"`
	CheckedRows                              int                                             `json:"checked_rows"`
	RetainedPayloadBytes                     int64                                           `json:"retained_payload_bytes"`
	RetainedPayloadShape                     []ColumnRetainedPayloadShapePathStat            `json:"retained_payload_shape,omitempty"`
	RetainedPayloadShapeTruncated            bool                                            `json:"retained_payload_shape_truncated,omitempty"`
	RetainedPayloadValueFamilies             []ColumnRetainedPayloadValueFamilyStat          `json:"retained_payload_value_families,omitempty"`
	RetainedPayloadValueFamiliesTruncated    bool                                            `json:"retained_payload_value_families_truncated,omitempty"`
	RetainedPayloadSemanticStreams           []ColumnRetainedPayloadSemanticStreamStat       `json:"retained_payload_semantic_streams,omitempty"`
	RetainedPayloadSemanticStreamsTruncated  bool                                            `json:"retained_payload_semantic_streams_truncated,omitempty"`
	RetainedPayloadSemanticStreamInputBytes  int64                                           `json:"retained_payload_semantic_stream_input_bytes,omitempty"`
	RetainedPayloadSemanticStreamZSTDBytes   int64                                           `json:"retained_payload_semantic_stream_zstd_bytes,omitempty"`
	RetainedPayloadSemanticStreamBlockLayout *ColumnRetainedSemanticStreamV1BlockLayoutAudit `json:"retained_payload_semantic_stream_block_layout,omitempty"`
	Truncated                                bool                                            `json:"truncated,omitempty"`
	Violations                               []ColumnRetainedPayloadCollectionPathViolation  `json:"violations,omitempty"`
	Errors                                   []string                                        `json:"errors,omitempty"`
}

type ColumnRetainedPayloadCollectionPathViolation 

type ColumnRetainedPayloadCollectionPathViolation struct {
	DocumentID string `json:"document_id"`
	Path       string `json:"path"`
}

type ColumnRetainedPayloadEncoding 

type ColumnRetainedPayloadEncoding string

type ColumnRetainedPayloadLengthBucket 

type ColumnRetainedPayloadLengthBucket struct {
	Bucket string `json:"bucket"`
	Count  int64  `json:"count"`
}

type ColumnRetainedPayloadPath 

type ColumnRetainedPayloadPath struct {
	Path    string `json:"path"`
	Present bool   `json:"present"`
}

type ColumnRetainedPayloadPathAudit 

type ColumnRetainedPayloadPathAudit struct {
	RetainedPayloadPolicy         ColumnRetainedPayloadPolicy `json:"retained_payload_policy"`
	RetainedPayloadEncoding       string                      `json:"retained_payload_encoding"`
	RetainedPayloadEncodingStatus string                      `json:"retained_payload_encoding_status"`
	RetainedPayloadBytes          int                         `json:"retained_payload_bytes"`
	Paths                         []ColumnRetainedPayloadPath `json:"paths"`
	Violations                    []string                    `json:"violations,omitempty"`
}

func AuditColumnRetainedPayloadPathsAbsent 

func AuditColumnRetainedPayloadPathsAbsent(cfg ColumnStoreConfig, retained []byte, paths []string) (ColumnRetainedPayloadPathAudit, error)

AuditColumnRetainedPayloadPathsAbsent verifies that declared typed JSON paths are absent from a retained payload body. It fails closed on malformed retained payloads and on any declared path that remains present.

type ColumnRetainedPayloadPolicy 

type ColumnRetainedPayloadPolicy string

type ColumnRetainedPayloadSemanticStreamStat 

type ColumnRetainedPayloadSemanticStreamStat struct {
	Path             string  `json:"path"`
	ValueKind        string  `json:"value_kind"`
	Occurrences      int64   `json:"occurrences"`
	Documents        int64   `json:"documents"`
	JSONBytes        int64   `json:"json_bytes"`
	StringBytes      int64   `json:"string_bytes,omitempty"`
	StreamInputBytes int64   `json:"stream_input_bytes"`
	MinStreamBytes   int     `json:"min_stream_bytes"`
	MaxStreamBytes   int     `json:"max_stream_bytes"`
	ZSTDBytes        int64   `json:"zstd_bytes,omitempty"`
	ZSTDToInputRatio float64 `json:"zstd_to_input_ratio,omitempty"`
}

ColumnRetainedPayloadSemanticStreamStat estimates the scalar stream bytes a ClickHouse-like semantic retained payload layout would need by path and kind. It is an oracle over decoded values, not a claim about the current on-disk format: object shape/presence metadata and reconstruction layout are separate format choices.

type ColumnRetainedPayloadShapePathStat 

type ColumnRetainedPayloadShapePathStat struct {
	Path         string `json:"path"`
	ValueKind    string `json:"value_kind"`
	Occurrences  int64  `json:"occurrences"`
	Documents    int64  `json:"documents"`
	JSONBytes    int64  `json:"json_bytes"`
	StringBytes  int64  `json:"string_bytes,omitempty"`
	MaxJSONBytes int    `json:"max_json_bytes,omitempty"`
}

ColumnRetainedPayloadShapePathStat summarizes decoded retained-payload JSON values by path and kind. JSONBytes is per-path encoded value size and is not additive across parent and child paths.

type ColumnRetainedPayloadValueFamilyStat 

type ColumnRetainedPayloadValueFamilyStat struct {
	Path                  string                              `json:"path"`
	Occurrences           int64                               `json:"occurrences"`
	Documents             int64                               `json:"documents"`
	JSONBytes             int64                               `json:"json_bytes"`
	StringBytes           int64                               `json:"string_bytes"`
	OracleInputBytes      int64                               `json:"oracle_input_bytes"`
	MinLength             int                                 `json:"min_length"`
	MaxLength             int                                 `json:"max_length"`
	MeanLength            float64                             `json:"mean_length"`
	TrackedUniqueValues   int64                               `json:"tracked_unique_values"`
	UniqueValuesTruncated bool                                `json:"unique_values_truncated,omitempty"`
	RepeatedValues        int64                               `json:"repeated_values,omitempty"`
	CommonPrefix          string                              `json:"common_prefix,omitempty"`
	CommonPrefixBytes     int                                 `json:"common_prefix_bytes,omitempty"`
	CommonPrefixTruncated bool                                `json:"common_prefix_truncated,omitempty"`
	CommonSuffix          string                              `json:"common_suffix,omitempty"`
	CommonSuffixBytes     int                                 `json:"common_suffix_bytes,omitempty"`
	CommonSuffixTruncated bool                                `json:"common_suffix_truncated,omitempty"`
	LengthBuckets         []ColumnRetainedPayloadLengthBucket `json:"length_buckets,omitempty"`
	GzipBytes             int64                               `json:"gzip_bytes,omitempty"`
	GzipToInputRatio      float64                             `json:"gzip_to_input_ratio,omitempty"`
	ZSTDBytes             int64                               `json:"zstd_bytes,omitempty"`
	ZSTDToInputRatio      float64                             `json:"zstd_to_input_ratio,omitempty"`
}

ColumnRetainedPayloadValueFamilyStat summarizes decoded retained-payload string leaves by path. Compression oracles encode one JSON string per line, so OracleInputBytes includes one separator byte per occurrence.

type ColumnRetainedSemanticStreamV1BlockLayoutAudit 

type ColumnRetainedSemanticStreamV1BlockLayoutAudit struct {
	Rows                 int                                            `json:"rows,omitempty"`
	BlockRows            int                                            `json:"block_rows"`
	BlockCount           int                                            `json:"block_count"`
	PrimaryLocatorBytes  int64                                          `json:"primary_locator_bytes,omitempty"`
	StoredBlockBytes     int64                                          `json:"stored_block_bytes,omitempty"`
	RawBlockBytes        int64                                          `json:"raw_block_bytes"`
	BlockHeaderBytes     int64                                          `json:"block_header_bytes"`
	PathStreamCount      int64                                          `json:"path_stream_count"`
	ValueCount           int64                                          `json:"value_count"`
	PathMetadataBytes    int64                                          `json:"path_metadata_bytes"`
	EntryMetadataBytes   int64                                          `json:"entry_metadata_bytes"`
	ScalarValueBytes     int64                                          `json:"scalar_value_bytes"`
	BlockCodecStats      []ColumnRetainedSemanticStreamV1CodecStat      `json:"block_codec_stats,omitempty"`
	Paths                []ColumnRetainedSemanticStreamV1PathLayoutStat `json:"paths,omitempty"`
	PathsTruncated       bool                                           `json:"paths_truncated,omitempty"`
	PathZSTDInputBytes   int64                                          `json:"path_zstd_input_bytes,omitempty"`
	PathZSTDEncodedBytes int64                                          `json:"path_zstd_encoded_bytes,omitempty"`
}

ColumnRetainedSemanticStreamV1BlockLayoutAudit reports exact raw byte attribution for semantic-stream-v1 side-root blocks plus payload-only codec oracles. It intentionally excludes value-log frame/index overhead.

func ColumnRetainedSemanticStreamV1BlockLayoutAuditFromJSONDocuments 

func ColumnRetainedSemanticStreamV1BlockLayoutAuditFromJSONDocuments(cfg ColumnStoreConfig, documents [][]byte, maxPaths int) (ColumnRetainedSemanticStreamV1BlockLayoutAudit, error)

ColumnRetainedSemanticStreamV1BlockLayoutAuditFromJSONDocuments applies the InsertBatch semantic-stream-v1 transform and audits the resulting side-root block layout. maxPaths limits emitted path rows; zero emits all paths.

type ColumnRetainedSemanticStreamV1CodecStat 

type ColumnRetainedSemanticStreamV1CodecStat struct {
	Codec             string  `json:"codec"`
	Blocks            int     `json:"blocks"`
	RawBytes          int64   `json:"raw_bytes"`
	EncodedBytes      int64   `json:"encoded_bytes,omitempty"`
	StoredBytes       int64   `json:"stored_bytes"`
	KeptBlocks        int     `json:"kept_blocks,omitempty"`
	RawFallbackBlocks int     `json:"raw_fallback_blocks,omitempty"`
	EncodeErrors      int     `json:"encode_errors,omitempty"`
	EncodedToRawRatio float64 `json:"encoded_to_raw_ratio,omitempty"`
	StoredToRawRatio  float64 `json:"stored_to_raw_ratio,omitempty"`
}

type ColumnRetainedSemanticStreamV1PathLayoutStat 

type ColumnRetainedSemanticStreamV1PathLayoutStat struct {
	Path                string  `json:"path"`
	Blocks              int64   `json:"blocks"`
	Occurrences         int64   `json:"occurrences"`
	TotalBytes          int64   `json:"total_bytes"`
	PathMetadataBytes   int64   `json:"path_metadata_bytes"`
	EntryMetadataBytes  int64   `json:"entry_metadata_bytes"`
	ScalarValueBytes    int64   `json:"scalar_value_bytes"`
	MaxScalarValueBytes int     `json:"max_scalar_value_bytes,omitempty"`
	ZSTDBytes           int64   `json:"zstd_bytes,omitempty"`
	ZSTDToTotalRatio    float64 `json:"zstd_to_total_ratio,omitempty"`
}

type ColumnRetainedSemanticStreamV1StorageAccounting 

type ColumnRetainedSemanticStreamV1StorageAccounting struct {
	Rows                int
	PrimaryLocatorBytes int64
	BlockBytes          int64
	BlockCount          int
	TotalBytes          int64
}

ColumnRetainedSemanticStreamV1StorageAccounting reports the retained-payload bytes produced by the semantic-stream-v1 InsertBatch encoding.

func ColumnRetainedSemanticStreamV1StorageAccountingFromJSONDocuments 

func ColumnRetainedSemanticStreamV1StorageAccountingFromJSONDocuments(cfg ColumnStoreConfig, documents [][]byte) (ColumnRetainedSemanticStreamV1StorageAccounting, error)

ColumnRetainedSemanticStreamV1StorageAccountingFromJSONDocuments applies the same retained-payload transform used by InsertBatch and returns the encoded primary retained bytes plus side-root block bytes.

type ColumnSkipScanBound 

type ColumnSkipScanBound struct {
	Key       []byte
	Inclusive bool
	Unbounded bool
}

ColumnSkipScanBound describes one side of a mark-pruning range. When Unbounded is true, Key is ignored and should be nil or empty.

type ColumnSkipScanMark 

type ColumnSkipScanMark struct {
	Name    string
	Rows    int
	MinKeys [][]byte
	MaxKeys [][]byte
}

type ColumnSkipScanPredicate 

type ColumnSkipScanPredicate struct {
	// Position is the zero-based sort-key position. PlanColumnSkipScan only uses
	// bounded predicates that form a contiguous left prefix from position zero;
	// predicates beyond the maximum possible prefix length for this predicate
	// set are ignored for pruning rather than allocating sparse scratch.
	Position int
	Lower    ColumnSkipScanBound
	Upper    ColumnSkipScanBound
}

type ColumnSkipScanResult 

type ColumnSkipScanResult struct {
	LeftPrefixColumns int
	ScheduledMarks    []int
	SkippedMarks      []int
	ScheduledRows     int
	SkippedRows       int
	// contains filtered or unexported fields
}

ColumnSkipScanResult contains reusable planner scratch. Do not copy a live result between workloads; pass the same pointer back to PlanColumnSkipScanInto for reuse or assign a zero value to release retained scratch.

func PlanColumnSkipScan 

func PlanColumnSkipScan(predicates []ColumnSkipScanPredicate, marks []ColumnSkipScanMark) ColumnSkipScanResult

type ColumnSortDirection 

type ColumnSortDirection string
const (
	ColumnSortAscending  ColumnSortDirection = ""
	ColumnSortDescending ColumnSortDirection = "desc"
)

type ColumnSortKey 

type ColumnSortKey struct {
	Column    string              `json:"column"`
	Direction ColumnSortDirection `json:"direction,omitempty"`
}

type ColumnStoreCacheIdentity 

type ColumnStoreCacheIdentity struct {
	Collection                             string
	SchemaHash                             uint64
	CatalogSystemRoot                      uint64
	CatalogCommitSeq                       uint64
	ManifestGeneration                     uint64
	ManifestChecksum                       uint64
	RecoveryAuthoritativeGeneration        uint64
	RecoveryAuthoritativeChecksum          uint64
	RecoveryAuthoritativeAppliedCommandLSN uint64
	ManifestRoot                           uint64
	ManifestRootName                       string
}

func (ColumnStoreCacheIdentity) BlockKey 

func (id ColumnStoreCacheIdentity) BlockKey(kind ColumnCacheEntryKind, partID uint64, asset ColumnAssetCacheIdentity, block uint32) ColumnBlockCacheKey

type ColumnStoreColumn 

type ColumnStoreColumn struct {
	Name      string               `json:"name"`
	Path      string               `json:"path"`
	ValueType ColumnStoreValueType `json:"value_type"`
	// Owner is typed-storage metadata. The zero value preserves compatibility and
	// resolves to typed_row_asset; typed_column_part is opt-in/experimental.
	Owner      TypedStorageFieldOwner `json:"owner,omitempty"`
	Nullable   bool                   `json:"nullable,omitempty"`
	Dictionary bool                   `json:"dictionary,omitempty"`
	VectorDims int                    `json:"vector_dims,omitempty"`
	// ElementsPerRow is the generic logical row width for dense numeric and
	// packed-code typed-column vector payloads.
	ElementsPerRow int `json:"elements_per_row,omitempty"`
	// BytesPerRow is the fixed physical row width for byte_vector/fixed_bytes
	// typed-column payloads.
	BytesPerRow int `json:"bytes_per_row,omitempty"`
	// BitsPerElement records packed-code element width. For packed_uint{1,2,4}_vector
	// value types it is optional metadata and, when present, must match the type.
	BitsPerElement int `json:"bits_per_element,omitempty"`
	// AdjacencyDegree is the fixed number of uint32 neighbors per row for the
	// legacy/fallback dense adjacency_list typed_column_part layout.
	AdjacencyDegree int `json:"adjacency_degree,omitempty"`
	// AdjacencyLayout selects the explicit adjacency_list physical layout. Empty
	// means fixed dense compatibility; uint32_offsets_list is the current
	// quarantined compatibility selector for adapter writer/fallback/direct reads,
	// not the generic uint32_list API.
	AdjacencyLayout    ColumnAdjacencyListLayout `json:"adjacency_layout,omitempty"`
	FixedWidthEncoding ColumnFixedWidthEncoding  `json:"fixed_width_encoding,omitempty"`
}

type ColumnStoreCompactOptions 

type ColumnStoreCompactOptions struct {
	// ReadIntegrity controls validation while reading existing column assets to
	// materialize the latest-visible row set. The zero value uses the default
	// column-asset read policy.
	ReadIntegrity ColumnAssetReadIntegrity
}

ColumnStoreCompactOptions controls logical column-store compaction.

type ColumnStoreCompactStats 

type ColumnStoreCompactStats struct {
	Compacted bool

	PreviousGeneration uint64
	NewGeneration      uint64
	ManifestRoot       uint64
	SystemRoot         uint64

	ManifestRecordsBefore int
	ManifestRecordsAfter  int
	MutationPartsBefore   int
	MutationPartsAfter    int

	RowsScanned       int
	DeletedRows       int
	RowsCompacted     int
	PhysicalBytesRead int64

	AssetsPublished            int
	AggregateMetadataPublished int
	PublishedRefs              []ColumnAssetRef
	SupersededRefs             []ColumnAssetRef
}

ColumnStoreCompactStats summarizes a logical column-store compaction.

type ColumnStoreConfig 

type ColumnStoreConfig struct {
	Enabled                                bool                              `json:"enabled,omitempty"`
	Columns                                []ColumnStoreColumn               `json:"columns,omitempty"`
	SortKey                                []ColumnSortKey                   `json:"sort_key,omitempty"`
	AggregateMetadata                      []ColumnAggregateMetadata         `json:"aggregate_metadata,omitempty"`
	RetainedPayload                        ColumnRetainedPayloadPolicy       `json:"retained_payload,omitempty"`
	RetainedPayloadEncoding                ColumnRetainedPayloadEncoding     `json:"retained_payload_encoding,omitempty"`
	Reconstruction                         ColumnReconstructionPolicy        `json:"reconstruction,omitempty"`
	AssetManager                           *ColumnAssetManagerConfig         `json:"asset_manager,omitempty"`
	ManifestRoot                           *ColumnManifestRootDescriptor     `json:"manifest_root,omitempty"`
	ActiveManifest                         *ColumnManifestIdentity           `json:"active_manifest,omitempty"`
	RecoveryAuthoritativeManifest          *ColumnManifestIdentity           `json:"recovery_authoritative_manifest,omitempty"`
	RecoveryAuthoritativeAppliedCommandLSN uint64                            `json:"recovery_authoritative_applied_command_lsn,omitempty"`
	PhysicalMutationParts                  uint64                            `json:"physical_mutation_parts,omitempty"`
	ProfileSupport                         ColumnStoreProfileSupport         `json:"profile_support,omitempty"`
	TypedColumnCompression                 ColumnStoreTypedColumnCompression `json:"typed_column_compression,omitempty"`
	TypedColumnSectionCompression          ColumnStoreTypedColumnCompression `json:"typed_column_section_compression,omitempty"`
	Locator                                *ColumnLocatorConfig              `json:"locator,omitempty"`
	ControlRootStoragePolicy               RootStoragePolicy                 `json:"control_root_storage_policy,omitempty"`
	SchemaHash                             uint64                            `json:"schema_hash,omitempty"`
}

type ColumnStorePhysicalAccounting 

type ColumnStorePhysicalAccounting struct {
	Complete                   bool                                     `json:"complete"`
	Collection                 string                                   `json:"collection"`
	Namespace                  string                                   `json:"namespace,omitempty"`
	ManifestRootName           string                                   `json:"manifest_root_name,omitempty"`
	ManifestRootID             uint64                                   `json:"manifest_root_id,omitempty"`
	ManifestGeneration         uint64                                   `json:"manifest_generation,omitempty"`
	ManifestChecksum           uint64                                   `json:"manifest_checksum,omitempty"`
	RecoveryManifestGeneration uint64                                   `json:"recovery_manifest_generation,omitempty"`
	RecoveryManifestChecksum   uint64                                   `json:"recovery_manifest_checksum,omitempty"`
	AppliedCommandLSN          uint64                                   `json:"applied_command_lsn,omitempty"`
	ManifestRecords            int                                      `json:"manifest_records,omitempty"`
	RowAssetRefs               int                                      `json:"row_asset_refs,omitempty"`
	TypedColumnPartRefs        int                                      `json:"typed_column_part_refs,omitempty"`
	AggregateMetadataRefs      int                                      `json:"aggregate_metadata_refs,omitempty"`
	DictionaryCodeRefs         int                                      `json:"dictionary_code_refs,omitempty"`
	Int64ValueRefs             int                                      `json:"int64_value_refs,omitempty"`
	GraphAssetRefs             int                                      `json:"graph_asset_refs,omitempty"`
	Totals                     ColumnStorePhysicalAccountingTotals      `json:"totals"`
	AssetKinds                 []ColumnStorePhysicalAssetKindAccounting `json:"asset_kinds,omitempty"`
	RowAssets                  []ColumnStoreRowAssetAccounting          `json:"row_assets,omitempty"`
	TypedColumnParts           []ColumnStoreTypedColumnPartAccounting   `json:"typed_column_parts,omitempty"`
	SidecarAssets              []ColumnStorePhysicalAssetAccounting     `json:"sidecar_assets,omitempty"`
	GraphAssets                []ColumnStorePhysicalAssetRefAccounting  `json:"graph_assets,omitempty"`
	Warnings                   []string                                 `json:"warnings,omitempty"`
}

ColumnStorePhysicalAccounting reports the active column manifest's referenced physical assets and typed-column part section bytes.

type ColumnStorePhysicalAccountingOptions 

type ColumnStorePhysicalAccountingOptions struct {
	DetailedSections bool                     `json:"detailed_sections,omitempty"`
	ReadIntegrity    ColumnAssetReadIntegrity `json:"read_integrity,omitempty"`
}

ColumnStorePhysicalAccountingOptions controls production column-store byte accounting. Section bytes are decoded from persisted typed-column part images and are a breakdown of typed-column part payload bytes, not an extra total.

type ColumnStorePhysicalAccountingTotals 

type ColumnStorePhysicalAccountingTotals struct {
	ReferencedAssetBytes   int64                                    `json:"referenced_asset_bytes,omitempty"`
	RowAssetBytes          int64                                    `json:"row_asset_bytes,omitempty"`
	TypedColumnPartBytes   int64                                    `json:"typed_column_part_bytes,omitempty"`
	AggregateMetadataBytes int64                                    `json:"aggregate_metadata_bytes,omitempty"`
	DictionaryCodeBytes    int64                                    `json:"dictionary_code_bytes,omitempty"`
	Int64ValueBytes        int64                                    `json:"int64_value_bytes,omitempty"`
	GraphAssetBytes        int64                                    `json:"graph_asset_bytes,omitempty"`
	RowAssetSections       ColumnStoreRowAssetByteAccounting        `json:"row_asset_sections"`
	TypedColumnSections    ColumnStoreTypedColumnPartByteAccounting `json:"typed_column_sections"`
}

ColumnStorePhysicalAccountingTotals contains manifest-referenced payload bytes. TypedColumnSections is a category breakdown of TypedColumnPartBytes.

type ColumnStorePhysicalAssetAccounting 

type ColumnStorePhysicalAssetAccounting struct {
	Ref    ColumnStorePhysicalAssetRefAccounting `json:"ref"`
	Rows   int                                   `json:"rows,omitempty"`
	Bytes  int64                                 `json:"bytes"`
	Role   ColumnManifestPartRole                `json:"role,omitempty"`
	Reason ColumnPublishOperation                `json:"reason,omitempty"`
	Column string                                `json:"column,omitempty"`
	Name   string                                `json:"name,omitempty"`
}

ColumnStorePhysicalAssetAccounting describes one active manifest asset.

type ColumnStorePhysicalAssetKindAccounting 

type ColumnStorePhysicalAssetKindAccounting struct {
	Kind  ColumnAssetKind `json:"kind"`
	Count int             `json:"count"`
	Bytes int64           `json:"bytes"`
	Rows  int             `json:"rows,omitempty"`
}

ColumnStorePhysicalAssetKindAccounting summarizes active manifest refs by concrete column asset kind.

type ColumnStorePhysicalAssetRefAccounting 

type ColumnStorePhysicalAssetRefAccounting struct {
	Kind       ColumnAssetKind `json:"kind"`
	Namespace  string          `json:"namespace,omitempty"`
	Generation uint64          `json:"generation"`
	PartID     uint64          `json:"part_id"`
	FileID     uint32          `json:"file_id"`
	Offset     int64           `json:"offset"`
	Length     int64           `json:"length"`
	Checksum   uint32          `json:"checksum"`
}

ColumnStorePhysicalAssetRefAccounting is a JSON-friendly public copy of ColumnAssetRef fields.

type ColumnStoreProfileSupport 

type ColumnStoreProfileSupport string
const (
	ColumnStoreProfileDurableOnly      ColumnStoreProfileSupport = "durable-only"
	ColumnStoreProfileBenchmarkRelaxed ColumnStoreProfileSupport = "benchmark-relaxed"
)

type ColumnStoreRowAssetAccounting 

type ColumnStoreRowAssetAccounting struct {
	Asset   ColumnStorePhysicalAssetAccounting `json:"asset"`
	Payload ColumnStoreRowAssetByteAccounting  `json:"payload"`
}

ColumnStoreRowAssetAccounting reports one physical row asset and its serialized payload byte breakdown.

type ColumnStoreRowAssetByteAccounting 

type ColumnStoreRowAssetByteAccounting struct {
	Rows                   int                                   `json:"rows,omitempty"`
	DeletedRows            int                                   `json:"deleted_rows,omitempty"`
	Columns                int                                   `json:"columns,omitempty"`
	Operation              ColumnPublishOperation                `json:"operation,omitempty"`
	SerializedAssetBytes   int64                                 `json:"serialized_asset_bytes,omitempty"`
	FormatHeaderBytes      int64                                 `json:"format_header_bytes,omitempty"`
	ColumnMetadataBytes    int64                                 `json:"column_metadata_bytes,omitempty"`
	RowEncodingHeaderBytes int64                                 `json:"row_encoding_header_bytes,omitempty"`
	RowIDStoredBytes       int64                                 `json:"row_id_stored_bytes,omitempty"`
	RowIDValueBytes        int64                                 `json:"row_id_value_bytes,omitempty"`
	RowDeletedFlagBytes    int64                                 `json:"row_deleted_flag_bytes,omitempty"`
	RowValueHeaderBytes    int64                                 `json:"row_value_header_bytes,omitempty"`
	RowValuePayloadBytes   int64                                 `json:"row_value_payload_bytes,omitempty"`
	TotalStoredBytes       int64                                 `json:"total_stored_bytes,omitempty"`
	BytesPerRow            float64                               `json:"bytes_per_row,omitempty"`
	ColumnsDetail          []ColumnStoreRowAssetColumnAccounting `json:"columns_detail,omitempty"`
	// contains filtered or unexported fields
}

ColumnStoreRowAssetByteAccounting breaks down the legacy TCPA row asset envelope. RowIDStoredBytes includes the per-row length prefix; RowIDValueBytes is only the document ID payload. RowValueHeaderBytes covers repeated per-value type/null/present metadata, while RowValuePayloadBytes covers the encoded value bodies.

type ColumnStoreRowAssetColumnAccounting 

type ColumnStoreRowAssetColumnAccounting struct {
	Column            string `json:"column"`
	Type              string `json:"type"`
	Rows              int    `json:"rows"`
	PresentRows       int    `json:"present_rows"`
	NullRows          int    `json:"null_rows"`
	ValueHeaderBytes  int64  `json:"value_header_bytes"`
	ValuePayloadBytes int64  `json:"value_payload_bytes"`
	StoredBytes       int64  `json:"stored_bytes"`
}

ColumnStoreRowAssetColumnAccounting reports row-asset bytes for one row-owned column.

type ColumnStoreTypedColumnColumnAccounting 

type ColumnStoreTypedColumnColumnAccounting struct {
	Column               string         `json:"column"`
	Type                 string         `json:"type"`
	Rows                 int            `json:"rows"`
	Blocks               int            `json:"blocks"`
	LogicalValueBytes    int64          `json:"logical_value_bytes"`
	EncodedRawBytes      int64          `json:"encoded_raw_bytes"`
	StoredBytes          int64          `json:"stored_bytes"`
	Encoding             string         `json:"encoding"`
	RequestedCompression string         `json:"requested_compression"`
	ActualCompressionMix map[string]int `json:"actual_compression_mix,omitempty"`
	CompressionAttempted int            `json:"compression_attempted"`
	CompressionKept      int            `json:"compression_kept"`
	CompressionRejected  int            `json:"compression_rejected"`
	FallbackReasons      map[string]int `json:"fallback_reasons,omitempty"`
	CompressionNanos     int64          `json:"compression_nanos"`
}

ColumnStoreTypedColumnColumnAccounting reports one declared typed-column payload's codec/storage contribution for benchmark/storage reports.

type ColumnStoreTypedColumnCompression 

type ColumnStoreTypedColumnCompression string
const (
	ColumnStoreTypedColumnCompressionDefault ColumnStoreTypedColumnCompression = ""
	ColumnStoreTypedColumnCompressionNone    ColumnStoreTypedColumnCompression = "none"
	ColumnStoreTypedColumnCompressionSnappy  ColumnStoreTypedColumnCompression = "snappy"
	ColumnStoreTypedColumnCompressionLZ4     ColumnStoreTypedColumnCompression = "lz4"
	ColumnStoreTypedColumnCompressionZSTD    ColumnStoreTypedColumnCompression = "zstd"
)

type ColumnStoreTypedColumnCompressionAccounting 

type ColumnStoreTypedColumnCompressionAccounting struct {
	Column                 string  `json:"column"`
	Substream              string  `json:"substream"`
	Encoding               string  `json:"encoding"`
	RequestedCompression   string  `json:"requested_compression"`
	ActualCompression      string  `json:"actual_compression"`
	Blocks                 int     `json:"blocks"`
	CompressionAttempted   int     `json:"compression_attempted"`
	CompressionKept        int     `json:"compression_kept"`
	CompressionRejected    int     `json:"compression_rejected"`
	FallbackReason         string  `json:"fallback_reason,omitempty"`
	EncodedRawBytes        int64   `json:"encoded_raw_bytes"`
	StoredBytes            int64   `json:"stored_bytes"`
	CompressionNanos       int64   `json:"compression_nanos"`
	StoredToEncodedRawRate float64 `json:"stored_to_encoded_raw_rate"`
}

ColumnStoreTypedColumnCompressionAccounting reports requested-vs-actual compression admission and bytes for one column/substream/codec bucket.

type ColumnStoreTypedColumnPartAccounting 

type ColumnStoreTypedColumnPartAccounting struct {
	Asset ColumnStorePhysicalAssetAccounting       `json:"asset"`
	Image ColumnStoreTypedColumnPartByteAccounting `json:"image"`
}

ColumnStoreTypedColumnPartAccounting reports one typed-column part image and its serialized section/category byte breakdown.

type ColumnStoreTypedColumnPartByteAccounting 

type ColumnStoreTypedColumnPartByteAccounting struct {
	Rows                       int                                           `json:"rows,omitempty"`
	Columns                    int                                           `json:"columns,omitempty"`
	SerializedImageBytes       int64                                         `json:"serialized_image_bytes,omitempty"`
	SerializedManifestBytes    int64                                         `json:"serialized_manifest_bytes,omitempty"`
	SerializedPaddingBytes     int64                                         `json:"serialized_padding_bytes,omitempty"`
	DeclaredColumnBytes        int64                                         `json:"declared_column_bytes,omitempty"`
	DeclaredColumnOffsetsBytes int64                                         `json:"declared_column_offsets_bytes,omitempty"`
	DeclaredColumnValuesBytes  int64                                         `json:"declared_column_values_bytes,omitempty"`
	DictionaryBytes            int64                                         `json:"dictionary_bytes,omitempty"`
	MarkBytes                  int64                                         `json:"mark_bytes,omitempty"`
	SortKeyMetadataBytes       int64                                         `json:"sort_key_metadata_bytes,omitempty"`
	AggregateMetadataBytes     int64                                         `json:"aggregate_metadata_bytes,omitempty"`
	ColumnStatsBytes           int64                                         `json:"column_stats_bytes,omitempty"`
	PruningMetadataBytes       int64                                         `json:"pruning_metadata_bytes,omitempty"`
	DescriptorBytes            int64                                         `json:"descriptor_bytes,omitempty"`
	LayoutContractBytes        int64                                         `json:"layout_contract_bytes,omitempty"`
	LocatorBytes               int64                                         `json:"locator_bytes,omitempty"`
	TotalStoredBytes           int64                                         `json:"total_stored_bytes,omitempty"`
	BytesPerRow                float64                                       `json:"bytes_per_row,omitempty"`
	LogicalValueBytes          int64                                         `json:"logical_value_bytes,omitempty"`
	EncodedRawBytes            int64                                         `json:"encoded_raw_bytes,omitempty"`
	CodecBlocks                int                                           `json:"codec_blocks,omitempty"`
	CompressionNanos           int64                                         `json:"compression_nanos,omitempty"`
	ColumnsDetail              []ColumnStoreTypedColumnColumnAccounting      `json:"columns_detail,omitempty"`
	CompressionDetail          []ColumnStoreTypedColumnCompressionAccounting `json:"compression_detail,omitempty"`
	SerializedSections         []ColumnStoreTypedColumnPartSectionAccounting `json:"serialized_sections,omitempty"`
	// contains filtered or unexported fields
}

ColumnStoreTypedColumnPartByteAccounting mirrors the persisted image categories needed by external benchmark/accounting tools without exposing TreeDB/internal/typedcolumn types.

type ColumnStoreTypedColumnPartSectionAccounting 

type ColumnStoreTypedColumnPartSectionAccounting struct {
	Kind             string  `json:"kind"`
	Category         string  `json:"category"`
	Name             string  `json:"name,omitempty"`
	Column           string  `json:"column,omitempty"`
	Bytes            int64   `json:"bytes"`
	Compression      string  `json:"compression,omitempty"`
	RawBytes         int64   `json:"raw_bytes,omitempty"`
	StoredBytes      int64   `json:"stored_bytes,omitempty"`
	CompressionRatio float64 `json:"compression_ratio,omitempty"`
}

ColumnStoreTypedColumnPartSectionAccounting reports one serialized section in a typed-column part image.

type ColumnStoreValueType 

type ColumnStoreValueType string
const (
	ColumnStoreValueBool    ColumnStoreValueType = "bool"
	ColumnStoreValueInt64   ColumnStoreValueType = "int64"
	ColumnStoreValueFloat32 ColumnStoreValueType = "float32"
	ColumnStoreValueDouble  ColumnStoreValueType = "double"
	ColumnStoreValueString  ColumnStoreValueType = "string"
	ColumnStoreValueInt8    ColumnStoreValueType = "int8"
	ColumnStoreValueUint8   ColumnStoreValueType = "uint8"
	ColumnStoreValueInt16   ColumnStoreValueType = "int16"
	ColumnStoreValueUint16  ColumnStoreValueType = "uint16"
	ColumnStoreValueInt32   ColumnStoreValueType = "int32"
	ColumnStoreValueUint32  ColumnStoreValueType = "uint32"
	ColumnStoreValueUint64  ColumnStoreValueType = "uint64"
	// Float16 and BFloat16 are storage-only raw 16-bit bit payloads.
	ColumnStoreValueFloat16           ColumnStoreValueType = "float16"
	ColumnStoreValueBFloat16          ColumnStoreValueType = "bfloat16"
	ColumnStoreValueUint8Vector       ColumnStoreValueType = "uint8_vector"
	ColumnStoreValueInt8Vector        ColumnStoreValueType = "int8_vector"
	ColumnStoreValueUint16Vector      ColumnStoreValueType = "uint16_vector"
	ColumnStoreValueInt16Vector       ColumnStoreValueType = "int16_vector"
	ColumnStoreValueUint32Vector      ColumnStoreValueType = "uint32_vector"
	ColumnStoreValueInt32Vector       ColumnStoreValueType = "int32_vector"
	ColumnStoreValueUint64Vector      ColumnStoreValueType = "uint64_vector"
	ColumnStoreValueInt64Vector       ColumnStoreValueType = "int64_vector"
	ColumnStoreValueFloat16Vector     ColumnStoreValueType = "float16_vector"
	ColumnStoreValueBFloat16Vector    ColumnStoreValueType = "bfloat16_vector"
	ColumnStoreValueFloat32Vector     ColumnStoreValueType = "float32_vector"
	ColumnStoreValueFloat64Vector     ColumnStoreValueType = "float64_vector"
	ColumnStoreValueByteVector        ColumnStoreValueType = "byte_vector"
	ColumnStoreValuePackedBitVector   ColumnStoreValueType = "packed_bit_vector"
	ColumnStoreValuePackedUint2Vector ColumnStoreValueType = "packed_uint2_vector"
	ColumnStoreValuePackedUint4Vector ColumnStoreValueType = "packed_uint4_vector"
	ColumnStoreValueUint32List        ColumnStoreValueType = "uint32_list"
	ColumnStoreValueBytes             ColumnStoreValueType = "bytes"
	// AdjacencyList is the current compatibility name for graph adjacency data.
	// It must not become the target variable-list datastore primitive; #1984/#1985
	// own the generic uint32_list logical type and raw_uint32_offsets_list encoding.
	ColumnStoreValueAdjacencyList ColumnStoreValueType = "adjacency_list"
)

type CommitAmbiguousError 

type CommitAmbiguousError struct {
	Operation string
	Err       error
}

CommitAmbiguousError reports that a collection mutation reached its logical commit point before a later visibility, flush, checkpoint, response, or bookkeeping step failed. The operation may already be visible or recoverable; callers should not blindly retry non-idempotent mutations.

func (*CommitAmbiguousError) Error 

func (e *CommitAmbiguousError) Error() string

func (*CommitAmbiguousError) Is 

func (e *CommitAmbiguousError) Is(target error) bool

func (*CommitAmbiguousError) Unwrap 

func (e *CommitAmbiguousError) Unwrap() error

type CompactStorageOptions 

type CompactStorageOptions = backenddb.CompactStorageOptions

CompactStorageOptions controls collection-aware storage compaction.

type CompactStorageStats 

type CompactStorageStats struct {
	RootOverlays map[string]CollectionRootOverlayCompactionStats `json:"root_overlays,omitempty"`
	Storage      backenddb.CompactStorageStats                   `json:"storage"`
}

CompactStorageStats summarizes collection root-overlay compaction plus the underlying TreeDB storage compaction report.

type DocumentFetchOptions 

type DocumentFetchOptions struct {
	// IncludePaths is an optional allowlist of top-level JSON fields to return.
	// When non-empty, fields not listed here are skipped. Nested projection paths
	// are intentionally unsupported for this pre-alpha API and fail closed.
	IncludePaths []string
	// ExcludePaths is an optional denylist of top-level JSON fields to skip.
	// Excludes take precedence over IncludePaths.
	ExcludePaths []string
	// Format selects the materialized document format. The zero value preserves
	// collection-default output; projected fetches currently require JSON output.
	Format DocumentFormat
	// ColumnAssetReadIntegrity controls typed-row/physical row asset reads used
	// to locate or point-fetch the visible row for a document. Typed-column part
	// reconstruction uses the prepared read-view cache with verified reads.
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

DocumentFetchOptions configures snapshot-bound document materialization. The zero value preserves Collection.Get-style full-document output and verified column-asset reads. Projection paths are explicit JSON top-level fields: IncludePaths is an allowlist when non-empty, ExcludePaths wins over includes, missing fields are ignored, and present JSON null values are preserved. The same projection contract is applied to retained payload fields, typed-row asset fields, and typed-column-part fields.

type DocumentFetchResponse 

type DocumentFetchResponse struct {
	Results []DocumentFetchResult
	Stats   DocumentMaterializationStats
}

DocumentFetchResponse contains ordered materialization results and per-call diagnostics.

type DocumentFetchResult 

type DocumentFetchResult struct {
	ID       []byte
	Document []byte
	Found    bool
	RowRef   DocumentRowRef
}

DocumentFetchResult is one materialized document result. ID and Document are response-owned slices; non-empty Document slices are cap-limited so appending to one result cannot mutate another result in the same response. Missing documents have Found=false and Document=nil. RowRef is populated only when typed-storage reconstruction found a visible physical row; it is zero for retained-payload-only results.

type DocumentFormat 

type DocumentFormat string
const (
	DocumentFormatDefault    DocumentFormat = ""
	DocumentFormatJSON       DocumentFormat = "json"
	DocumentFormatBSON       DocumentFormat = "bson"
	DocumentFormatTemplateV1 DocumentFormat = "template-v1"
)

type DocumentMaterializationStats 

type DocumentMaterializationStats struct {
	DocumentsRequested  uint64
	DocumentsFetched    uint64
	DocumentsMissing    uint64
	DocumentBytes       uint64
	OutputBytes         uint64
	FieldsReconstructed uint64
	FieldsSkipped       uint64
	FetchNanos          int64

	RetainedPayloadFetches uint64
	RetainedPayloadBytes   uint64

	VisibilityScans         uint64
	VisibilityRowsScanned   uint64
	VisibilityRows          uint64
	VisibilityPhysicalBytes int64
	VisibilityNanos         int64

	TypedColumnRows        uint64
	TypedColumnCacheHits   uint64
	TypedColumnCacheMisses uint64
	TypedColumnPartLoads   uint64
	TypedColumnPartDecodes uint64
	TypedColumnNanos       int64

	JSONReconstructionRows  uint64
	JSONReconstructionNanos int64

	RowLocatorBuilds        uint64
	RowLocatorLookups       uint64
	RowLocatorMisses        uint64
	RowLocatorRowsScanned   uint64
	RowLocatorPhysicalBytes int64
	RowLocatorNanos         int64

	PointRowFetches uint64
	PointRowDecodes uint64

	RowRefFallbackScans      uint64
	RowRefUnsupported        uint64
	RowRefValidationFailures uint64

	AssetMmapHits        uint64
	AssetReadAtFallbacks uint64
	AssetFileOpens       uint64
	AssetFileCloses      uint64
	AssetActiveHandles   int64
}

DocumentMaterializationStats attributes the work performed by a CollectionReadView fetch. Counters describe the fetch call; AssetActiveHandles is the read view's current mappedresource handle count after the fetch.

type DocumentRecord 

type DocumentRecord struct {
	ID       []byte
	Document []byte
}

DocumentRecord is one primary collection record returned by ScanDocuments. ID and Document are cloned byte slices owned by the caller.

type DocumentRowRef 

type DocumentRowRef struct {
	DocumentID        []byte
	Generation        uint64
	PartID            uint64
	RowIndex          int
	AppliedCommandLSN uint64
}

DocumentRowRef identifies a document row in a snapshot-bound typed-storage materialization request. Refs are produced by typed-storage locator lookups or by FetchDocumentsByID scan reconstruction and are validated against the decoded physical row before materialization.

type DocumentRowRefLookupResponse 

type DocumentRowRefLookupResponse struct {
	Results []DocumentRowRefLookupResult
	Stats   DocumentMaterializationStats
}

DocumentRowRefLookupResponse contains ordered row-ref lookup results and diagnostics for the snapshot-derived locator work.

type DocumentRowRefLookupResult 

type DocumentRowRefLookupResult struct {
	ID     []byte
	RowRef DocumentRowRef
	Found  bool
}

DocumentRowRefLookupResult is one ordered document-row locator lookup result. Missing or deleted documents have Found=false and a zero RowRef.

type HybridCandidateBudgetPolicy 

type HybridCandidateBudgetPolicy string

HybridCandidateBudgetPolicy reports whether SearchHybrid used the fixed caller-provided source budgets or an exact adaptive RRF budget proof. 

const (
	HybridCandidateBudgetPolicyFixed       HybridCandidateBudgetPolicy = "fixed"
	HybridCandidateBudgetPolicyAdaptiveRRF HybridCandidateBudgetPolicy = "adaptive_rrf"
)

type HybridCandidateBudgetStopReason 

type HybridCandidateBudgetStopReason string

HybridCandidateBudgetStopReason is a low-cardinality explanation for the candidate-budget decision. Fallback reasons use the same vocabulary. 

const (
	HybridCandidateBudgetStopReasonNone                   HybridCandidateBudgetStopReason = "none"
	HybridCandidateBudgetStopReasonFixedPolicy            HybridCandidateBudgetStopReason = "fixed_policy"
	HybridCandidateBudgetStopReasonNoReduction            HybridCandidateBudgetStopReason = "no_reduction"
	HybridCandidateBudgetStopReasonEmptyScalarAllowSet    HybridCandidateBudgetStopReason = "empty_scalar_allow_set"
	HybridCandidateBudgetStopReasonSingleSourceTopK       HybridCandidateBudgetStopReason = "single_source_topk"
	HybridCandidateBudgetStopReasonExactRRFBound          HybridCandidateBudgetStopReason = "exact_rrf_bound"
	HybridCandidateBudgetStopReasonRequestedBudgetReached HybridCandidateBudgetStopReason = "requested_budget_reached"
	HybridCandidateBudgetStopReasonUnsupportedFusion      HybridCandidateBudgetStopReason = "unsupported_fusion"
	HybridCandidateBudgetStopReasonPostfilterUnsupported  HybridCandidateBudgetStopReason = "postfilter_unsupported"
	HybridCandidateBudgetStopReasonExactBoundInsufficient HybridCandidateBudgetStopReason = "exact_bound_insufficient"
)

type HybridCandidateResponse 

type HybridCandidateResponse struct {
	Stats      HybridSearchStats       `json:"stats,omitempty"`
	Candidates []HybridSearchCandidate `json:"candidates,omitempty"`
}

HybridCandidateResponse is returned by candidate-only source adapters. The adapters are pre-fusion and pre-final-fetch: Candidates contains source hits only, and Stats reports candidate-generation counters in the shared hybrid vocabulary.

type HybridCandidateSource 

type HybridCandidateSource string

HybridCandidateSource identifies the candidate-producing subsystem. 

const (
	HybridCandidateSourceText   HybridCandidateSource = "text"
	HybridCandidateSourceVector HybridCandidateSource = "vector"
)

type HybridConsistencyMode 

type HybridConsistencyMode string

HybridConsistencyMode identifies how text, vector, scalar, and final document fetch phases bind to a collection snapshot. 

const (
	HybridConsistencyCurrentSnapshot HybridConsistencyMode = "current_snapshot"
	HybridConsistencyBoundSnapshot   HybridConsistencyMode = "bound_snapshot"
)

type HybridConsistencyOptions 

type HybridConsistencyOptions struct {
	Mode HybridConsistencyMode `json:"mode,omitempty"`
}

HybridConsistencyOptions describes the snapshot binding requested by the caller. The zero value uses the current collection snapshot after flushing buffered writes, matching existing collection read visibility.

type HybridFailClosedReason 

type HybridFailClosedReason string

HybridFailClosedReason is a low-cardinality reason suitable for counters and debug traces when a hybrid query refuses to run. 

const (
	HybridFailClosedReasonNone                      HybridFailClosedReason = "none"
	HybridFailClosedReasonUnsupported               HybridFailClosedReason = "unsupported"
	HybridFailClosedReasonTextIndexUnavailable      HybridFailClosedReason = "text_index_unavailable"
	HybridFailClosedReasonVectorIndexUnavailable    HybridFailClosedReason = "vector_index_unavailable"
	HybridFailClosedReasonTextIndexStale            HybridFailClosedReason = "text_index_stale"
	HybridFailClosedReasonVectorIndexStale          HybridFailClosedReason = "vector_index_stale"
	HybridFailClosedReasonScalarFilterUnbounded     HybridFailClosedReason = "scalar_filter_unbounded"
	HybridFailClosedReasonSnapshotMismatch          HybridFailClosedReason = "snapshot_mismatch"
	HybridFailClosedReasonDocumentFetchUnavailable  HybridFailClosedReason = "document_fetch_unavailable"
	HybridFailClosedReasonFullDocumentScanForbidden HybridFailClosedReason = "full_document_scan_forbidden"
)

type HybridFusionMethod 

type HybridFusionMethod string

HybridFusionMethod selects the rank-fusion algorithm. The zero value defaults to reciprocal-rank fusion for the first implementation. 

const (
	HybridFusionMethodRRF             HybridFusionMethod = "rrf"
	HybridFusionMethodWeightedRRF     HybridFusionMethod = "weighted_rrf"
	HybridFusionMethodNormalizedScore HybridFusionMethod = "normalized_score"
)

type HybridFusionOptions 

type HybridFusionOptions struct {
	Method       HybridFusionMethod      `json:"method,omitempty"`
	RRFK         int                     `json:"rrf_k,omitempty"`
	TiePolicy    HybridFusionTiePolicy   `json:"tie_policy,omitempty"`
	SourceOrder  []HybridCandidateSource `json:"source_order,omitempty"`
	TextWeight   float64                 `json:"text_weight,omitempty"`
	VectorWeight float64                 `json:"vector_weight,omitempty"`
}

HybridFusionOptions configures deterministic rank fusion. For RRF, RRFK=0 means the implementation default (documented as 60 by the contract spec).

type HybridFusionTiePolicy 

type HybridFusionTiePolicy string

HybridFusionTiePolicy names the deterministic total-order policy applied after fused scores are computed. 

const (
	HybridFusionTiePolicyScoreBestRankSourceID HybridFusionTiePolicy = "fused_score_best_rank_source_order_id"
)

type HybridResultMode 

type HybridResultMode string

HybridResultMode controls how much final result payload SearchHybrid returns. Score-only and compact modes do not fetch final documents; full mode fetches bounded top-k documents after fusion. 

const (
	HybridResultModeCompact   HybridResultMode = "compact"
	HybridResultModeScoreOnly HybridResultMode = "score_only"
	HybridResultModeFull      HybridResultMode = "full"
)

type HybridScalarFilter 

type HybridScalarFilter struct {
	IndexName string             `json:"index_name"`
	Value     any                `json:"value,omitempty"`
	Range     *IndexRangeOptions `json:"range,omitempty"`
}

HybridScalarFilter describes a bounded scalar-index filter. Equality uses Value; ranges use Range. Strategies that need an indexed allow-set must fail closed when the filter cannot be served by a scalar index.

type HybridScalarFilterStrategy 

type HybridScalarFilterStrategy string

HybridScalarFilterStrategy describes where scalar/metadata filters are applied relative to candidate generation and fusion. 

const (
	HybridScalarFilterStrategyPrefilter   HybridScalarFilterStrategy = "prefilter"
	HybridScalarFilterStrategyPostfilter  HybridScalarFilterStrategy = "postfilter"
	HybridScalarFilterStrategyTextFirst   HybridScalarFilterStrategy = "text_first"
	HybridScalarFilterStrategyVectorFirst HybridScalarFilterStrategy = "vector_first"
	HybridScalarFilterStrategyUnionFusion HybridScalarFilterStrategy = "union_fusion"
)

type HybridScoreKind 

type HybridScoreKind string

HybridScoreKind identifies the native score scale carried on a candidate. Higher scores are better after conversion into this shared candidate shape. 

const (
	HybridScoreKindBM25             HybridScoreKind = "bm25"
	HybridScoreKindBM25F            HybridScoreKind = "bm25f"
	HybridScoreKindVectorSimilarity HybridScoreKind = "vector_similarity"
)

type HybridSearchCandidate 

type HybridSearchCandidate struct {
	ID          []byte                `json:"id"`
	Source      HybridCandidateSource `json:"source"`
	IndexName   string                `json:"index_name"`
	SourceRank  int                   `json:"source_rank"`
	Score       float64               `json:"score"`
	ScoreKind   HybridScoreKind       `json:"score_kind"`
	TextMatches []HybridTextMatch     `json:"text_matches,omitempty"`
}

HybridSearchCandidate is the shared candidate shape produced by text and vector candidate-only paths before fusion.

type HybridSearchDebugOptions 

type HybridSearchDebugOptions struct {
	IncludeCandidates bool `json:"include_candidates,omitempty"`
}

HybridSearchDebugOptions controls optional trace payloads. Implementations must keep normal production stats available without requiring candidate echo.

type HybridSearchOptions 

type HybridSearchOptions struct {
	TopK                 int                        `json:"top_k"`
	Text                 *HybridTextQuery           `json:"text,omitempty"`
	Vector               *HybridVectorQuery         `json:"vector,omitempty"`
	ScalarFilter         *HybridScalarFilter        `json:"scalar_filter,omitempty"`
	ScalarFilterStrategy HybridScalarFilterStrategy `json:"scalar_filter_strategy,omitempty"`
	Fusion               HybridFusionOptions        `json:"fusion,omitempty"`
	ResultMode           HybridResultMode           `json:"result_mode,omitempty"`
	IncludeDocuments     bool                       `json:"include_documents,omitempty"`
	DocumentFetchOptions DocumentFetchOptions       `json:"document_fetch_options,omitempty"`
	Consistency          HybridConsistencyOptions   `json:"consistency,omitempty"`
	Debug                HybridSearchDebugOptions   `json:"debug,omitempty"`
}

HybridSearchOptions is the collection-level combined retrieval contract for scalar filters, lexical candidates, vector candidates, deterministic fusion, and bounded final document fetch.

type HybridSearchPlan 

type HybridSearchPlan struct {
	ScalarFilterStrategy HybridScalarFilterStrategy `json:"scalar_filter_strategy,omitempty"`
	FusionMethod         HybridFusionMethod         `json:"fusion_method,omitempty"`
	FusionTiePolicy      HybridFusionTiePolicy      `json:"fusion_tie_policy,omitempty"`
	ResultMode           HybridResultMode           `json:"result_mode,omitempty"`
	TextCandidateLimit   int                        `json:"text_candidate_limit,omitempty"`
	VectorCandidateLimit int                        `json:"vector_candidate_limit,omitempty"`
	FinalTopK            int                        `json:"final_top_k,omitempty"`
}

HybridSearchPlan reports the planner choices that affected source ordering, scalar filtering, fusion, and final fetch bounds.

type HybridSearchResponse 

type HybridSearchResponse struct {
	Snapshot   HybridSearchSnapshot    `json:"snapshot,omitempty"`
	Plan       HybridSearchPlan        `json:"plan,omitempty"`
	Stats      HybridSearchStats       `json:"stats,omitempty"`
	Candidates []HybridSearchCandidate `json:"candidates,omitempty"`
	Results    []HybridSearchResult    `json:"results,omitempty"`
}

HybridSearchResponse is returned by SearchHybrid once the executor lands. The current contract stub fails closed and returns no results.

type HybridSearchResult 

type HybridSearchResult struct {
	ID            []byte                     `json:"id"`
	Rank          int                        `json:"rank"`
	FusedScore    float64                    `json:"fused_score"`
	Sources       []HybridSourceContribution `json:"sources,omitempty"`
	Document      []byte                     `json:"document,omitempty"`
	DocumentFound bool                       `json:"document_found,omitempty"`
}

HybridSearchResult is one fused final result. Rank is one-based in the final fused order. FusedScore is higher-is-better. Document is populated only in full result mode (or legacy IncludeDocuments=true) and only after bounded top-k selection.

type HybridSearchSnapshot 

type HybridSearchSnapshot struct {
	Consistency          HybridConsistencyMode `json:"consistency,omitempty"`
	CommitSeq            uint64                `json:"commit_seq,omitempty"`
	SystemRootPageID     uint64                `json:"system_root_page_id,omitempty"`
	CollectionGeneration uint64                `json:"collection_generation,omitempty"`
	TextIndexEpoch       uint64                `json:"text_index_epoch,omitempty"`
	VectorIndexEpoch     uint64                `json:"vector_index_epoch,omitempty"`
}

HybridSearchSnapshot reports the snapshot/epoch identity used by the query. Generation fields are filled when the corresponding source can expose an index/catalog epoch; zero means unavailable or not applicable.

type HybridSearchStats 

type HybridSearchStats struct {
	TextCandidatesRequested        uint64                          `json:"text_candidates_requested,omitempty"`
	TextCandidateBudgetEffective   uint64                          `json:"text_candidate_budget_effective,omitempty"`
	TextCandidatesReturned         uint64                          `json:"text_candidates_returned,omitempty"`
	TextPostingsScanned            uint64                          `json:"text_postings_scanned,omitempty"`
	TextPostingBlocksVisited       uint64                          `json:"text_posting_blocks_visited,omitempty"`
	TextPostingBlocksSkipped       uint64                          `json:"text_posting_blocks_skipped,omitempty"`
	TextBlockMaxFallbacks          uint64                          `json:"text_block_max_fallbacks,omitempty"`
	TextBlockMaxThresholds         uint64                          `json:"text_block_max_thresholds,omitempty"`
	TextWANDPivots                 uint64                          `json:"text_wand_pivots,omitempty"`
	TextScalarPrefilterIDs         uint64                          `json:"text_scalar_prefilter_ids,omitempty"`
	TextScalarPostingBlocksSkipped uint64                          `json:"text_scalar_posting_blocks_skipped,omitempty"`
	TextScalarPostingsRejected     uint64                          `json:"text_scalar_postings_rejected,omitempty"`
	TextCandidatesScored           uint64                          `json:"text_candidates_scored,omitempty"`
	TextStateLookups               uint64                          `json:"text_state_lookups,omitempty"`
	TextNormLookups                uint64                          `json:"text_norm_lookups,omitempty"`
	TextMatchDetailsBuilt          uint64                          `json:"text_match_details_built,omitempty"`
	TextPositionLookups            uint64                          `json:"text_position_lookups,omitempty"`
	TextPhraseCandidatesChecked    uint64                          `json:"text_phrase_candidates_checked,omitempty"`
	TextPhraseCandidatesMatched    uint64                          `json:"text_phrase_candidates_matched,omitempty"`
	VectorCandidatesRequested      uint64                          `json:"vector_candidates_requested,omitempty"`
	VectorCandidateBudgetEffective uint64                          `json:"vector_candidate_budget_effective,omitempty"`
	VectorCandidatesReturned       uint64                          `json:"vector_candidates_returned,omitempty"`
	VectorCandidatesExamined       uint64                          `json:"vector_candidates_examined,omitempty"`
	VectorEdgesVisited             uint64                          `json:"vector_edges_visited,omitempty"`
	ScalarPrefilterIDs             uint64                          `json:"scalar_prefilter_ids,omitempty"`
	ScalarPostfilterChecks         uint64                          `json:"scalar_postfilter_checks,omitempty"`
	ScalarFilterMatched            uint64                          `json:"scalar_filter_matched,omitempty"`
	ScalarFilterRejected           uint64                          `json:"scalar_filter_rejected,omitempty"`
	ScalarFilterSelectivityPPM     uint64                          `json:"scalar_filter_selectivity_ppm,omitempty"`
	CandidatesFused                uint64                          `json:"candidates_fused,omitempty"`
	CandidatesAfterFusion          uint64                          `json:"candidates_after_fusion,omitempty"`
	FusionTextOnly                 uint64                          `json:"fusion_text_only,omitempty"`
	FusionVectorOnly               uint64                          `json:"fusion_vector_only,omitempty"`
	FusionBoth                     uint64                          `json:"fusion_both,omitempty"`
	FusionDuplicateCandidates      uint64                          `json:"fusion_duplicate_candidates,omitempty"`
	CandidatesAfterFilter          uint64                          `json:"candidates_after_filter,omitempty"`
	DocumentsFetched               uint64                          `json:"documents_fetched,omitempty"`
	DocumentsMissing               uint64                          `json:"documents_missing,omitempty"`
	FullDocumentScanFallbacks      uint64                          `json:"full_document_scan_fallbacks,omitempty"`
	Truncated                      uint64                          `json:"truncated,omitempty"`
	CandidateBudgetPolicy          HybridCandidateBudgetPolicy     `json:"candidate_budget_policy,omitempty"`
	CandidateBudgetStopReason      HybridCandidateBudgetStopReason `json:"candidate_budget_stop_reason,omitempty"`
	CandidateBudgetFallbacks       uint64                          `json:"candidate_budget_fallbacks,omitempty"`
	CandidateBudgetFallbackReason  HybridCandidateBudgetStopReason `json:"candidate_budget_fallback_reason,omitempty"`
	CandidateBudgetIterations      uint64                          `json:"candidate_budget_iterations,omitempty"`
	FailClosed                     uint64                          `json:"fail_closed,omitempty"`
	FailClosedReason               HybridFailClosedReason          `json:"fail_closed_reason,omitempty"`
}

HybridSearchStats is the common debug/counter vocabulary for hybrid planning, candidate generation, fusion, scalar filtering, and bounded final fetch.

type HybridSourceContribution 

type HybridSourceContribution struct {
	Source      HybridCandidateSource `json:"source"`
	IndexName   string                `json:"index_name"`
	SourceRank  int                   `json:"source_rank"`
	Score       float64               `json:"score"`
	ScoreKind   HybridScoreKind       `json:"score_kind"`
	FusionScore float64               `json:"fusion_score"`
	TextMatches []HybridTextMatch     `json:"text_matches,omitempty"`
}

HybridSourceContribution records one source's contribution to a final fused result. FusionScore is the normalized contribution (for example one source's RRF term), not the native BM25/BM25F/vector score.

type HybridTextMatch 

type HybridTextMatch struct {
	Field string   `json:"field"`
	Terms []string `json:"terms,omitempty"`
}

HybridTextMatch carries text attribution when the lexical source can provide it. Terms are analyzer-normalized query/index terms where available.

type HybridTextQuery 

type HybridTextQuery struct {
	IndexName      string `json:"index_name"`
	Query          string `json:"query"`
	CandidateLimit int    `json:"candidate_limit,omitempty"`
	// IncludeTextMatches opts into compact field/term attribution on text-source
	// candidates. The default hybrid candidate path is score-only so candidate
	// generation does not allocate match details for non-final candidates.
	IncludeTextMatches bool `json:"include_text_matches,omitempty"`
}

HybridTextQuery configures the lexical candidate source. Query syntax, analyzers, and BM25/BM25F scoring are owned by the text-search tracker; this contract fixes only the candidate budget and source naming consumed by hybrid planning and fusion.

type HybridVectorQuery 

type HybridVectorQuery struct {
	IndexName                 string               `json:"index_name"`
	Query                     []float32            `json:"query"`
	CandidateLimit            int                  `json:"candidate_limit,omitempty"`
	EfSearch                  int                  `json:"ef_search,omitempty"`
	QueryMode                 VectorIndexQueryMode `json:"query_mode,omitempty"`
	QuantizedIndexName        string               `json:"quantized_index_name,omitempty"`
	QuantizedRerankCandidates int                  `json:"quantized_rerank_candidates,omitempty"`
}

HybridVectorQuery configures the vector candidate source. It intentionally carries no document materialization knobs; hybrid document fetch is a bounded final phase after fusion.

type IndexDefinition 

type IndexDefinition struct {
	Name          string            `json:"name"`
	Field         string            `json:"field"`
	ValueType     IndexValueType    `json:"value_type"`
	Unique        bool              `json:"unique,omitempty"`
	MultiKey      bool              `json:"multi_key,omitempty"`
	StoragePolicy RootStoragePolicy `json:"storage_policy,omitempty"`
}

type IndexRangeBound 

type IndexRangeBound struct {
	Value     any
	Inclusive bool
	Unbounded bool
}

type IndexRangeOptions 

type IndexRangeOptions struct {
	Lower IndexRangeBound
	Upper IndexRangeBound
	Limit int
	Desc  bool
}

type IndexValueType 

type IndexValueType string
const (
	IndexValueString IndexValueType = "string"
	IndexValueBool   IndexValueType = "bool"
	IndexValueInt64  IndexValueType = "int64"
	IndexValueDouble IndexValueType = "double"
)

type QuantizedVectorIndexDefinition 

type QuantizedVectorIndexDefinition struct {
	Name                string                     `json:"name"`
	Codec               string                     `json:"codec"`
	Version             uint32                     `json:"version,omitempty"`
	ScalarU8Calibration *ScalarU8CalibrationConfig `json:"scalar_u8_calibration,omitempty"`
}

QuantizedVectorIndexDefinition declares a named derived score plane attached to a column_graph vector index. Query modes must still select these indexes explicitly, and search must fail closed until matching prepared assets are loaded and scored. For scalar_u8, an omitted ScalarU8Calibration preserves the legacy v1 default; calibrated per-granule alpha remains explicit opt-in.

type RootStoragePolicy 

type RootStoragePolicy string
const (
	RootStorageDefault    RootStoragePolicy = ""
	RootStorageFast       RootStoragePolicy = "fast"
	RootStorageCompressed RootStoragePolicy = "compressed"
)

type ScalarU8AlphaPolicy 

type ScalarU8AlphaPolicy struct {
	Name        ScalarU8AlphaPolicyName `json:"name,omitempty"`
	QuantilePPM uint32                  `json:"quantile_ppm,omitempty"`
}

ScalarU8AlphaPolicy is the deterministic policy used to derive alpha values. QuantilePPM is meaningful only for the abs_quantile policy and is intentionally constrained to a finite allowed set.

type ScalarU8AlphaPolicyName 

type ScalarU8AlphaPolicyName string

ScalarU8AlphaPolicyName selects a deterministic finite alpha policy.

type ScalarU8CalibrationConfig 

type ScalarU8CalibrationConfig struct {
	Mode        ScalarU8CalibrationMode     `json:"mode,omitempty"`
	Grouping    ScalarU8CalibrationGrouping `json:"grouping,omitempty"`
	AlphaPolicy ScalarU8AlphaPolicy         `json:"alpha_policy,omitempty"`
}

ScalarU8CalibrationConfig configures scalar_u8 calibration. A nil pointer on QuantizedVectorIndexDefinition preserves the legacy scalar_u8 v1 config and identity. Non-nil configs are normalized and validated with the definition.

func NormalizeScalarU8CalibrationConfig 

func NormalizeScalarU8CalibrationConfig(defName string, index int, q QuantizedVectorIndexDefinition) (*ScalarU8CalibrationConfig, error)

NormalizeScalarU8CalibrationConfig validates and canonicalizes the optional scalar_u8 calibration config on q. Nil preserves the legacy scalar_u8 v1 behavior and empty codec identity; explicit empty/legacy configs normalize to legacy mode so callers that send the field get deterministic metadata back.

type ScalarU8CalibrationGrouping 

type ScalarU8CalibrationGrouping string

ScalarU8CalibrationGrouping names the source of groups used by per-granule alpha calibration. The contract deliberately uses existing storage/layout granules and does not define a vector-specific granule size. 

const (
	ScalarU8CalibrationGroupingStorageLayoutGranule ScalarU8CalibrationGrouping = "storage_layout_granule"
)

type ScalarU8CalibrationMode 

type ScalarU8CalibrationMode string

ScalarU8CalibrationMode selects the scalar_u8 v1 calibration contract. Omitted scalar_u8 calibration config is equivalent to legacy mode for behavior and asset identity. 

const (
	// ScalarU8CalibrationModeLegacy preserves the original scalar_u8 v1 contract:
	// one normalized uint8 code per vector dimension and no alpha side asset.
	ScalarU8CalibrationModeLegacy ScalarU8CalibrationMode = "legacy"
	// ScalarU8CalibrationModePerGranuleAlpha opts into the scalar_u8 v1
	// per-existing-storage-granule scalar alpha contract. Rebuild persists alpha
	// metadata and encodes rows with their granule alpha; search scoring consumes
	// the matching prepared alpha state and fails closed when it is unavailable.
	ScalarU8CalibrationModePerGranuleAlpha ScalarU8CalibrationMode = "per_granule_alpha"
)

type StoredDocumentJSONMaterializer 

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

StoredDocumentJSONMaterializer reuses any resources needed to materialize stored collection documents as JSON.

func (*StoredDocumentJSONMaterializer) Close 

func (m *StoredDocumentJSONMaterializer) Close() error

Close releases resources held by the materializer.

func (*StoredDocumentJSONMaterializer) DocumentFormat 

func (m *StoredDocumentJSONMaterializer) DocumentFormat() DocumentFormat

DocumentFormat returns the collection storage format this materializer was created for.

func (*StoredDocumentJSONMaterializer) StoredDocumentJSON 

func (m *StoredDocumentJSONMaterializer) StoredDocumentJSON(document []byte) ([]byte, error)

StoredDocumentJSON materializes one stored collection document as JSON bytes.

type TemplateV1Encoder 

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

func (*TemplateV1Encoder) EncodeDocument 

func (e *TemplateV1Encoder) EncodeDocument(fields []string, values []any) ([]byte, error)

func (*TemplateV1Encoder) Reset 

func (e *TemplateV1Encoder) Reset()

type TextAnalyzer 

type TextAnalyzer string

TextAnalyzer names a collection text analyzer. The zero value normalizes to TextAnalyzerSimple. 

const (
	TextAnalyzerSimple TextAnalyzer = "simple"
)

type TextAnalyzerOptions 

type TextAnalyzerOptions struct {
	StopWords []string            `json:"stop_words,omitempty"`
	Stemmer   string              `json:"stemmer,omitempty"`
	Synonyms  map[string][]string `json:"synonyms,omitempty"`
}

TextAnalyzerOptions configures the built-in text analyzer in ways that are safe to persist in collection metadata. StopWords are supported for the simple analyzer. Stemmer and Synonyms reserve bounded extension seams and are rejected until their indexing/query expansion semantics are implemented.

type TextIndexBackfillStats 

type TextIndexBackfillStats struct {
	DocumentsScanned int
	StateEntries     int
	PostingEntries   int
	StatsEntries     int
	EncodedBytes     uint64

	V2DocIDEntries    int
	V2DocMapBlocks    int
	V2PostingBlocks   int
	V2NormBlocks      int
	V2PositionEntries int
	V2TermStats       int
	V2FormatRecords   int
	V2StatusRecords   int
	V2NextOrdinal     uint64
	V2RootGeneration  uint64

	V2DocIDBytes        uint64
	V2DocMapBytes       uint64
	V2PostingBlockBytes uint64
	V2NormBlockBytes    uint64
	V2PositionBytes     uint64
	V2TermStatsBytes    uint64
	V2StatusFormatBytes uint64
}

TextIndexBackfillStats reports durable root entries produced by CreateTextIndex.

type TextIndexDefinition 

type TextIndexDefinition struct {
	Name             string               `json:"name"`
	Fields           []TextIndexField     `json:"fields"`
	Analyzer         TextAnalyzer         `json:"analyzer,omitempty"`
	AnalyzerOptions  *TextAnalyzerOptions `json:"analyzer_options,omitempty"`
	Version          TextIndexVersion     `json:"version,omitempty"`
	Rollout          TextIndexRolloutMode `json:"rollout,omitempty"`
	StorePositions   bool                 `json:"store_positions,omitempty"`
	StoreOffsets     bool                 `json:"store_offsets,omitempty"`
	StoragePolicy    RootStoragePolicy    `json:"storage_policy,omitempty"`
	SchemaGeneration uint64               `json:"schema_generation,omitempty"`
}

TextIndexDefinition declares a persistent collection-native inverted index. M2 stores and validates metadata plus versioned postings/text-state/stats storage, M3 maintains these roots on writes, and M4 ranks SearchText results from bounded postings scans.

type TextIndexField 

type TextIndexField struct {
	Field  string  `json:"field"`
	Weight float64 `json:"weight,omitempty"`
}

TextIndexField declares one document field in a text index. Weight defaults to 1.0 when omitted or set to zero.

type TextIndexMaintenanceDebt 

type TextIndexMaintenanceDebt struct {
	Documents               uint64 `json:"documents,omitempty"`
	LiveDocuments           uint64 `json:"live_documents,omitempty"`
	DeletedDocuments        uint64 `json:"deleted_documents,omitempty"`
	DeletedDocumentRatioPPM uint64 `json:"deleted_document_ratio_ppm,omitempty"`
	PostingBlocks           uint64 `json:"posting_blocks,omitempty"`
	SealedPostingBlocks     uint64 `json:"sealed_posting_blocks,omitempty"`
	MicroPostingBlocks      uint64 `json:"micro_posting_blocks,omitempty"`
	DeltaPostingBlocks      uint64 `json:"delta_posting_blocks,omitempty"`
	PostingsRead            uint64 `json:"postings_read,omitempty"`
	StalePostings           uint64 `json:"stale_postings,omitempty"`
	StalePostingRatioPPM    uint64 `json:"stale_posting_ratio_ppm,omitempty"`
	TermsScanned            uint64 `json:"terms_scanned,omitempty"`
	TermsRewritten          uint64 `json:"terms_rewritten,omitempty"`
	PostingBlocksRead       uint64 `json:"posting_blocks_read,omitempty"`
	PostingBlocksBefore     uint64 `json:"posting_blocks_before,omitempty"`
	PostingBlocksAfter      uint64 `json:"posting_blocks_after,omitempty"`
	PostingBlocksWritten    uint64 `json:"posting_blocks_written,omitempty"`
	PostingBlocksDeleted    uint64 `json:"posting_blocks_deleted,omitempty"`
	RewritePostingBlocks    uint64 `json:"rewrite_posting_blocks,omitempty"`
	TombstoneDocIDEntries   uint64 `json:"tombstone_docid_entries,omitempty"`
	TombstoneDocMapEntries  uint64 `json:"tombstone_docmap_entries,omitempty"`
	TombstoneNormEntries    uint64 `json:"tombstone_norm_entries,omitempty"`
	RewriteMergeState       string `json:"rewrite_merge_state,omitempty"`
	PhysicalReclamationPath string `json:"physical_reclamation_path,omitempty"`
}

TextIndexMaintenanceDebt reports logical rewrite debt observed while planning text-v2 maintenance.

type TextIndexMaintenanceIndexStats 

type TextIndexMaintenanceIndexStats struct {
	IndexName             string                   `json:"index_name"`
	Version               TextIndexVersion         `json:"version"`
	Triggered             bool                     `json:"triggered,omitempty"`
	TriggerReason         string                   `json:"trigger_reason,omitempty"`
	Applied               bool                     `json:"applied,omitempty"`
	Noop                  bool                     `json:"noop,omitempty"`
	DryRun                bool                     `json:"dry_run,omitempty"`
	SkippedReason         string                   `json:"skipped_reason,omitempty"`
	BudgetExhausted       bool                     `json:"budget_exhausted,omitempty"`
	BudgetExhaustedReason string                   `json:"budget_exhausted_reason,omitempty"`
	StorageBefore         TextIndexStorageStats    `json:"storage_before"`
	StorageAfter          TextIndexStorageStats    `json:"storage_after,omitempty"`
	Debt                  TextIndexMaintenanceDebt `json:"debt"`
	Rewrite               TextIndexRewriteStats    `json:"rewrite"`
}

TextIndexMaintenanceIndexStats is the per-index operator/test report for one maintenance decision.

type TextIndexMaintenanceManagerStats 

type TextIndexMaintenanceManagerStats struct {
	PhysicalReclamationPath string                      `json:"physical_reclamation_path,omitempty"`
	CollectionsScanned      uint64                      `json:"collections_scanned,omitempty"`
	IndexesScanned          uint64                      `json:"indexes_scanned,omitempty"`
	IndexesTriggered        uint64                      `json:"indexes_triggered,omitempty"`
	IndexesRewritten        uint64                      `json:"indexes_rewritten,omitempty"`
	IndexesSkipped          uint64                      `json:"indexes_skipped,omitempty"`
	BudgetExhausted         bool                        `json:"budget_exhausted,omitempty"`
	BudgetExhaustedReason   string                      `json:"budget_exhausted_reason,omitempty"`
	StorageCompacted        bool                        `json:"storage_compacted,omitempty"`
	StorageCompaction       *CompactStorageStats        `json:"storage_compaction,omitempty"`
	Collections             []TextIndexMaintenanceStats `json:"collections,omitempty"`
}

TextIndexMaintenanceManagerStats aggregates explicit policy maintenance across all collections known to a CollectionManager.

type TextIndexMaintenanceOptions 

type TextIndexMaintenanceOptions struct {
	Policy TextIndexMaintenancePolicy `json:"policy,omitempty"`

	TargetPostingsPerBlock uint32        `json:"target_postings_per_block,omitempty"`
	Force                  bool          `json:"force,omitempty"`
	DisableTombstonePurge  bool          `json:"disable_tombstone_purge,omitempty"`
	DryRun                 bool          `json:"dry_run,omitempty"`
	MaxTerms               uint64        `json:"max_terms,omitempty"`
	MaxPostingBlocks       uint64        `json:"max_posting_blocks,omitempty"`
	MaxPostings            uint64        `json:"max_postings,omitempty"`
	MaxDuration            time.Duration `json:"max_duration,omitempty"`
	MaxIndexes             int           `json:"max_indexes,omitempty"`

	RunStorageCompaction     bool                  `json:"run_storage_compaction,omitempty"`
	StorageCompactionOptions CompactStorageOptions `json:"storage_compaction_options,omitempty"`
}

TextIndexMaintenanceOptions controls bounded explicit text-v2 maintenance. It only publishes normal ordered-root mutations. Physical reclamation remains in TreeDB's normal maintenance path and is run only when RunStorageCompaction is set.

type TextIndexMaintenancePolicy 

type TextIndexMaintenancePolicy struct {
	MinDeletedDocuments        uint64 `json:"min_deleted_documents,omitempty"`
	MinDeletedDocumentRatioPPM uint32 `json:"min_deleted_document_ratio_ppm,omitempty"`
	MinMicroPostingBlocks      uint64 `json:"min_micro_posting_blocks,omitempty"`
	MinDeltaPostingBlocks      uint64 `json:"min_delta_posting_blocks,omitempty"`
	MinStalePostings           uint64 `json:"min_stale_postings,omitempty"`
	MinStalePostingRatioPPM    uint32 `json:"min_stale_posting_ratio_ppm,omitempty"`
	MinRewritePostingBlocks    uint64 `json:"min_rewrite_posting_blocks,omitempty"`
}

TextIndexMaintenancePolicy defines when explicit text-v2 maintenance should apply a logical rewrite. Zero-valued policies are normalized to conservative production defaults; set one or more fields to opt into a test/operator policy with only those thresholds enabled.

func DefaultTextIndexMaintenancePolicy 

func DefaultTextIndexMaintenancePolicy() TextIndexMaintenancePolicy

DefaultTextIndexMaintenancePolicy returns conservative text-v2 rewrite thresholds. They avoid surprise foreground work for small indexes while still giving operators a deterministic automatic policy for explicit maintenance.

type TextIndexMaintenanceStats 

type TextIndexMaintenanceStats struct {
	CollectionName          string                           `json:"collection_name,omitempty"`
	PhysicalReclamationPath string                           `json:"physical_reclamation_path,omitempty"`
	IndexesScanned          uint64                           `json:"indexes_scanned,omitempty"`
	IndexesTriggered        uint64                           `json:"indexes_triggered,omitempty"`
	IndexesRewritten        uint64                           `json:"indexes_rewritten,omitempty"`
	IndexesSkipped          uint64                           `json:"indexes_skipped,omitempty"`
	BudgetExhausted         bool                             `json:"budget_exhausted,omitempty"`
	BudgetExhaustedReason   string                           `json:"budget_exhausted_reason,omitempty"`
	StorageCompacted        bool                             `json:"storage_compacted,omitempty"`
	StorageCompaction       *CompactStorageStats             `json:"storage_compaction,omitempty"`
	Indexes                 []TextIndexMaintenanceIndexStats `json:"indexes,omitempty"`
}

TextIndexMaintenanceStats reports one explicit maintenance run. The storage compaction fields are populated only when RunStorageCompaction is enabled.

type TextIndexRewriteOptions 

type TextIndexRewriteOptions struct {
	// TargetPostingsPerBlock controls the sealed block size produced by the
	// rewrite. Zero uses the text-v2 production default.
	TargetPostingsPerBlock uint32
	// Force rewrites every term even if no stale/micro/delta blocks are observed.
	Force bool
	// DisableTombstonePurge keeps deleted docID/docmap/norm tombstones after
	// stale posting blocks are removed. The default purges tombstones.
	DisableTombstonePurge bool
	// MaxTerms bounds how many posting terms may be planned. Zero is unlimited.
	// If the bound is exhausted, no rewrite is published and stats report the
	// exhausted budget reason.
	MaxTerms uint64
	// MaxPostingBlocks bounds posting blocks read while planning. Zero is
	// unlimited. The bound is checked at term boundaries so one term is the
	// accounting unit.
	MaxPostingBlocks uint64
	// MaxPostings bounds posting entries read while planning. Zero is unlimited.
	// The bound is checked at term boundaries so one term is the accounting unit.
	MaxPostings uint64
	// MaxDuration bounds wall-clock planning time. Zero is unlimited. The bound is
	// checked during storage-stat inspection, term-stat planning, posting-block
	// scanning, and term rewrites; exhaustion leaves storage unchanged.
	MaxDuration time.Duration
}

TextIndexRewriteOptions controls logical text-v2 rewrite/merge maintenance. The rewrite is a normal ordered-root mutation: it publishes replacement posting-block, term-stat, tombstone, and status records through collection roots. Physical reclamation remains owned by TreeDB ValueLogGC, value-log rewrite, leaf generation maintenance, index vacuum, and CompactStorage.

type TextIndexRewriteStats 

type TextIndexRewriteStats struct {
	IndexName string           `json:"index_name"`
	Version   TextIndexVersion `json:"version"`

	RootGenerationBefore uint64 `json:"root_generation_before"`
	RootGenerationAfter  uint64 `json:"root_generation_after"`
	Noop                 bool   `json:"noop"`

	TermsScanned   uint64 `json:"terms_scanned"`
	TermsRewritten uint64 `json:"terms_rewritten"`
	TermsPurged    uint64 `json:"terms_purged"`

	PostingBlocksRead    uint64 `json:"posting_blocks_read"`
	PostingBlocksWritten uint64 `json:"posting_blocks_written"`
	PostingBlocksDeleted uint64 `json:"posting_blocks_deleted"`
	PostingsRead         uint64 `json:"postings_read"`
	LivePostingsRetained uint64 `json:"live_postings_retained"`
	StalePostingsPurged  uint64 `json:"stale_postings_purged"`

	TombstoneDocIDEntriesPurged  uint64 `json:"tombstone_docid_entries_purged"`
	TombstoneDocMapEntriesPurged uint64 `json:"tombstone_docmap_entries_purged"`
	TombstoneNormEntriesPurged   uint64 `json:"tombstone_norm_entries_purged"`

	PostingBlocksBefore uint64 `json:"posting_blocks_before"`
	PostingBlocksAfter  uint64 `json:"posting_blocks_after"`

	BudgetExhausted       bool   `json:"budget_exhausted,omitempty"`
	BudgetExhaustedReason string `json:"budget_exhausted_reason,omitempty"`
}

TextIndexRewriteStats reports logical text-v2 rewrite/merge maintenance work.

type TextIndexRolloutMode 

type TextIndexRolloutMode string

TextIndexRolloutMode describes how a text index participates in reads/writes during v1/v2 coexistence. The zero value normalizes to primary. Non-primary modes are reserved for the text v2 rollout and fail closed until the corresponding dual-write/shadow-read implementation lands. 

const (
	TextIndexRolloutDefault   TextIndexRolloutMode = ""
	TextIndexRolloutPrimary   TextIndexRolloutMode = "primary"
	TextIndexRolloutShadow    TextIndexRolloutMode = "shadow"
	TextIndexRolloutDualWrite TextIndexRolloutMode = "dual_write"
	TextIndexRolloutDisabled  TextIndexRolloutMode = "disabled"
)

type TextIndexStatus 

type TextIndexStatus struct {
	Name                    string               `json:"name"`
	Version                 TextIndexVersion     `json:"version"`
	Rollout                 TextIndexRolloutMode `json:"rollout"`
	Ready                   bool                 `json:"ready"`
	Readable                bool                 `json:"readable"`
	Writable                bool                 `json:"writable"`
	FailClosed              bool                 `json:"fail_closed,omitempty"`
	FailClosedReason        string               `json:"fail_closed_reason,omitempty"`
	ActiveRootNames         []string             `json:"active_root_names,omitempty"`
	ReservedV2RootNames     []string             `json:"reserved_v2_root_names,omitempty"`
	RequiredCounterNames    []string             `json:"required_counter_names,omitempty"`
	RewriteMergeState       string               `json:"rewrite_merge_state,omitempty"`
	PhysicalReclamationPath string               `json:"physical_reclamation_path,omitempty"`
}

TextIndexStatus reports the currently supported text-index contract for one declared index. It is intentionally low-cardinality so callers and benchmark harnesses can fail closed when a requested version or rollout mode is not active.

type TextIndexStorageStats 

type TextIndexStorageStats struct {
	Documents      uint64
	StateEntries   uint64
	PostingEntries uint64
	StatsEntries   uint64
	EncodedBytes   uint64

	Version               TextIndexVersion
	V2DocIDEntries        uint64
	V2DocMapBlocks        uint64
	V2PostingBlocks       uint64
	V2NormBlocks          uint64
	V2PositionEntries     uint64
	V2TermStats           uint64
	V2FormatRecords       uint64
	V2StatusRecords       uint64
	V2NextOrdinal         uint64
	V2LiveDocuments       uint64
	V2DeletedDocs         uint64
	V2RootGeneration      uint64
	V2StatsGeneration     uint64
	V2SealedPostingBlocks uint64
	V2DeltaPostingBlocks  uint64
	V2MicroPostingBlocks  uint64
	V2RewriteMergeState   string

	V2DocIDBytes        uint64
	V2DocMapBytes       uint64
	V2PostingBlockBytes uint64
	V2NormBlockBytes    uint64
	V2PositionBytes     uint64
	V2TermStatsBytes    uint64
	V2StatusFormatBytes uint64
}

TextIndexStorageStats reports durable text-root contents after validation.

type TextIndexVersion 

type TextIndexVersion string

TextIndexVersion selects the physical text-index contract. For new text index declarations, the zero value normalizes to TextIndexVersionV2. Existing persisted v1 metadata remains v1, and callers that need the legacy root format can still set TextIndexVersionV1 explicitly. Unsupported versions fail closed rather than silently falling back to another format. 

const (
	TextIndexVersionDefault TextIndexVersion = ""
	TextIndexVersionV1      TextIndexVersion = "v1"
	TextIndexVersionV2      TextIndexVersion = "v2"
)

type TextSearchExplain 

type TextSearchExplain struct {
	Enabled            bool                      `json:"enabled"`
	CollectionName     string                    `json:"collection_name,omitempty"`
	IndexName          string                    `json:"index_name,omitempty"`
	IndexVersion       TextIndexVersion          `json:"index_version,omitempty"`
	Query              string                    `json:"query,omitempty"`
	Operator           TextSearchOperator        `json:"operator,omitempty"`
	Phrase             *TextSearchExplainPhrase  `json:"phrase,omitempty"`
	TopK               int                       `json:"top_k,omitempty"`
	CandidateLimit     int                       `json:"candidate_limit,omitempty"`
	MaxPostingsScanned int                       `json:"max_postings_scanned,omitempty"`
	ResultMode         TextSearchResultMode      `json:"result_mode,omitempty"`
	Terms              []TextSearchExplainTerm   `json:"terms,omitempty"`
	Fields             []TextSearchExplainField  `json:"fields,omitempty"`
	Snapshot           TextSearchExplainSnapshot `json:"snapshot,omitempty"`
	Serving            TextSearchExplainServing  `json:"serving,omitempty"`
	Counters           TextSearchExplainCounters `json:"counters,omitempty"`
	Results            []TextSearchExplainResult `json:"results,omitempty"`
	FailClosedReason   string                    `json:"fail_closed_reason,omitempty"`
	FallbackReasons    []string                  `json:"fallback_reasons,omitempty"`
}

TextSearchExplain is an opt-in diagnostic payload for SearchText. It is nil unless TextSearchOptions.Explain is true. The payload describes the analyzed query, text-v2 root/status snapshot, execution path, pruning counters, and BM25F score components for returned results.

type TextSearchExplainCounters 

type TextSearchExplainCounters struct {
	PostingsScanned            uint64 `json:"postings_scanned,omitempty"`
	CandidatesScored           uint64 `json:"candidates_scored,omitempty"`
	CandidatesReturned         uint64 `json:"candidates_returned,omitempty"`
	PostingBlocksVisited       uint64 `json:"posting_blocks_visited,omitempty"`
	PostingBlocksSkipped       uint64 `json:"posting_blocks_skipped,omitempty"`
	BlockMaxFallbacks          uint64 `json:"block_max_fallbacks,omitempty"`
	BlockMaxThresholds         uint64 `json:"block_max_thresholds,omitempty"`
	WANDPivots                 uint64 `json:"wand_pivots,omitempty"`
	ScalarPrefilterIDs         uint64 `json:"scalar_prefilter_ids,omitempty"`
	ScalarPostingBlocksSkipped uint64 `json:"scalar_posting_blocks_skipped,omitempty"`
	ScalarPostingsRejected     uint64 `json:"scalar_postings_rejected,omitempty"`
	NormLookups                uint64 `json:"norm_lookups,omitempty"`
	MatchDetailsBuilt          uint64 `json:"match_details_built,omitempty"`
	PositionLookups            uint64 `json:"position_lookups,omitempty"`
	PhraseCandidatesChecked    uint64 `json:"phrase_candidates_checked,omitempty"`
	PhraseCandidatesMatched    uint64 `json:"phrase_candidates_matched,omitempty"`
	DocumentsFetched           uint64 `json:"documents_fetched,omitempty"`
	FullDocumentScanFallbacks  uint64 `json:"full_document_scan_fallbacks,omitempty"`
	FailClosed                 uint64 `json:"fail_closed,omitempty"`
}

TextSearchExplainCounters mirrors the hot text counters at the end of the query so an explain payload can be copied into runbooks without separately formatting TextSearchResponse.Stats.

type TextSearchExplainField 

type TextSearchExplainField struct {
	Field           string  `json:"field"`
	Weight          float64 `json:"weight"`
	DocumentCount   uint64  `json:"document_count"`
	TotalTokenCount uint64  `json:"total_token_count"`
	AverageLength   float64 `json:"average_length,omitempty"`
	StatsGeneration uint64  `json:"stats_generation,omitempty"`
}

TextSearchExplainField reports field weights and corpus accounting used by BM25F length normalization.

type TextSearchExplainPhrase 

type TextSearchExplainPhrase struct {
	Query string   `json:"query,omitempty"`
	Terms []string `json:"terms,omitempty"`
	Gaps  []int    `json:"gaps,omitempty"`
	Slop  int      `json:"slop,omitempty"`
}

TextSearchExplainPhrase reports bounded structured phrase/proximity options after analysis. Gaps are analyzer-position gaps between adjacent phrase terms.

type TextSearchExplainPhraseStats 

type TextSearchExplainPhraseStats struct {
	PositionLookups   uint64 `json:"position_lookups,omitempty"`
	CandidatesChecked uint64 `json:"candidates_checked,omitempty"`
	CandidatesMatched uint64 `json:"candidates_matched,omitempty"`
}

TextSearchExplainPhraseStats reports phrase position validation work.

type TextSearchExplainResult 

type TextSearchExplainResult struct {
	DocumentID []byte                       `json:"document_id"`
	Rank       int                          `json:"rank"`
	Ordinal    uint64                       `json:"ordinal,omitempty"`
	Generation uint64                       `json:"generation,omitempty"`
	Score      float64                      `json:"score"`
	Terms      []TextSearchExplainScoreTerm `json:"terms,omitempty"`
}

TextSearchExplainResult reports BM25F score decomposition for one returned result. Components are populated only for returned top-K results.

type TextSearchExplainScalar 

type TextSearchExplainScalar struct {
	Enabled              bool   `json:"enabled,omitempty"`
	AllowSetSize         uint64 `json:"allow_set_size,omitempty"`
	PostingBlocksSkipped uint64 `json:"posting_blocks_skipped,omitempty"`
	PostingsRejected     uint64 `json:"postings_rejected,omitempty"`
}

TextSearchExplainScalar reports scalar allow-set pruning when text-v2 search is invoked from hybrid text+scalar serving.

type TextSearchExplainScoreField 

type TextSearchExplainScoreField struct {
	Field         string  `json:"field"`
	Weight        float64 `json:"weight"`
	TermFrequency uint32  `json:"term_frequency"`
	FieldLength   uint32  `json:"field_length"`
	AverageLength float64 `json:"average_length"`
	NormalizedTF  float64 `json:"normalized_tf"`
	WeightedTF    float64 `json:"weighted_tf"`
}

TextSearchExplainScoreField reports one field lane's contribution to a term's BM25F combined term frequency.

type TextSearchExplainScoreTerm 

type TextSearchExplainScoreTerm struct {
	Term              string                        `json:"term"`
	DocumentFrequency uint64                        `json:"document_frequency"`
	IDF               float64                       `json:"idf"`
	CombinedTF        float64                       `json:"combined_tf"`
	Score             float64                       `json:"score"`
	Fields            []TextSearchExplainScoreField `json:"fields,omitempty"`
}

TextSearchExplainScoreTerm reports one term's contribution to a returned result's BM25F score.

type TextSearchExplainServing 

type TextSearchExplainServing struct {
	Path                 TextSearchExplainServingPath `json:"path,omitempty"`
	BM25K1               float64                      `json:"bm25_k1,omitempty"`
	BM25B                float64                      `json:"bm25_b,omitempty"`
	BlockMaxEnabled      bool                         `json:"block_max_enabled,omitempty"`
	PostingBlocksVisited uint64                       `json:"posting_blocks_visited,omitempty"`
	PostingBlocksSkipped uint64                       `json:"posting_blocks_skipped,omitempty"`
	BlockMaxFallbacks    uint64                       `json:"block_max_fallbacks,omitempty"`
	BlockMaxThresholds   uint64                       `json:"block_max_thresholds,omitempty"`
	WANDPivots           uint64                       `json:"wand_pivots,omitempty"`
	ScalarPruning        TextSearchExplainScalar      `json:"scalar_pruning,omitempty"`
	PhraseValidation     TextSearchExplainPhraseStats `json:"phrase_validation,omitempty"`
	FailClosedReason     string                       `json:"fail_closed_reason,omitempty"`
	FallbackReasons      []string                     `json:"fallback_reasons,omitempty"`
}

TextSearchExplainServing reports the selected serving path and the main low-cardinality decisions/counters that explain why work was visited, skipped, pruned, or failed closed.

type TextSearchExplainServingPath 

type TextSearchExplainServingPath string

TextSearchExplainServingPath identifies the text-v2 execution path chosen for a query explain. Values are intentionally low-cardinality so they can be used in docs, tests, and operational dashboards. 

const (
	TextSearchExplainPathUnset          TextSearchExplainServingPath = ""
	TextSearchExplainPathV1Postings     TextSearchExplainServingPath = "v1_postings"
	TextSearchExplainPathExactPostings  TextSearchExplainServingPath = "exact_postings_scan"
	TextSearchExplainPathBlockMaxSingle TextSearchExplainServingPath = "blockmax_single_term"
	TextSearchExplainPathBlockMaxAND    TextSearchExplainServingPath = "blockmax_and"
	TextSearchExplainPathBlockMaxORWAND TextSearchExplainServingPath = "blockmax_or_wand"
	TextSearchExplainPathPhrase         TextSearchExplainServingPath = "phrase_validation"
	TextSearchExplainPathFailClosed     TextSearchExplainServingPath = "fail_closed"
)

type TextSearchExplainSnapshot 

type TextSearchExplainSnapshot struct {
	FormatVersion    uint32   `json:"format_version,omitempty"`
	RootGeneration   uint64   `json:"root_generation,omitempty"`
	StatsGeneration  uint64   `json:"stats_generation,omitempty"`
	DocMapGeneration uint64   `json:"doc_map_generation,omitempty"`
	NormGeneration   uint64   `json:"norm_generation,omitempty"`
	TermGeneration   uint64   `json:"term_generation,omitempty"`
	NextOrdinal      uint64   `json:"next_ordinal,omitempty"`
	LiveDocuments    uint64   `json:"live_documents,omitempty"`
	DeletedDocuments uint64   `json:"deleted_documents,omitempty"`
	CorpusDocuments  uint64   `json:"corpus_documents,omitempty"`
	ActiveRootNames  []string `json:"active_root_names,omitempty"`
}

TextSearchExplainSnapshot identifies the root/status snapshot that served the query. It lets reopen/snapshot diagnostics prove which text-v2 generation was consulted without scanning the full index.

type TextSearchExplainTerm 

type TextSearchExplainTerm struct {
	Term               string `json:"term"`
	DocumentFrequency  uint64 `json:"document_frequency"`
	TotalTermFrequency uint64 `json:"total_term_frequency"`
	PostingBlockCount  uint64 `json:"posting_block_count"`
	StatsGeneration    uint64 `json:"stats_generation,omitempty"`
}

TextSearchExplainTerm reports per-term collection statistics used by BM25F.

type TextSearchMatch 

type TextSearchMatch struct {
	Field string
	Terms []string
}

TextSearchMatch carries matched field/term attribution for a lexical result.

type TextSearchOperator 

type TextSearchOperator string

TextSearchOperator controls how analyzed query terms are combined. The zero value normalizes to OR. 

const (
	TextSearchOperatorOR  TextSearchOperator = "or"
	TextSearchOperatorAND TextSearchOperator = "and"
)

type TextSearchOptions 

type TextSearchOptions struct {
	IndexName string
	Query     string
	// Phrase is a structured phrase/proximity query. It is intentionally separate
	// from Query to avoid introducing a broad text query DSL.
	Phrase   *TextSearchPhraseQuery
	Operator TextSearchOperator
	TopK     int
	// ResultMode controls optional match-detail materialization. The zero value
	// is detailed for API compatibility. Score-only returns IDs/ranks/scores
	// without match summaries; compact returns TextMatches only; detailed returns
	// TextMatches plus legacy MatchedTerms/MatchedFields. Document fetching remains
	// controlled solely by IncludeDocuments.
	ResultMode TextSearchResultMode
	// CandidateLimit bounds the number of unique document candidates generated
	// from postings before scoring. The zero value uses an implementation default
	// derived from TopK. When the limit is exceeded, SearchText fails closed rather
	// than returning silently incomplete rankings.
	CandidateLimit int
	// MaxPostingsScanned bounds postings range-scan work. The zero value uses an
	// implementation default. When the limit is exceeded, SearchText fails closed.
	MaxPostingsScanned   int
	IncludeDocuments     bool
	DocumentFetchOptions DocumentFetchOptions

	// Explain opts into a diagnostic payload that describes analyzed terms,
	// text-v2 root/status snapshot, serving path, pruning counters, phrase
	// validation, fail-closed reasons, and BM25F score components for returned
	// results. The zero value keeps explain disabled and avoids mandatory extra
	// allocations on the normal search path.
	Explain bool
	// contains filtered or unexported fields
}

TextSearchOptions configures collection-native lexical search.

type TextSearchPhraseQuery 

type TextSearchPhraseQuery struct {
	Query string
	Slop  int
}

TextSearchPhraseQuery requests bounded ordered phrase/proximity semantics over text-v2 position lanes. Matching uses analyzed token positions, so stopword-filtered tokens still contribute expected gaps. Slop is the maximum total number of extra intervening tokens allowed beyond those expected gaps; zero means exact analyzed positions.

type TextSearchResponse 

type TextSearchResponse struct {
	IndexName string
	Results   []TextSearchResult
	Stats     TextSearchStats
	Explain   *TextSearchExplain
}

TextSearchResponse contains ranked text results and diagnostics.

type TextSearchResult 

type TextSearchResult struct {
	DocumentID    []byte
	IndexName     string
	Rank          int
	Score         float64
	ScoreKind     HybridScoreKind
	MatchedTerms  []string
	MatchedFields []string
	TextMatches   []TextSearchMatch
	Document      []byte
}

TextSearchResult is one ranked lexical result. Rank is one-based in descending BM25F score order and DocumentID is response-owned.

type TextSearchResultMode 

type TextSearchResultMode string

TextSearchResultMode controls how much lexical match attribution is materialized for returned results. The zero value keeps the historical SearchText behavior: detailed field/term summaries for final top-K results. 

const (
	TextSearchResultModeDefault   TextSearchResultMode = ""
	TextSearchResultModeDetailed  TextSearchResultMode = "detailed"
	TextSearchResultModeCompact   TextSearchResultMode = "compact"
	TextSearchResultModeScoreOnly TextSearchResultMode = "score_only"
)

type TextSearchStats 

type TextSearchStats struct {
	QueryTerms                     int
	TextCandidatesRequested        uint64
	TextCandidatesReturned         uint64
	TextPostingsScanned            uint64
	TextPostingBlocksVisited       uint64
	TextPostingBlocksSkipped       uint64
	TextBlockMaxFallbacks          uint64
	TextBlockMaxThresholds         uint64
	TextWANDPivots                 uint64
	TextScalarPrefilterIDs         uint64
	TextScalarPostingBlocksSkipped uint64
	TextScalarPostingsRejected     uint64
	TextCandidatesScored           uint64
	TextStateLookups               uint64
	TextNormLookups                uint64
	TextMatchDetailsBuilt          uint64
	TextPositionLookups            uint64
	TextPhraseCandidatesChecked    uint64
	TextPhraseCandidatesMatched    uint64
	PostingsScanned                uint64
	CandidatesScored               uint64
	DocumentsFetched               uint64
	DocumentsMissing               uint64
	FullDocumentScanFallbacks      uint64
	PostingsScanNanos              uint64
	CandidateScoreNanos            uint64
	DocumentFetchNanos             uint64
	Truncated                      bool
	FailClosed                     uint64
	FailClosedReason               string
	Unavailable                    bool
	UnavailableReason              string
}

TextSearchStats reports text-only search work. The Text* candidate counters intentionally mirror the hybrid-search counter vocabulary so #2503 can adapt text-only results without inventing new counter names. The shorter aliases are retained for text-only callers.

type TextToken 

type TextToken struct {
	Term        string
	Position    int
	StartOffset int
	EndOffset   int
}

TextToken is one analyzed token. Position is zero-based token order; offsets are byte offsets in the source string.

func AnalyzeText 

func AnalyzeText(analyzer TextAnalyzer, text string) ([]TextToken, error)

AnalyzeText runs a named collection text analyzer over text. The simple analyzer lowercases Unicode letters and treats Unicode letters, Unicode digits, and '_' as token characters so code-ish identifiers such as "HTTP_500" remain searchable without stemming.

func AnalyzeTextWithOptions 

func AnalyzeTextWithOptions(analyzer TextAnalyzer, options *TextAnalyzerOptions, text string) ([]TextToken, error)

AnalyzeTextWithOptions runs a named collection text analyzer with persisted analyzer options. It is intended for callers that need the same token stream used by text-index write and search paths.

type TextTokenSink 

type TextTokenSink interface {
	AddTextToken(TextToken) error
}

TextTokenSink receives analyzed tokens from AnalyzeTextToSink. Implementations must not retain mutable scratch owned by the analyzer; TextToken values are self-contained.

type TextTokenSinkFunc 

type TextTokenSinkFunc func(TextToken) error

TextTokenSinkFunc adapts a function to TextTokenSink.

func (TextTokenSinkFunc) AddTextToken 

func (f TextTokenSinkFunc) AddTextToken(token TextToken) error

type TypedColumnBoolPredicateAggregateRequest 

type TypedColumnBoolPredicateAggregateRequest struct {
	Column                   string
	Kind                     TypedColumnBoolPredicateScanKind
	Value                    bool
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

type TypedColumnBoolPredicateAggregateResult 

type TypedColumnBoolPredicateAggregateResult struct {
	Rows        int64
	NonNulls    int64
	TrueCount   int64
	FalseCount  int64
	Diagnostics TypedColumnInt64PredicateScanDiagnostics
}

type TypedColumnBoolPredicateAggregateSession 

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

func (*TypedColumnBoolPredicateAggregateSession) Close 

func (s *TypedColumnBoolPredicateAggregateSession) Close() error

func (*TypedColumnBoolPredicateAggregateSession) Diagnostics 

func (s *TypedColumnBoolPredicateAggregateSession) Diagnostics() TypedColumnBoolPredicateAggregateSessionDiagnostics

func (*TypedColumnBoolPredicateAggregateSession) Run 

func (s *TypedColumnBoolPredicateAggregateSession) Run() (TypedColumnBoolPredicateAggregateResult, error)

type TypedColumnBoolPredicateAggregateSessionDiagnostics 

type TypedColumnBoolPredicateAggregateSessionDiagnostics = TypedColumnInt64PredicateAggregateSessionDiagnostics

type TypedColumnBoolPredicateScanKind 

type TypedColumnBoolPredicateScanKind string
const (
	TypedColumnBoolPredicateAll   TypedColumnBoolPredicateScanKind = "all"
	TypedColumnBoolPredicateEqual TypedColumnBoolPredicateScanKind = "equal"
	TypedColumnBoolPredicateRange TypedColumnBoolPredicateScanKind = "range"
)

type TypedColumnInt64AggregateExpression 

type TypedColumnInt64AggregateExpression string
const (
	TypedColumnInt64AggregateIdentity          TypedColumnInt64AggregateExpression = "identity"
	TypedColumnInt64AggregateSecondOfDaySquare TypedColumnInt64AggregateExpression = "second_of_day_square"
)

type TypedColumnInt64PredicateAggregateRequest 

type TypedColumnInt64PredicateAggregateRequest struct {
	Column                   string
	Kind                     TypedColumnInt64PredicateScanKind
	Value                    int64
	Low                      int64
	High                     int64
	Expression               TypedColumnInt64AggregateExpression
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

type TypedColumnInt64PredicateAggregateResult 

type TypedColumnInt64PredicateAggregateResult struct {
	Count       int64
	Sum         int64
	Avg         float64
	Diagnostics TypedColumnInt64PredicateScanDiagnostics
}

type TypedColumnInt64PredicateAggregateSession 

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

TypedColumnInt64PredicateAggregateSession owns an explicit prepared lifetime for repeated typed-column int64 predicate aggregate scans over one immutable snapshot. It keeps the column physical asset read cache and mappedresource handles alive between Run calls, and releases them on Close.

A session is not safe for concurrent Run and Close calls; callers that share a session between goroutines must provide external synchronization.

func (*TypedColumnInt64PredicateAggregateSession) Close 

func (s *TypedColumnInt64PredicateAggregateSession) Close() error

Close releases mapped asset handles and the pinned snapshot owned by the prepared aggregate session. It is safe to call multiple times.

func (*TypedColumnInt64PredicateAggregateSession) Diagnostics 

func (s *TypedColumnInt64PredicateAggregateSession) Diagnostics() TypedColumnInt64PredicateAggregateSessionDiagnostics

Diagnostics returns current scoped resource state for the prepared session.

func (*TypedColumnInt64PredicateAggregateSession) Run 

func (s *TypedColumnInt64PredicateAggregateSession) Run() (TypedColumnInt64PredicateAggregateResult, error)

Run executes one hot aggregate scan against the prepared snapshot. Setup and warmup work done before Run is not included in the returned ScanNanos.

type TypedColumnInt64PredicateAggregateSessionDiagnostics 

type TypedColumnInt64PredicateAggregateSessionDiagnostics struct {
	Closed                   bool
	ColumnAssetReadIntegrity string
	SegmentFileCacheHits     uint64
	SegmentFileCacheMisses   uint64
	ActiveResourceHandles    int64
	ActiveMappedBytes        int64
	ActiveHeapCopyBytes      int64
	TotalResourceAcquires    uint64
	TotalResourceReleases    uint64
	TotalMappedBytes         uint64
	TotalHeapCopyBytes       uint64
	FallbackReads            uint64
}

TypedColumnInt64PredicateAggregateSessionDiagnostics reports scoped resource state for a prepared aggregate session without exposing internal resource manager types in the public API.

type TypedColumnInt64PredicateScanDiagnostics 

type TypedColumnInt64PredicateScanDiagnostics struct {
	ManifestRoot               uint64
	ManifestGeneration         uint64
	RecoveryManifestGeneration uint64
	AppliedCommandLSN          uint64
	ManifestRecords            int
	AssetRefs                  int
	MutationParts              int

	RowsScanned int
	RowsMatched int

	PartsConsidered  int
	PartsPruned      int
	PartsDecoded     int
	BlocksConsidered int
	BlocksPruned     int
	BlocksDecoded    int

	SelectionEmptyBlocks  int
	SelectionAllBlocks    int
	SelectionRangeBlocks  int
	SelectionRangesBlocks int
	SelectionBitmapBlocks int
	SelectionSparseBlocks int
	SelectionCompositions int

	DirectTypedColumnAssetReads    int
	FullAssetReads                 int
	FallbackReads                  int
	CodesMatched                   int
	DictionaryBytesDecoded         uint64
	FullAssetBytes                 uint64
	SectionBytesRead               uint64
	RangeBytesRead                 uint64
	MappedBytes                    uint64
	HeapCopyBytes                  uint64
	DecodedMetadataBytes           uint64
	DecodedHeapCopyBytes           uint64
	MaterializedBytes              uint64
	FastDecodeDirectViewPlans      int
	FastDecodeStreamingPlans       int
	FastDecodeMaterializePlans     int
	FastDecodeUnsupportedPlans     int
	FastDecodeMmapDirectViews      int
	FastDecodeHeapCopyTypedViews   int
	FastDecodeScratchDecodes       int
	FastDecodeStreamingFallbacks   int
	FastDecodeCertificationFailure int
	FastDecodeAbsoluteUnaligned    int
	FastDecodeActualUnaligned      int
	FastDecodeStaleHandles         int
	DirectViewSuccesses            int
	DirectViewFailures             int
	KernelBlocks                   int
	KernelFullCoveredBlocks        int
	KernelSelectedBlocks           int
	KernelCursorBlocks             int
	KernelFallbackBlocks           int
	StatsBlocks                    int
	StatsFullCoveredBlocks         int
	StatsFallbackBlocks            int
	StatsRows                      int
	PruningBlocks                  int
	PruningRows                    int
	PruningFallbackBlocks          int
	PruningFallbackReason          string
	StatsFallbackReason            string
	StatsValidationFailures        int
	StatsValidationFailureReason   string
	PruningValidationFailures      int
	PruningValidationFailureReason string
	FastDecodeFallbackReason       string
	DirectViewCertified            int
	StreamingCertified             int
	StatsCertified                 int
	PruningCertified               int
	CertificationFailures          int
	CertificationFailureReason     string
	PhysicalBytesScanned           int64
	RowLocatorDecodes              int
	PhysicalRowIDLookups           int
	PhysicalRowAssetReads          int
	RowMaterializations            int
	DocumentMaterializations       int
	DocumentReconstructions        int
	SegmentFileCacheHits           uint64
	SegmentFileCacheMisses         uint64
	ColumnAssetReadIntegrity       string
	Fallback                       bool
	FallbackReason                 string
	ScanNanos                      int64
}

type TypedColumnInt64PredicateScanKind 

type TypedColumnInt64PredicateScanKind string
const (
	TypedColumnInt64PredicateAll   TypedColumnInt64PredicateScanKind = "all"
	TypedColumnInt64PredicateEqual TypedColumnInt64PredicateScanKind = "equal"
	TypedColumnInt64PredicateRange TypedColumnInt64PredicateScanKind = "range"
)

type TypedColumnInt64PredicateScanRequest 

type TypedColumnInt64PredicateScanRequest struct {
	Column                   string
	Kind                     TypedColumnInt64PredicateScanKind
	Value                    int64
	Low                      int64
	High                     int64
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

type TypedColumnInt64PredicateScanResult 

type TypedColumnInt64PredicateScanResult struct {
	Rows        []TypedColumnInt64PredicateScanRow
	Diagnostics TypedColumnInt64PredicateScanDiagnostics
}

type TypedColumnInt64PredicateScanRow 

type TypedColumnInt64PredicateScanRow struct {
	Generation uint64
	PartID     uint64
	RowIndex   int
	PrimaryID  int64
	DocumentID []byte
	Value      int64
}

type TypedColumnStringPredicateScanDiagnostics 

type TypedColumnStringPredicateScanDiagnostics = TypedColumnInt64PredicateScanDiagnostics

type TypedColumnStringPredicateScanKind 

type TypedColumnStringPredicateScanKind string
const (
	TypedColumnStringPredicateEqual        TypedColumnStringPredicateScanKind = "equal"
	TypedColumnStringPredicateInList       TypedColumnStringPredicateScanKind = "in_list"
	TypedColumnStringPredicateCategory     TypedColumnStringPredicateScanKind = "category"
	TypedColumnStringPredicatePrefix       TypedColumnStringPredicateScanKind = "prefix"
	TypedColumnStringPredicateLexicalRange TypedColumnStringPredicateScanKind = "lexical_range"
)

type TypedColumnStringPredicateScanRequest 

type TypedColumnStringPredicateScanRequest struct {
	Column                   string
	Kind                     TypedColumnStringPredicateScanKind
	Value                    string
	Values                   []string
	Prefix                   string
	Low                      string
	High                     string
	ColumnAssetReadIntegrity ColumnAssetReadIntegrity
}

type TypedColumnStringPredicateScanResult 

type TypedColumnStringPredicateScanResult struct {
	Rows        []TypedColumnStringPredicateScanRow
	Diagnostics TypedColumnStringPredicateScanDiagnostics
}

type TypedColumnStringPredicateScanRow 

type TypedColumnStringPredicateScanRow struct {
	Generation uint64
	PartID     uint64
	RowIndex   int
	PrimaryID  int64
	DocumentID []byte
	Value      string
}

type TypedStorageAssetClass 

type TypedStorageAssetClass string

TypedStorageAssetClass classifies non-authoritative assets associated with a typed-storage owner/generation. 

const (
	// TypedStorageAssetClassDerivedAccelerator marks dictionaries, int64 values,
	// aggregate metadata, vector graphs, and caches as derived sidecars. It is not
	// an authoritative field owner.
	TypedStorageAssetClassDerivedAccelerator TypedStorageAssetClass = "derived_accelerator"
)

type TypedStorageDerivedAccelerator 

type TypedStorageDerivedAccelerator struct {
	Name            string                 `json:"name"`
	Class           TypedStorageAssetClass `json:"class"`
	SourceFieldPath string                 `json:"source_field_path,omitempty"`
	SourceOwner     TypedStorageFieldOwner `json:"source_owner,omitempty"`
	Generation      uint64                 `json:"generation,omitempty"`
}

TypedStorageDerivedAccelerator describes a non-authoritative sidecar tied to an authoritative owner and optional generation.

type TypedStorageField 

type TypedStorageField struct {
	Name               string                    `json:"name,omitempty"`
	Path               string                    `json:"path"`
	Owner              TypedStorageFieldOwner    `json:"owner"`
	ValueType          ColumnStoreValueType      `json:"value_type,omitempty"`
	Nullable           bool                      `json:"nullable,omitempty"`
	Dictionary         bool                      `json:"dictionary,omitempty"`
	VectorDims         int                       `json:"vector_dims,omitempty"`
	ElementsPerRow     int                       `json:"elements_per_row,omitempty"`
	BytesPerRow        int                       `json:"bytes_per_row,omitempty"`
	BitsPerElement     int                       `json:"bits_per_element,omitempty"`
	AdjacencyDegree    int                       `json:"adjacency_degree,omitempty"`
	AdjacencyLayout    ColumnAdjacencyListLayout `json:"adjacency_layout,omitempty"`
	FixedWidthEncoding ColumnFixedWidthEncoding  `json:"fixed_width_encoding,omitempty"`
}

TypedStorageField describes one explicitly resolved logical field owner. The zero Owner is normalized to TypedStorageOwnerRowAsset for compatibility with existing ColumnStoreConfig declared typed fields.

type TypedStorageFieldOwner 

type TypedStorageFieldOwner string

TypedStorageFieldOwner names the authoritative physical owner for one logical field in a normalized typed-storage layout. 

const (
	// TypedStorageOwnerRetainedDocument means the field is authoritatively owned
	// by the retained document/document_payload path.
	TypedStorageOwnerRetainedDocument TypedStorageFieldOwner = "retained_document"
	// TypedStorageOwnerRowAsset means the field is authoritatively owned by the
	// current typed-row physical asset path.
	TypedStorageOwnerRowAsset TypedStorageFieldOwner = "typed_row_asset"
	// TypedStorageOwnerColumnPart means the field is authoritatively owned by a
	// typed-column part. Unsupported value-type/layout combinations continue to
	// fail closed in the adapter and publication path.
	TypedStorageOwnerColumnPart TypedStorageFieldOwner = "typed_column_part"
)

type TypedStorageLayout 

type TypedStorageLayout struct {
	Collection string `json:"collection,omitempty"`
	Enabled    bool   `json:"enabled,omitempty"`

	// Fields contains explicit authoritative owners for declared/logical fields.
	// Unknown document fields are represented by RetainedDocumentOwnsRemainder.
	Fields []TypedStorageField `json:"fields,omitempty"`

	// RetainedPayload records the compatibility retained-payload policy that
	// produced the document_payload behavior below.
	RetainedPayload ColumnRetainedPayloadPolicy `json:"retained_payload,omitempty"`
	// RetainedDocumentOwnsRemainder means document_payload remains the
	// authoritative owner for fields not listed in Fields.
	RetainedDocumentOwnsRemainder bool `json:"retained_document_owns_remainder,omitempty"`
	// RetainedDocumentCompatibilityDuplicate means document_payload may contain
	// bytes for fields whose authoritative owner is a typed asset. This models
	// ColumnRetainedPayloadFull compatibility duplication without creating
	// overlapping authoritative owners.
	RetainedDocumentCompatibilityDuplicate bool `json:"retained_document_compatibility_duplicate,omitempty"`

	DerivedAccelerators []TypedStorageDerivedAccelerator `json:"derived_accelerators,omitempty"`
}

TypedStorageLayout is the pure-metadata resolved ownership view for a collection generation. It does not open assets, read sections, mutate DB state, publish roots, or acquire mmap/resource handles.

func NormalizeTypedStorageLayout 

func NormalizeTypedStorageLayout(in TypedStorageLayout) (TypedStorageLayout, error)

NormalizeTypedStorageLayout normalizes and validates an explicit pure-metadata typed-storage layout. It accepts typed_column_part placeholders so future metadata can be represented, while fail-closed read/publication guards below prevent accidental use as a supported data path.

func ResolveTypedStorageLayout 

func ResolveTypedStorageLayout(meta CollectionMeta) (TypedStorageLayout, error)

ResolveTypedStorageLayout maps collection metadata to a normalized typed-storage ownership layout. Existing ColumnStoreConfig metadata is kept as compatibility input: declared columns resolve to typed_row_asset ownership.

func (TypedStorageLayout) EnsurePublicationSupported 

func (l TypedStorageLayout) EnsurePublicationSupported() error

EnsurePublicationSupported fails closed for typed_column_part owners whose value types are not represented by the current durable typed-column path.

func (TypedStorageLayout) EnsureReadSupported 

func (l TypedStorageLayout) EnsureReadSupported() error

EnsureReadSupported fails closed for typed_column_part owners whose value types are not represented by the current durable typed-column path.

func (TypedStorageLayout) FieldOwnerDebugRows 

func (l TypedStorageLayout) FieldOwnerDebugRows() []string

FieldOwnerDebugRows returns deterministic status/debug rows for tests and PR evidence without touching DB files or opening assets.

func (TypedStorageLayout) HasTypedColumnPartOwners 

func (l TypedStorageLayout) HasTypedColumnPartOwners() bool

HasTypedColumnPartOwners reports whether the layout contains future typed-column authoritative owners.

func (TypedStorageLayout) OwnerForPath 

func (l TypedStorageLayout) OwnerForPath(path string) (TypedStorageFieldOwner, bool)

OwnerForPath returns the authoritative owner for a logical field path when it is explicitly declared or is covered by the retained document remainder.

type UpdateBatchItem 

type UpdateBatchItem struct {
	DocumentID []byte
	Update     func(current []byte) (replacement []byte, changed bool, err error)
}

UpdateBatchItem describes one document update in a batch. DocumentID must be non-empty and unique within the batch. Update receives the current stored document bytes and returns the replacement document bytes in the same format expected by Update. If Update returns changed=true, replacement must be a complete valid stored document for the collection format; returning replacement=nil, changed=false is the supported no-op form.

type UpdateBatchItemError 

type UpdateBatchItemError struct {
	Index int
	Err   error
}

UpdateBatchItemError wraps an error produced while preparing or applying one item in an UpdateBatch call.

func (*UpdateBatchItemError) Error 

func (e *UpdateBatchItemError) Error() string

func (*UpdateBatchItemError) Unwrap 

func (e *UpdateBatchItemError) Unwrap() error

type UpdateBatchResult 

type UpdateBatchResult struct {
	Matched  bool
	Modified bool
}

UpdateBatchResult reports the outcome for one UpdateBatch item.

type VectorDocumentFetchPreset 

type VectorDocumentFetchPreset struct {
	// IncludeDocuments should be copied to vector search options. The
	// projection-oriented preset sets this to true because projection is only
	// meaningful when callers request final documents.
	IncludeDocuments bool
	// DocumentFetchOptions should be copied to vector search options. ApplyTo*
	// always replaces IncludePaths/ExcludePaths from the target options. Scalar
	// fields use merge semantics: zero-valued preset scalars preserve the target
	// option's existing value, and non-zero preset scalars override it.
	DocumentFetchOptions DocumentFetchOptions
}

VectorDocumentFetchPreset is a named, opt-in final-document fetch preset for vector search APIs. Apply it to VectorIndexSearchOptions or VectorIndexSearcherSearchOptions when a vector search response should include top-k documents while omitting the vector payload field from those documents.

The projection-oriented preset is the storage-efficient product path for vector-heavy document responses: use ColumnRetainedPayloadNonColumn at storage setup time, then use this preset at search time to fetch documents with the vector field excluded from the final response. The preset is deliberately opt-in; zero-valued search options and IncludeDocuments=true without this preset continue to return full documents.

func ProjectionOrientedVectorDocumentFetchPreset 

func ProjectionOrientedVectorDocumentFetchPreset(def VectorIndexDefinition) (VectorDocumentFetchPreset, error)

ProjectionOrientedVectorDocumentFetchPreset returns the preferred vector final-document fetch preset for the field declared by def.Field. It excludes that vector field from materialized JSON documents and sets IncludeDocuments for the target vector search options.

Current DocumentFetchOptions projection supports top-level JSON fields only; nested vector fields fail closed with a clear error instead of silently projecting a broader document shape.

func ProjectionOrientedVectorDocumentFetchPresetForField 

func ProjectionOrientedVectorDocumentFetchPresetForField(vectorField string) (VectorDocumentFetchPreset, error)

ProjectionOrientedVectorDocumentFetchPresetForField returns the preferred vector final-document fetch preset for a custom vector field path. The field path must be a supported top-level JSON projection path.

func (VectorDocumentFetchPreset) ApplyToSearchOptions 

func (p VectorDocumentFetchPreset) ApplyToSearchOptions(opts *VectorIndexSearchOptions)

ApplyToSearchOptions applies p to collection-level SearchVectorIndex options. It enables IncludeDocuments, replaces projection paths from opts.DocumentFetchOptions, and preserves existing scalar fetch settings unless the preset explicitly overrides them.

func (VectorDocumentFetchPreset) ApplyToSearcherSearchOptions 

func (p VectorDocumentFetchPreset) ApplyToSearcherSearchOptions(opts *VectorIndexSearcherSearchOptions)

ApplyToSearcherSearchOptions applies p to reusable VectorIndexSearcher.Search options. It enables IncludeDocuments, replaces projection paths from opts.DocumentFetchOptions, and preserves existing scalar fetch settings unless the preset explicitly overrides them.

type VectorIndex 

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

VectorIndex is the process-local runtime graph for collection vector fields. Declared collection vector indexes can persist this runtime graph into a TreeDB-managed collection root; ad hoc indexes can still be rebuilt from primary collection rows.

func (*VectorIndex) CheckRecall 

func (idx *VectorIndex) CheckRecall(queries [][]float32, opts VectorIndexSearchOptions) (VectorIndexRecall, error)

CheckRecall compares indexed search with exact search for the supplied query vectors and reports recall@TopK.

func (*VectorIndex) InsertDocument 

func (idx *VectorIndex) InsertDocument(documentID []byte) error

InsertDocument adds or replaces one committed collection document in the in-memory index. Missing or null vector fields leave the document unindexed and tombstone any previous indexed version.

func (*VectorIndex) PruneOldSnapshots 

func (idx *VectorIndex) PruneOldSnapshots(keep int) (VectorIndexPruneStatus, error)

PruneOldSnapshots removes older immutable epoch directories for this vector index while preserving the currently published manifest epoch and the newest keep-1 additional epochs. It never removes temp directories.

func (*VectorIndex) Rebuild 

func (idx *VectorIndex) Rebuild() error

Rebuild removes tombstoned/superseded graph nodes by rebuilding the index from live canonical collection rows. It preserves vector index options and swaps the rebuilt graph into the receiver.

func (*VectorIndex) SaveNativeDeltaSnapshot 

func (idx *VectorIndex) SaveNativeDeltaSnapshot() (VectorIndexLoadStatus, error)

SaveNativeDeltaSnapshot persists dirty graph records for a declared vector index as a collection-root delta. It is used by live write maintenance; full rebuild/shrink publication should continue to use SaveNativeSnapshot so removed graph keys cannot survive.

func (*VectorIndex) SaveNativeSnapshot 

func (idx *VectorIndex) SaveNativeSnapshot() (VectorIndexLoadStatus, error)

SaveNativeSnapshot persists the current in-memory vector index as ordinary TreeDB collection-root content and publishes that root through the collection root descriptor system state.

func (*VectorIndex) SaveSnapshot 

func (idx *VectorIndex) SaveSnapshot() (VectorIndexLoadStatus, error)

SaveSnapshot persists the current in-memory vector index. Declared collection vector indexes use a native TreeDB collection root; ad hoc in-memory indexes keep using the legacy sidecar snapshot path.

func (*VectorIndex) Search 

func (idx *VectorIndex) Search(query []float32, opts VectorIndexSearchOptions) ([]VectorSearchResult, VectorIndexTrace, error)

Search returns ANN candidates from the in-memory graph and reranks the final result set. Unfiltered float32 cosine indexes rerank from resident vectors; filtered or compressed searches rerank from canonical collection rows. If graph search underfills and DisableExactFallback is false, it falls back to the exact scan API.

func (*VectorIndex) Stats 

func (idx *VectorIndex) Stats() VectorIndexStats

Stats returns a snapshot of in-memory vector index state.

func (*VectorIndex) TombstoneDocumentID 

func (idx *VectorIndex) TombstoneDocumentID(documentID []byte)

TombstoneDocumentID marks the current indexed version of documentID deleted. Tombstoned nodes remain in the graph until the caller rebuilds the index.

type VectorIndexDefinition 

type VectorIndexDefinition struct {
	Name             string                           `json:"name"`
	Field            string                           `json:"field"`
	Metric           VectorMetric                     `json:"metric"`
	Dimensions       int                              `json:"dimensions"`
	M                int                              `json:"m,omitempty"`
	EfConstruction   int                              `json:"ef_construction,omitempty"`
	EfSearch         int                              `json:"ef_search,omitempty"`
	Encoding         VectorIndexEncoding              `json:"encoding,omitempty"`
	Strategy         VectorIndexStrategy              `json:"strategy,omitempty"`
	SchemaGeneration uint64                           `json:"schema_generation,omitempty"`
	QuantizedIndexes []QuantizedVectorIndexDefinition `json:"quantized_indexes,omitempty"`
}

VectorIndexDefinition declares a document vector field as an ANN-capable collection index. PRs after the metadata/API step persist and maintain the HNSW graph through collection index roots.

type VectorIndexEncoding 

type VectorIndexEncoding uint8

VectorIndexEncoding selects the process-local ANN vector copy format. The collection row remains canonical; float32 indexes can rerank directly from the indexed vector copy, while compressed indexes rerank from canonical rows. 

const (
	VectorIndexEncodingFloat32 VectorIndexEncoding = iota
	VectorIndexEncodingInt8
)

func (VectorIndexEncoding) MarshalJSON 

func (e VectorIndexEncoding) MarshalJSON() ([]byte, error)

func (VectorIndexEncoding) String 

func (e VectorIndexEncoding) String() string

func (*VectorIndexEncoding) UnmarshalJSON 

func (e *VectorIndexEncoding) UnmarshalJSON(raw []byte) error

type VectorIndexLoadStatus 

type VectorIndexLoadStatus struct {
	Loaded              bool
	ExactFallbackReason string
	ManifestPath        string
	RootName            string
	RootID              uint64
	Epoch               uint64
	BytesDisk           int64
}

VectorIndexLoadStatus reports whether a persisted vector index loaded or why callers should use exact search as the safe fallback.

type VectorIndexOptions 

type VectorIndexOptions struct {
	Name                string
	Field               string
	Metric              VectorMetric
	Dimensions          int
	M                   int
	EfConstruction      int
	EfSearch            int
	RebuildDeletedRatio float64
	Encoding            VectorIndexEncoding
	// contains filtered or unexported fields
}

VectorIndexOptions configures an in-memory vector secondary index built from collection rows. The index stores stable collection document IDs and vector copies for graph search; TreeDB collection rows remain canonical for returned document payloads and filtered reranking.

type VectorIndexPruneStatus 

type VectorIndexPruneStatus struct {
	IndexDir      string
	ActiveEpoch   string
	RemovedEpochs int
	RemovedBytes  int64
}

VectorIndexPruneStatus reports persisted vector-index epoch cleanup.

type VectorIndexQueryMode 

type VectorIndexQueryMode string

VectorIndexQueryMode selects the score plane used by column_graph search. The zero value is exact to preserve existing search behavior. Quantized modes must be selected explicitly with a named quantized index and fail closed until matching assets and scorers are available. 

const (
	VectorIndexQueryModeExact           VectorIndexQueryMode = "exact"
	VectorIndexQueryModeQuantizedOnly   VectorIndexQueryMode = "quantized_only"
	VectorIndexQueryModeQuantizedRerank VectorIndexQueryMode = "quantized_rerank"
)

type VectorIndexRangeFilter 

type VectorIndexRangeFilter struct {
	IndexName string
	Range     IndexRangeOptions
}

VectorIndexRangeFilter restricts vector search to document IDs produced by a scalar collection secondary-index range.

type VectorIndexReason 

type VectorIndexReason string
const (
	VectorIndexReasonNativeRuntime                     VectorIndexReason = "native_runtime_index"
	VectorIndexReasonColumnGraphRebuildNeeded          VectorIndexReason = "column_graph_rebuild_needed"
	VectorIndexReasonPhysicalColumnAssetSupportMissing VectorIndexReason = "physical_column_asset_support_missing"
	VectorIndexReasonColumnGraphAssetMismatch          VectorIndexReason = "column_graph_asset_mismatch"
	VectorIndexReasonColumnGraphCorrupt                VectorIndexReason = "column_graph_corrupt"
	VectorIndexReasonColumnGraphUnsupportedVisibility  VectorIndexReason = "column_graph_unsupported_visibility"
	VectorIndexReasonColumnGraphUnsupportedMetric      VectorIndexReason = "column_graph_unsupported_metric"
	VectorIndexReasonUnsupportedStrategy               VectorIndexReason = "unsupported_vector_index_strategy"
)

type VectorIndexRecall 

type VectorIndexRecall struct {
	Queries      int
	TopK         int
	ExactTotal   int
	ANNTotal     int
	Overlap      int
	Recall       float64
	SearchTraces []VectorIndexTrace
}

VectorIndexRecall reports ANN overlap with exact search for sampled queries.

type VectorIndexSearchBuffer 

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

VectorIndexSearchBuffer is caller-owned reusable response storage for VectorIndexSearcher.SearchWithBuffer and Collection.SearchVectorIndexWithBuffer. It is intended for steady-state no-document searches that need to avoid per-call response allocation. Reuse a warmed buffer to keep result-ID searches allocation-free once open/prepared state is outside the measured boundary.

A VectorIndexSearchBuffer is not safe for concurrent use. Do not reuse or reset the same buffer while any caller still needs a response previously returned from it. The response Results slice and each result ID returned by buffered search APIs alias this buffer and remain valid only until the same buffer is reused or Reset is called. Parallel callers should use independent searcher/buffer pairs per worker.

func (*VectorIndexSearchBuffer) Reset 

func (b *VectorIndexSearchBuffer) Reset()

Reset clears the buffer's current response view while retaining reusable capacity. Any response previously returned by a buffered search API with this buffer must be considered invalid after Reset returns.

type VectorIndexSearchDiagnostics 

type VectorIndexSearchDiagnostics struct {
	Route                         VectorIndexSearchRouteKind            `json:"route"`
	HNSWSearchPackStatus          VectorIndexSearchHNSWSearchPackStatus `json:"hnsw_search_pack_status"`
	FallbackReason                VectorIndexSearchFallbackReason       `json:"fallback_reason"`
	NoDocumentGuardrailsOK        bool                                  `json:"no_document_guardrails_ok"`
	ExactHNSWSearchPackNoDocRoute bool                                  `json:"exact_hnsw_search_pack_no_doc_route"`
	DocumentsFetched              uint64                                `json:"docs_fetched,omitempty"`
	GraphRowFallbacks             uint64                                `json:"graph_row_fallbacks,omitempty"`
	TypedColumnVectorFallbacks    uint64                                `json:"typed_column_vector_fallbacks,omitempty"`
	VectorScratchDecodes          uint64                                `json:"vector_scratch_decodes,omitempty"`
	OpenSearcherCalls             uint64                                `json:"open_searcher_calls,omitempty"`
	OpenSetupInTimedLoop          uint64                                `json:"open_setup_in_timed_loop,omitempty"`
	ResponseOwnedResultAllocs     uint64                                `json:"response_owned_result_allocs,omitempty"`
	HNSWSearchPackCacheHits       uint64                                `json:"hnsw_search_pack_cache_hits,omitempty"`
	HNSWSearchPackCacheMisses     uint64                                `json:"hnsw_search_pack_cache_misses,omitempty"`
	HNSWSearchPackCacheWaits      uint64                                `json:"hnsw_search_pack_cache_waits,omitempty"`
	HNSWSearchPackCacheBuilds     uint64                                `json:"hnsw_search_pack_cache_builds,omitempty"`
}

VectorIndexSearchDiagnostics is a compact allocation-free value summary for route/status and no-document guardrail checks. It is derived from VectorIndexSearchStats; callers that need full counters should inspect Stats.

type VectorIndexSearchFallbackReason 

type VectorIndexSearchFallbackReason string

VectorIndexSearchFallbackReason summarizes why a search did not remain on the preferred exact no-document route. Values are low-cardinality and derived from counters; no logging or map allocation is required. 

const (
	// VectorIndexSearchFallbackReasonNone reports no observed fallback reason.
	VectorIndexSearchFallbackReasonNone VectorIndexSearchFallbackReason = "none"
	// VectorIndexSearchFallbackReasonHNSWSearchPackMissing reports fallback because exact pack state was missing.
	VectorIndexSearchFallbackReasonHNSWSearchPackMissing VectorIndexSearchFallbackReason = "hnsw_search_pack_missing"
	// VectorIndexSearchFallbackReasonHNSWSearchPackInvalid reports fallback because exact pack state was invalid.
	VectorIndexSearchFallbackReasonHNSWSearchPackInvalid VectorIndexSearchFallbackReason = "hnsw_search_pack_invalid"
	// VectorIndexSearchFallbackReasonHNSWSearchPackStale reports fallback because exact pack state was stale.
	VectorIndexSearchFallbackReasonHNSWSearchPackStale VectorIndexSearchFallbackReason = "hnsw_search_pack_stale"
	// VectorIndexSearchFallbackReasonHNSWSearchPackClosed reports fallback because exact pack state was closed.
	VectorIndexSearchFallbackReasonHNSWSearchPackClosed VectorIndexSearchFallbackReason = "hnsw_search_pack_closed"
	// VectorIndexSearchFallbackReasonHNSWSearchPackUnavailable reports a generic exact pack fallback without a more specific status.
	VectorIndexSearchFallbackReasonHNSWSearchPackUnavailable VectorIndexSearchFallbackReason = "hnsw_search_pack_unavailable"
	// VectorIndexSearchFallbackReasonColumnGraphFallback reports the column_graph compatibility/fallback route.
	VectorIndexSearchFallbackReasonColumnGraphFallback VectorIndexSearchFallbackReason = "column_graph_fallback"
	// VectorIndexSearchFallbackReasonGraphRowFallback reports legacy graph-row fallback activity.
	VectorIndexSearchFallbackReasonGraphRowFallback VectorIndexSearchFallbackReason = "graph_row_fallback"
	// VectorIndexSearchFallbackReasonTypedColumnVectorFallback reports typed-column vector fallback activity.
	VectorIndexSearchFallbackReasonTypedColumnVectorFallback VectorIndexSearchFallbackReason = "typed_column_vector_fallback"
	// VectorIndexSearchFallbackReasonVectorScratchDecode reports vector scratch/fallback decode activity.
	VectorIndexSearchFallbackReasonVectorScratchDecode VectorIndexSearchFallbackReason = "vector_scratch_decode"
)

type VectorIndexSearchHNSWSearchPackStatus 

type VectorIndexSearchHNSWSearchPackStatus string

VectorIndexSearchHNSWSearchPackStatus summarizes hnsw_search_pack_v1 health from public search stats. It describes the pack traversal asset itself; codec route kind and quantized score-plane health remain separate counters. 

const (
	// VectorIndexSearchHNSWSearchPackStatusNone reports no hnsw_search_pack_v1 observation.
	VectorIndexSearchHNSWSearchPackStatusNone VectorIndexSearchHNSWSearchPackStatus = "none"
	// VectorIndexSearchHNSWSearchPackStatusActive reports a validated active hnsw_search_pack_v1 view.
	VectorIndexSearchHNSWSearchPackStatusActive VectorIndexSearchHNSWSearchPackStatus = "active"
	// VectorIndexSearchHNSWSearchPackStatusMissing reports no available hnsw_search_pack_v1 state.
	VectorIndexSearchHNSWSearchPackStatusMissing VectorIndexSearchHNSWSearchPackStatus = "missing"
	// VectorIndexSearchHNSWSearchPackStatusInvalid reports invalid hnsw_search_pack_v1 state.
	VectorIndexSearchHNSWSearchPackStatusInvalid VectorIndexSearchHNSWSearchPackStatus = "invalid"
	// VectorIndexSearchHNSWSearchPackStatusStale reports stale hnsw_search_pack_v1 state.
	VectorIndexSearchHNSWSearchPackStatusStale VectorIndexSearchHNSWSearchPackStatus = "stale"
	// VectorIndexSearchHNSWSearchPackStatusClosed reports a closed hnsw_search_pack_v1 view.
	VectorIndexSearchHNSWSearchPackStatusClosed VectorIndexSearchHNSWSearchPackStatus = "closed"
)

type VectorIndexSearchOptions 

type VectorIndexSearchOptions struct {
	// IndexName is used by collection-level physical column_graph search.
	IndexName string
	// Query is used by collection-level physical column_graph search.
	Query []float32
	// QueryMode selects exact, quantized-only, or quantized-rerank search for
	// collection column_graph APIs. The zero value is exact. Only exact/zero mode
	// is in the collection-level no-document high-QPS contract; quantized modes are
	// explicit score-plane paths with their own fail-closed semantics.
	QueryMode VectorIndexQueryMode
	// QuantizedIndexName selects the named derived score plane for quantized modes.
	QuantizedIndexName string
	// QuantizedRerankCandidates bounds the quantized candidate set reranked by
	// exact float32 vectors in quantized_rerank mode. Zero uses the normalized
	// ef_search candidate set.
	QuantizedRerankCandidates int
	TopK                      int
	EfSearch                  int
	FetchMultiplier           int
	Filter                    func(DocumentRecord) (bool, error)
	IndexRangeFilter          *VectorIndexRangeFilter
	ExactFilterMaxDocs        int
	DisableExactFallback      bool
	// IncludeDocuments materializes documents after column_graph top-k selection.
	IncludeDocuments bool
	// DocumentFetchOptions controls optional projected final-fetch materialization.
	// It is used only when IncludeDocuments is true; the zero value returns full documents.
	DocumentFetchOptions DocumentFetchOptions
	// MaxDecodedBlocks bounds the physical column row reader cache for column_graph search.
	MaxDecodedBlocks int
	// StatsMode selects column_graph search telemetry detail. The zero value
	// preserves full diagnostics; production/minimal mode keeps source-health,
	// fallback, admission, and result counters with lower hot-loop overhead on
	// the healthy combined prepared path.
	StatsMode VectorIndexSearchStatsMode
	// contains filtered or unexported fields
}

VectorIndexSearchOptions configures one vector index search.

Collection-level high-QPS no-document searches are intentionally narrow: use an explicit column_graph index, exact/zero QueryMode, IncludeDocuments=false, no document projection, and no legacy filter fields. The current Collection.SearchVectorIndex method is a response-owned convenience boundary that uses the cached hnsw_search_pack_v1 route for healthy exact no-document calls and falls back to a one-shot searcher for unsupported shapes. Collection.SearchVectorIndexWithBuffer exposes caller-owned result storage for the exact no-document hnsw_search_pack_v1 seam and reuses collection-owned prepared pack state on warmed healthy current state; callers that need explicit snapshot lifetime control can still use a reusable VectorIndexSearcher with VectorIndexSearcher.SearchWithBuffer. To materialize documents after a no-document search, open a CollectionReadView and call FetchDocumentsForVectorIndexSearchResults as an explicit, separately measured fetch phase.

type VectorIndexSearchPath 

type VectorIndexSearchPath string

VectorIndexSearchPath identifies the physical implementation used for a public vector-index search. 

const (
	// VectorIndexSearchPathColumnGraphNativeReader searches persisted column_graph
	// state through the native reader. Current healthy indexes use TVIS/base
	// typed-column sources; legacy physical graph rows are compatibility fallback
	// only. It does not build or query a decoded in-memory ColumnVectorGraph.
	VectorIndexSearchPathColumnGraphNativeReader VectorIndexSearchPath = "column_graph_native_reader"
)

type VectorIndexSearchResponse 

type VectorIndexSearchResponse struct {
	// IndexName is the searched collection vector-index name.
	IndexName string `json:"index_name"`
	// Strategy is the declared vector-index strategy.
	Strategy VectorIndexStrategy `json:"strategy"`
	// Path is the implementation path actually used for the search, when one ran.
	Path VectorIndexSearchPath `json:"path,omitempty"`
	// Status describes whether the index was loaded, unavailable, or stale.
	Status VectorIndexStatus `json:"status"`
	// Stats contains search and reader telemetry.
	Stats VectorIndexSearchStats `json:"stats,omitempty"`
	// Results contains top-k hits in descending score order. Search and
	// SearchVectorIndex return response-owned slices; SearchWithBuffer and
	// SearchVectorIndexWithBuffer return slices owned by the caller's
	// VectorIndexSearchBuffer.
	Results []VectorIndexSearchResult `json:"results,omitempty"`
}

VectorIndexSearchResponse is returned by public vector-index search APIs.

func (VectorIndexSearchResponse) Diagnostics 

func (r VectorIndexSearchResponse) Diagnostics() VectorIndexSearchDiagnostics

Diagnostics returns a compact route/status summary for the response.

type VectorIndexSearchResult 

type VectorIndexSearchResult struct {
	// ID is the collection document ID. Search and SearchVectorIndex return
	// response-owned bytes. SearchWithBuffer returns bytes owned by the caller's
	// VectorIndexSearchBuffer and valid only until that buffer is reused or reset.
	ID []byte `json:"id"`
	// Ordinal is the vector row ordinal in the persisted column_graph index.
	Ordinal int `json:"ordinal"`
	// Score is the result score for the selected query mode: exact/default and
	// quantized_rerank return authoritative float32 cosine scores, while
	// quantized_only returns the selected codec's estimated cosine score.
	Score float64 `json:"score"`
	// Document is populated only when IncludeDocuments is true.
	Document []byte `json:"document,omitempty"`
}

VectorIndexSearchResult is one public vector-index search hit.

type VectorIndexSearchRouteKind 

type VectorIndexSearchRouteKind string

VectorIndexSearchRouteKind is a compact route summary derived from public search stats. The exact hnsw_search_pack_v1 route is intentionally distinct from codec-generic quantized route kinds; a quantized search may still report SearchRouteHNSWSearchPack when a codec-specific score plane uses pack traversal, but RouteKind remains quantized. 

const (
	// VectorIndexSearchRouteUnknown reports that stats did not identify a search route.
	VectorIndexSearchRouteUnknown VectorIndexSearchRouteKind = "unknown"
	// VectorIndexSearchRouteExactHNSWSearchPackV1 reports the exact FP32 hnsw_search_pack_v1 route.
	VectorIndexSearchRouteExactHNSWSearchPackV1 VectorIndexSearchRouteKind = "exact_hnsw_search_pack_v1"
	// VectorIndexSearchRouteQuantizedOnly reports the codec-generic quantized-only route.
	VectorIndexSearchRouteQuantizedOnly VectorIndexSearchRouteKind = "quantized_only"
	// VectorIndexSearchRouteQuantizedRerank reports the codec-generic quantized-rerank route.
	VectorIndexSearchRouteQuantizedRerank VectorIndexSearchRouteKind = "quantized_rerank"
	// VectorIndexSearchRouteColumnGraphPrepared reports the prepared column_graph route.
	VectorIndexSearchRouteColumnGraphPrepared VectorIndexSearchRouteKind = "column_graph_prepared"
	// VectorIndexSearchRouteColumnGraphFallback reports the column_graph compatibility/fallback route.
	VectorIndexSearchRouteColumnGraphFallback VectorIndexSearchRouteKind = "column_graph_fallback"
)

type VectorIndexSearchStats 

type VectorIndexSearchStats struct {
	// GraphRows is the number of legacy physical graph rows resident in the bound reader. Healthy current typed-column search reports zero.
	GraphRows uint64 `json:"graph_rows,omitempty"`
	// CandidateRows is the candidate row domain after any internal row-selection/visibility composition.
	CandidateRows uint64 `json:"candidate_rows,omitempty"`
	// Candidates is the number of candidate nodes scored by graph search.
	Candidates uint64 `json:"candidates,omitempty"`
	// Edges is the number of graph edges considered by graph search.
	Edges uint64 `json:"edges,omitempty"`
	// VisitedNodes is the operation-specific graph node score/evaluation visit counter. It includes upper-layer probes and may exceed Candidates.
	VisitedNodes uint64 `json:"visited_nodes,omitempty"`
	// VisitedEdges is the operation-specific graph edge visit counter. It aliases Edges for current column_graph search.
	VisitedEdges uint64 `json:"visited_edges,omitempty"`
	// VectorBytesRead is the logical vector payload bytes read while scoring candidates.
	VectorBytesRead uint64 `json:"vector_bytes_read,omitempty"`
	// NormBytesRead is the logical inverse-norm payload bytes read while scoring candidates.
	NormBytesRead uint64 `json:"norm_bytes_read,omitempty"`
	// AdjacencyBytesRead is the logical adjacency payload bytes read while expanding graph nodes.
	AdjacencyBytesRead uint64 `json:"adjacency_bytes_read,omitempty"`
	// CandidateFetches is the per-search count of score-plane row fetches for scored candidates.
	CandidateFetches uint64 `json:"candidate_fetches,omitempty"`
	// ScoreBatchCalls counts logical score calls: singleton scalar calls and indexed tile calls.
	ScoreBatchCalls uint64 `json:"score_batch_calls,omitempty"`
	// ScoreBatchCandidates counts candidate scores produced by score calls.
	ScoreBatchCandidates uint64 `json:"score_batch_candidates,omitempty"`
	// ScoreBatchMaxTileSize reports the largest score tile size observed by this search.
	ScoreBatchMaxTileSize uint64 `json:"score_batch_max_tile_size,omitempty"`
	// ScoreBatchOptimizedCalls counts score calls reported as optimized by the vectorops backend.
	ScoreBatchOptimizedCalls uint64 `json:"score_batch_optimized,omitempty"`
	// ScoreBatchScalarFallbackCalls counts score calls completed through scalar/fallback execution.
	ScoreBatchScalarFallbackCalls uint64 `json:"score_batch_fallback,omitempty"`
	// PreparedScoreCalls counts candidate scores produced by the prepared vector/norm scoring view.
	PreparedScoreCalls uint64 `json:"prepared_score_calls,omitempty"`
	// FP32ScoreCalls aliases exact float32 candidate score calls for work-accounting consumers.
	FP32ScoreCalls uint64 `json:"fp32_score_calls,omitempty"`
	// QuantizedScoreCalls counts candidate scores produced by a quantized score-plane scorer.
	QuantizedScoreCalls uint64 `json:"quantized_score_calls,omitempty"`
	// QuantizedCodeBytesRead is the logical quantized code-row byte count read while scoring candidates.
	QuantizedCodeBytesRead uint64 `json:"quantized_code_bytes_read,omitempty"`
	// QuantizedRerankCandidates counts quantized shortlist candidates submitted to exact rerank.
	QuantizedRerankCandidates uint64 `json:"quantized_rerank_candidates,omitempty"`
	// QuantizedRerankExactScoreCalls counts exact FP32 score calls used by quantized_rerank.
	QuantizedRerankExactScoreCalls uint64 `json:"quantized_rerank_exact_score_calls,omitempty"`
	// ExactRerankScoreCalls aliases exact rerank score calls for work-accounting consumers.
	ExactRerankScoreCalls uint64 `json:"exact_rerank_score_calls,omitempty"`
	// QuantizedScorerActive reports that a validated quantized scorer served this search.
	QuantizedScorerActive uint64 `json:"quantized_scorer_active,omitempty"`
	// QuantizedAssetMissing reports that the selected quantized score-plane asset was absent.
	QuantizedAssetMissing uint64 `json:"quantized_asset_missing,omitempty"`
	// QuantizedAssetInvalid reports that the selected quantized score-plane asset failed validation or decode.
	QuantizedAssetInvalid uint64 `json:"quantized_asset_invalid,omitempty"`
	// QuantizedAssetStale reports that the selected quantized score-plane asset did not match the current graph/index identity.
	QuantizedAssetStale uint64 `json:"quantized_asset_stale,omitempty"`
	// QuantizedAssetClosed reports that the selected quantized score-plane asset was closed before use.
	QuantizedAssetClosed uint64 `json:"quantized_asset_closed,omitempty"`
	// QuantizedAssetUnavailable aggregates missing, invalid, stale, or closed quantized score-plane asset failures.
	QuantizedAssetUnavailable uint64 `json:"quantized_asset_unavailable,omitempty"`
	// QuantizedAssetMmapDirect reports searches with a validated direct mmap quantized score-plane asset bound to the searcher.
	QuantizedAssetMmapDirect uint64 `json:"quantized_asset_mmap_direct,omitempty"`
	// QuantizedAssetHeapCopy reports searches with a validated heap-copy quantized score-plane asset bound to the searcher.
	QuantizedAssetHeapCopy uint64 `json:"quantized_asset_heap_copy,omitempty"`
	// QuantizedAssetOpenNanos reports open/prepare time for the selected quantized score-plane asset.
	QuantizedAssetOpenNanos uint64 `json:"quantized_asset_open_nanos,omitempty"`
	// QuantizedAssetMappedBytes is the mapped byte total backing the selected quantized score-plane asset.
	QuantizedAssetMappedBytes uint64 `json:"quantized_asset_mapped_bytes,omitempty"`
	// QuantizedAssetHeapCopyBytes is the heap-copy byte total backing the selected quantized score-plane asset.
	QuantizedAssetHeapCopyBytes uint64 `json:"quantized_asset_heap_copy_bytes,omitempty"`
	// QuantizedAssetActiveHandles is the current active mappedresource handle count for the selected quantized score-plane asset.
	QuantizedAssetActiveHandles int64 `json:"quantized_asset_active_handles,omitempty"`
	// QuantizedScoreCodecScalarU8Alpha reports searches served by scalar_u8 per-granule alpha scoring.
	QuantizedScoreCodecScalarU8Alpha uint64 `json:"quantized_score_codec_scalar_u8_alpha,omitempty"`
	// QuantizedScoreCodecBRQ1Bit reports searches served by the brq_1bit quantized scorer.
	QuantizedScoreCodecBRQ1Bit uint64 `json:"quantized_score_codec_brq_1bit,omitempty"`
	// BRQ1BitQueryWeightBits reports the runtime query-weight bit width for brq_1bit searches.
	BRQ1BitQueryWeightBits uint64 `json:"brq_1bit_query_weight_bits,omitempty"`
	// BRQ1BitBitProductPasses counts logical brq_1bit bit-product passes used by scorer calls.
	BRQ1BitBitProductPasses uint64 `json:"brq_1bit_bitproduct_passes,omitempty"`
	// BRQ1BitQueryWeightScale reports the query-local uint4 weight scale for brq_1bit searches.
	BRQ1BitQueryWeightScale float64 `json:"brq_1bit_query_weight_scale,omitempty"`
	// ScoreFloat64Fallbacks counts rare dot-product retries using float64 after a non-finite float32 dot.
	ScoreFloat64Fallbacks uint64 `json:"score_float64_fallbacks,omitempty"`
	// ExpansionFetches is the per-search count of adjacency row fetches for expanded nodes.
	ExpansionFetches uint64 `json:"expansion_fetches,omitempty"`
	// ResultFetches is the per-search count of vector row fetches for final results.
	ResultFetches uint64 `json:"result_fetches,omitempty"`
	// DocumentsFetched is the post-top-k document materialization count.
	DocumentsFetched uint64 `json:"documents_fetched,omitempty"`
	// DocumentsMissing is the post-top-k materialization miss count.
	DocumentsMissing uint64 `json:"documents_missing,omitempty"`
	// DocumentBytes is the materialized response document byte count.
	DocumentBytes uint64 `json:"document_bytes,omitempty"`
	// DocumentOutputBytes is the materialized response document byte count attributed to projection/materialization output.
	DocumentOutputBytes uint64 `json:"document_output_bytes,omitempty"`
	// DocumentFieldsReconstructed counts top-level fields emitted into response documents.
	DocumentFieldsReconstructed uint64 `json:"document_fields_reconstructed,omitempty"`
	// DocumentFieldsSkipped counts declared or retained top-level fields skipped by projection.
	DocumentFieldsSkipped uint64 `json:"document_fields_skipped,omitempty"`
	// DocumentFetchNanos attributes end-to-end post-top-k document fetch/materialization time.
	DocumentFetchNanos uint64 `json:"document_fetch_nanos,omitempty"`
	// DocumentRetainedFetches counts primary retained-payload fetches for document materialization.
	DocumentRetainedFetches uint64 `json:"document_retained_fetches,omitempty"`
	// DocumentRetainedBytes counts retained-payload bytes read for document materialization.
	DocumentRetainedBytes uint64 `json:"document_retained_bytes,omitempty"`
	// DocumentVisibilityScans counts batched typed-row visibility scans used by materialization.
	DocumentVisibilityScans uint64 `json:"document_visibility_scans,omitempty"`
	// DocumentVisibilityRowsScanned counts typed-row asset rows scanned for materialization.
	DocumentVisibilityRowsScanned uint64 `json:"document_visibility_rows_scanned,omitempty"`
	// DocumentVisibilityRows counts visible typed rows found by materialization scans.
	DocumentVisibilityRows uint64 `json:"document_visibility_rows,omitempty"`
	// DocumentVisibilityPhysicalBytes counts typed-row physical bytes scanned for materialization.
	DocumentVisibilityPhysicalBytes uint64 `json:"document_visibility_physical_bytes,omitempty"`
	// DocumentVisibilityNanos attributes typed-row visibility scan time.
	DocumentVisibilityNanos uint64 `json:"document_visibility_nanos,omitempty"`
	// DocumentTypedColumnRows counts materialized rows that consulted typed_column_part storage.
	DocumentTypedColumnRows uint64 `json:"document_typed_column_rows,omitempty"`
	// DocumentTypedColumnCacheHits counts typed-column reconstruction cache hits.
	DocumentTypedColumnCacheHits uint64 `json:"document_typed_column_cache_hits,omitempty"`
	// DocumentTypedColumnCacheMisses counts typed-column reconstruction cache misses.
	DocumentTypedColumnCacheMisses uint64 `json:"document_typed_column_cache_misses,omitempty"`
	// DocumentTypedColumnPartLoads counts typed_column_part asset loads.
	DocumentTypedColumnPartLoads uint64 `json:"document_typed_column_part_loads,omitempty"`
	// DocumentTypedColumnPartDecodes counts typed_column_part decodes.
	DocumentTypedColumnPartDecodes uint64 `json:"document_typed_column_part_decodes,omitempty"`
	// DocumentTypedColumnNanos attributes typed-column value fetch/decode time.
	DocumentTypedColumnNanos uint64 `json:"document_typed_column_nanos,omitempty"`
	// DocumentJSONReconstructionRows counts rows serialized through JSON reconstruction.
	DocumentJSONReconstructionRows uint64 `json:"document_json_reconstruction_rows,omitempty"`
	// DocumentJSONReconstructionNanos attributes JSON merge/serialization time.
	DocumentJSONReconstructionNanos uint64 `json:"document_json_reconstruction_nanos,omitempty"`
	// DocumentRowLocatorBuilds counts snapshot-derived row-locator map builds.
	DocumentRowLocatorBuilds uint64 `json:"document_row_locator_builds,omitempty"`
	// DocumentRowLocatorLookups counts document-id to row-ref locator lookups.
	DocumentRowLocatorLookups uint64 `json:"document_row_locator_lookups,omitempty"`
	// DocumentRowLocatorMisses counts locator lookups with no latest-visible row.
	DocumentRowLocatorMisses uint64 `json:"document_row_locator_misses,omitempty"`
	// DocumentRowLocatorRowsScanned counts physical rows scanned to build locator maps.
	DocumentRowLocatorRowsScanned uint64 `json:"document_row_locator_rows_scanned,omitempty"`
	// DocumentRowLocatorPhysicalBytes counts physical bytes scanned to build locator maps.
	DocumentRowLocatorPhysicalBytes uint64 `json:"document_row_locator_physical_bytes,omitempty"`
	// DocumentRowLocatorNanos attributes row-locator map build time.
	DocumentRowLocatorNanos uint64 `json:"document_row_locator_nanos,omitempty"`
	// DocumentPointRowFetches counts direct row-ref point fetch attempts.
	DocumentPointRowFetches uint64 `json:"document_point_row_fetches,omitempty"`
	// DocumentPointRowDecodes counts physical rows decoded by direct row-ref point fetch.
	DocumentPointRowDecodes uint64 `json:"document_point_row_decodes,omitempty"`
	// DocumentRowRefFallbackScans counts row-ref requests served by an explicit scan fallback.
	DocumentRowRefFallbackScans uint64 `json:"document_row_ref_fallback_scans,omitempty"`
	// DocumentRowRefUnsupported counts unsupported row-ref materialization states.
	DocumentRowRefUnsupported uint64 `json:"document_row_ref_unsupported,omitempty"`
	// DocumentRowRefValidationFailures counts row-ref fail-closed validation failures.
	DocumentRowRefValidationFailures uint64 `json:"document_row_ref_validation_failures,omitempty"`
	// DocumentAssetMmapHits counts document materializer typed-row/typed-column asset reads served from mmap-backed views.
	DocumentAssetMmapHits uint64 `json:"document_asset_mmap_hits,omitempty"`
	// DocumentAssetReadAtFallbacks counts document materializer asset reads that fell back to heap/read-at.
	DocumentAssetReadAtFallbacks uint64 `json:"document_asset_readat_fallbacks,omitempty"`
	// DocumentAssetFileOpens counts materializer asset segment file opens.
	DocumentAssetFileOpens uint64 `json:"document_asset_file_opens,omitempty"`
	// DocumentAssetFileCloses counts materializer asset segment file closes.
	DocumentAssetFileCloses uint64 `json:"document_asset_file_closes,omitempty"`
	// DocumentAssetActiveHandles is the current active mappedresource handle count held by the materializer read view.
	DocumentAssetActiveHandles int64 `json:"document_asset_active_handles,omitempty"`

	// RowFetches is the per-search count of physical row-reader fetch calls.
	RowFetches uint64 `json:"row_fetches,omitempty"`
	// BatchFetches is the per-search count of physical row-reader batch fetch calls.
	BatchFetches uint64 `json:"batch_fetches,omitempty"`
	// RowsFetched is the per-search number of rows returned by physical reader fetches.
	RowsFetched uint64 `json:"rows_fetched,omitempty"`
	// CacheHits is the per-search count of decoded-block cache hits.
	CacheHits uint64 `json:"cache_hits,omitempty"`
	// CacheMisses is the per-search count of decoded-block cache misses.
	CacheMisses uint64 `json:"cache_misses,omitempty"`
	// DecodedBlocks is the per-search count of column blocks decoded after a miss.
	DecodedBlocks uint64 `json:"decoded_blocks,omitempty"`
	// GranulesTouched is the per-search count of physical granules touched.
	GranulesTouched uint64 `json:"granules_touched,omitempty"`
	// PhysicalBytesRead is the per-search physical byte read delta.
	PhysicalBytesRead int64 `json:"physical_bytes_read,omitempty"`
	// MaxResidentBytes is the reader's absolute high-water resident decoded bytes.
	MaxResidentBytes int64 `json:"max_resident_bytes,omitempty"`

	// OpenGranulesRead is the absolute granule count read while opening the bound reader.
	OpenGranulesRead uint64 `json:"open_granules_read,omitempty"`
	// OpenPhysicalBytesRead is the absolute physical byte count read while opening the bound reader.
	OpenPhysicalBytesRead int64 `json:"open_physical_bytes_read,omitempty"`

	// VectorDirectViews is a legacy alias for candidate vectors served from certified mmap direct views.
	VectorDirectViews uint64 `json:"vector_direct_views,omitempty"`
	// VectorMmapDirectViews is the per-search count of candidate vectors served from certified zero-copy mmap direct views.
	VectorMmapDirectViews uint64 `json:"vector_mmap_direct,omitempty"`
	// VectorHeapCopyTypedViews is the per-search count of candidate vectors served from typed views over heap-copy fallback buffers.
	VectorHeapCopyTypedViews uint64 `json:"vector_heap_copy_typed_view,omitempty"`
	// VectorScratchDecodes is the per-search count of candidate vectors served from scratch/fallback decoded vectors.
	VectorScratchDecodes uint64 `json:"vector_scratch_decodes,omitempty"`
	// VectorPreparedDirectViews counts candidate vectors served through the #2040 prepared direct scoring view.
	VectorPreparedDirectViews uint64 `json:"vector_prepared_direct,omitempty"`
	// VectorPreparedIdentityMappings counts prepared vector reads where graph ordinal equals base vector row index.
	VectorPreparedIdentityMappings uint64 `json:"vector_prepared_identity_mapping,omitempty"`
	// VectorPreparedRowRefMappings counts prepared vector reads using an ordinal-to-base-row map.
	VectorPreparedRowRefMappings uint64 `json:"vector_prepared_row_ref_mapping,omitempty"`
	// VectorCertificationFailures counts reason-specific vector source failures that are treated as certification/fail-closed fallbacks.
	VectorCertificationFailures uint64 `json:"vector_certification_failures,omitempty"`
	// VectorAbsoluteOffsetUnaligned counts typed-column vector fallback observations caused by absolute storage offset misalignment.
	VectorAbsoluteOffsetUnaligned uint64 `json:"vector_absolute_offset_unaligned,omitempty"`
	// VectorActualPointerUnaligned counts typed-column vector fallback observations caused by actual Go pointer misalignment.
	VectorActualPointerUnaligned uint64 `json:"vector_actual_pointer_unaligned,omitempty"`
	// VectorStaleHandles counts typed-column vector fallback observations caused by released/stale handles.
	VectorStaleHandles uint64 `json:"vector_stale_handles,omitempty"`
	// AdjacencyDirectViews is a legacy alias for adjacency payloads served from certified mmap direct views.
	AdjacencyDirectViews uint64 `json:"adjacency_direct_views,omitempty"`
	// AdjacencyMmapDirectViews is the per-search count of adjacency payloads served from certified zero-copy mmap direct views.
	AdjacencyMmapDirectViews uint64 `json:"adjacency_mmap_direct,omitempty"`
	// AdjacencyHeapCopyTypedViews is the per-search count of adjacency payloads served from typed heap-copy fallback views.
	AdjacencyHeapCopyTypedViews uint64 `json:"adjacency_heap_copy_typed_view,omitempty"`
	// AdjacencyPreparedCSRDirectViews is the per-search count of HNSW adjacency neighbor slices served from prepared CSR direct views.
	AdjacencyPreparedCSRDirectViews uint64 `json:"adjacency_prepared_csr_direct_views,omitempty"`
	// AdjacencyPreparedCSRMmapDirectViews is the per-search count of HNSW adjacency neighbor slices served from prepared CSR mmap direct views.
	AdjacencyPreparedCSRMmapDirectViews uint64 `json:"adjacency_prepared_csr_mmap_direct,omitempty"`
	// AdjacencyTypedListDirectViews is the per-search count of vector-index state uint32_list adjacency payloads served from generic direct typed-list views.
	AdjacencyTypedListDirectViews uint64 `json:"adjacency_typed_list_direct_views,omitempty"`
	// AdjacencyTypedListMmapDirectViews is the per-search count of vector-index state uint32_list adjacency payloads served from mmap direct views.
	AdjacencyTypedListMmapDirectViews uint64 `json:"adjacency_typed_list_mmap_direct,omitempty"`
	// AdjacencyTypedListHeapCopyTypedViews is the per-search count of vector-index state uint32_list adjacency payloads served from heap-copy typed views.
	AdjacencyTypedListHeapCopyTypedViews uint64 `json:"adjacency_typed_list_heap_copy_typed_view,omitempty"`
	// AdjacencyTypedListScratchDecodes is the per-search count of vector-index state uint32_list adjacency payloads served from decoded fallback views.
	AdjacencyTypedListScratchDecodes uint64 `json:"adjacency_typed_list_scratch_decodes,omitempty"`
	// AdjacencyLegacyFallbacks counts row-image graph adjacency fallback/quarantine reads.
	AdjacencyLegacyFallbacks uint64 `json:"adjacency_legacy_fallbacks,omitempty"`
	// AdjacencySourceUnavailable reports that this searcher had no usable certified adjacency source.
	AdjacencySourceUnavailable uint64 `json:"adjacency_source_unavailable,omitempty"`
	// AdjacencySourceFallbacks reports searches or observations that fell back from certified adjacency sources to legacy rows or fail-closed fallback handling.
	AdjacencySourceFallbacks uint64 `json:"adjacency_source_fallbacks,omitempty"`
	// AdjacencyCertificationFailures counts adjacency source certification, shape, or validation failures.
	AdjacencyCertificationFailures uint64 `json:"adjacency_certification_failures,omitempty"`
	// AdjacencyValidationFailures counts typed-list adjacency validation failures.
	AdjacencyValidationFailures uint64 `json:"adjacency_validation_failures,omitempty"`
	// AdjacencyAbsoluteOffsetUnaligned counts adjacency source fallbacks caused by absolute storage offset misalignment.
	AdjacencyAbsoluteOffsetUnaligned uint64 `json:"adjacency_absolute_offset_unaligned,omitempty"`
	// AdjacencyActualPointerUnaligned counts adjacency source fallbacks caused by actual mapped pointer misalignment.
	AdjacencyActualPointerUnaligned uint64 `json:"adjacency_actual_pointer_unaligned,omitempty"`
	// AdjacencyStaleHandles counts adjacency source fallbacks caused by released/stale mappedresource handles.
	AdjacencyStaleHandles uint64 `json:"adjacency_stale_handles,omitempty"`
	// AdjacencyScratchDecodes is the per-search count of adjacency payloads served from scratch/fallback decodes.
	AdjacencyScratchDecodes uint64 `json:"adjacency_scratch_decodes,omitempty"`
	// NormDirectViews is a legacy alias for inverse norms served from certified mmap direct views.
	NormDirectViews uint64 `json:"norm_direct_views,omitempty"`
	// NormMmapDirectViews is the per-search count of inverse norms served from certified zero-copy mmap direct views.
	NormMmapDirectViews uint64 `json:"norm_mmap_direct,omitempty"`
	// NormHeapCopyTypedViews is the per-search count of inverse norms served from typed heap-copy fallback views.
	NormHeapCopyTypedViews uint64 `json:"norm_heap_copy_typed_view,omitempty"`
	// NormScratchDecodes is the per-search count of inverse norms served from scratch/fallback decoded state.
	NormScratchDecodes uint64 `json:"norm_scratch_decodes,omitempty"`
	// NormPreparedDirectViews counts inverse norms served through the #2040 prepared direct scoring view.
	NormPreparedDirectViews uint64 `json:"norm_prepared_direct,omitempty"`
	// NormSourceUnavailable reports that this searcher had no usable inverse-norm state source and used graph-row fallback.
	NormSourceUnavailable uint64 `json:"norm_source_unavailable,omitempty"`
	// NormSourceFallbacks reports searches or observations that fell back from inverse-norm state to legacy rows or fail-closed fallback handling.
	NormSourceFallbacks uint64 `json:"norm_source_fallbacks,omitempty"`
	// NormValidationFailures counts inverse-norm state source certification, shape, or validation failures.
	NormValidationFailures uint64 `json:"norm_validation_failures,omitempty"`
	// NormAbsoluteOffsetUnaligned counts inverse-norm state fallbacks caused by absolute storage offset misalignment.
	NormAbsoluteOffsetUnaligned uint64 `json:"norm_absolute_offset_unaligned,omitempty"`
	// NormActualPointerUnaligned counts inverse-norm state fallbacks caused by actual mapped pointer misalignment.
	NormActualPointerUnaligned uint64 `json:"norm_actual_pointer_unaligned,omitempty"`
	// NormStaleHandles counts inverse-norm state fallbacks caused by released/stale mappedresource handles.
	NormStaleHandles uint64 `json:"norm_stale_handles,omitempty"`
	// NormMappedBytes is the mapped-resource mapped byte total backing the bound inverse-norm state source.
	NormMappedBytes uint64 `json:"norm_mapped_bytes,omitempty"`
	// NormHeapCopyBytes is the mapped-resource heap-copy byte total backing the bound inverse-norm state source.
	NormHeapCopyBytes uint64 `json:"norm_heap_copy_bytes,omitempty"`
	// NormDecodedBytes is decoded fallback inverse-norm state bytes held by the bound source.
	NormDecodedBytes uint64 `json:"norm_decoded_bytes,omitempty"`
	// NormActiveHandles is the current active mappedresource handle count for inverse-norm state views.
	NormActiveHandles int64 `json:"norm_active_handles,omitempty"`
	// NormDeniedResources is the total denied mappedresource acquisition count for the inverse-norm state source.
	NormDeniedResources uint64 `json:"norm_denied_resources,omitempty"`
	// TypedColumnMappedBytes is the typed-column mapped-resource mapped byte total backing the bound vector source.
	TypedColumnMappedBytes uint64 `json:"typed_column_mapped_bytes,omitempty"`
	// TypedColumnHeapCopyBytes is the typed-column mapped-resource heap-copy byte total backing the bound vector source.
	TypedColumnHeapCopyBytes uint64 `json:"typed_column_heap_copy_bytes,omitempty"`
	// TypedColumnDecodedBytes is decoded/derived typed-column metadata or fallback vector bytes for the bound vector source.
	TypedColumnDecodedBytes uint64 `json:"typed_column_decoded_bytes,omitempty"`
	// TypedColumnActiveHandles is the current active mappedresource handle count for direct typed-column vector views.
	TypedColumnActiveHandles int64 `json:"typed_column_active_handles,omitempty"`
	// TypedColumnDeniedResources is the total denied mappedresource acquisition count for the typed-column vector source.
	TypedColumnDeniedResources uint64 `json:"typed_column_denied_resources,omitempty"`
	// TypedColumnFallbacks reports that typed-column vector ownership was selected but the reader fell back to graph row vectors.
	TypedColumnFallbacks uint64 `json:"typed_column_fallbacks,omitempty"`
	// RowRefVectorSourceState reports searches whose typed-column vector locator map came from vector-index row-ref state.
	RowRefVectorSourceState uint64 `json:"row_ref_vector_source_state,omitempty"`
	// RowRefVectorSourceLegacyGraphIDs reports searches whose typed-column vector locator map used legacy graph row ID scans.
	RowRefVectorSourceLegacyGraphIDs uint64 `json:"row_ref_vector_source_legacy_graph_ids,omitempty"`
	// RowRefStatePreparedViews reports searches with an open-time certified prepared row-ref view bound to the searcher.
	RowRefStatePreparedViews uint64 `json:"row_ref_state_prepared_views,omitempty"`
	// RowRefStateMmapDirectFields counts row-ref coordinate fields admitted as mmap-direct prepared int64 views.
	RowRefStateMmapDirectFields uint64 `json:"row_ref_state_mmap_direct_fields,omitempty"`
	// RowRefStateResultRefs counts top-k result row refs served from vector-index row-ref state.
	RowRefStateResultRefs uint64 `json:"row_ref_state_result_refs,omitempty"`
	// RowRefStateSourceUnavailable reports that row-ref state was absent and compatibility source selection was used.
	RowRefStateSourceUnavailable uint64 `json:"row_ref_state_source_unavailable,omitempty"`
	// RowRefStateSourceFallbacks reports row-ref source fallback/quarantine observations.
	RowRefStateSourceFallbacks uint64 `json:"row_ref_state_source_fallbacks,omitempty"`
	// ResultIDPreparedBytesViews reports searches with an open-time certified prepared document-ID bytes view bound to the searcher.
	ResultIDPreparedBytesViews uint64 `json:"result_id_prepared_bytes_views,omitempty"`
	// ResultIDTypedBytesState counts returned document IDs copied from vector-index typed-column bytes state.
	ResultIDTypedBytesState uint64 `json:"result_id_typed_bytes_state,omitempty"`
	// ResultIDGraphFallbacks counts returned document IDs copied from legacy graph row ID bytes.
	ResultIDGraphFallbacks uint64 `json:"result_id_graph_fallbacks,omitempty"`
	// ResultIDStateValidationFailures counts searches that fell back because present document-ID state failed validation.
	ResultIDStateValidationFailures uint64 `json:"result_id_state_validation_failures,omitempty"`
	// PreparedGraphSearchViews reports searches routed through the combined open-time prepared typed-column graph-search view.
	PreparedGraphSearchViews uint64 `json:"prepared_graph_search_views,omitempty"`
	// GraphRowFallbacks aggregates compatibility graph-row reads/fallbacks observed during vector/norm/adjacency/result materialization.
	GraphRowFallbacks uint64 `json:"graph_row_fallbacks,omitempty"`

	// SearchRouteColumnGraphPrepared reports that this search used the current prepared column_graph route.
	SearchRouteColumnGraphPrepared uint64 `json:"search_route_column_graph_prepared,omitempty"`
	// SearchRouteColumnGraphFallback reports that this search used the column_graph compatibility/fallback route instead of the prepared route.
	SearchRouteColumnGraphFallback uint64 `json:"search_route_column_graph_fallback,omitempty"`
	// SearchRouteHNSWSearchPack reports that this search used the exact FP32 hnsw_search_pack_v1 route.
	SearchRouteHNSWSearchPack uint64 `json:"search_route_hnsw_search_pack,omitempty"`
	// SearchRouteQuantizedOnly reports that this search used the codec-generic quantized-only route.
	SearchRouteQuantizedOnly uint64 `json:"search_route_quantized_only,omitempty"`
	// SearchRouteQuantizedRerank reports that this search used the codec-generic quantized-rerank route.
	SearchRouteQuantizedRerank uint64 `json:"search_route_quantized_rerank,omitempty"`
	// HNSWSearchPackActive reports that a validated hnsw_search_pack_v1 served this search.
	HNSWSearchPackActive uint64 `json:"hnsw_search_pack_active,omitempty"`
	// HNSWSearchPackMissing reports that no hnsw_search_pack_v1 was available for this searcher.
	HNSWSearchPackMissing uint64 `json:"hnsw_search_pack_missing,omitempty"`
	// HNSWSearchPackInvalid reports that a hnsw_search_pack_v1 candidate was present but failed validation.
	HNSWSearchPackInvalid uint64 `json:"hnsw_search_pack_invalid,omitempty"`
	// HNSWSearchPackStale reports that a previously opened hnsw_search_pack_v1 handle is no longer live.
	HNSWSearchPackStale uint64 `json:"hnsw_search_pack_stale,omitempty"`
	// HNSWSearchPackClosed reports that the bound hnsw_search_pack_v1 view is closed.
	HNSWSearchPackClosed uint64 `json:"hnsw_search_pack_closed,omitempty"`
	// HNSWSearchPackFallbacks reports searches that fell back from hnsw_search_pack_v1 to an existing route.
	HNSWSearchPackFallbacks uint64 `json:"hnsw_search_pack_fallbacks,omitempty"`
	// HNSWSearchPackMmapDirect reports searches with a validated direct mmap hnsw_search_pack_v1 view bound to the searcher.
	HNSWSearchPackMmapDirect uint64 `json:"hnsw_search_pack_mmap_direct,omitempty"`
	// HNSWSearchPackHeapCopy reports searches with a validated heap-copy hnsw_search_pack_v1 view bound to the searcher.
	HNSWSearchPackHeapCopy uint64 `json:"hnsw_search_pack_heap_copy,omitempty"`
	// HNSWSearchPackOpenNanos reports the open/prepared-view time for the bound hnsw_search_pack_v1 view.
	HNSWSearchPackOpenNanos uint64 `json:"hnsw_search_pack_open_nanos,omitempty"`
	// HNSWSearchPackMappedBytes is the active mapped byte total backing the bound hnsw_search_pack_v1 view.
	HNSWSearchPackMappedBytes uint64 `json:"hnsw_search_pack_mapped_bytes,omitempty"`
	// HNSWSearchPackHeapCopyBytes is the active heap-copy byte total backing the bound hnsw_search_pack_v1 view.
	HNSWSearchPackHeapCopyBytes uint64 `json:"hnsw_search_pack_heap_copy_bytes,omitempty"`
	// HNSWSearchPackActiveHandles is the current active mappedresource handle count for the hnsw_search_pack_v1 view.
	HNSWSearchPackActiveHandles int64 `json:"hnsw_search_pack_active_handles,omitempty"`
	// HNSWSearchPackCacheHits reports collection-level prepared hnsw_search_pack_v1 cache hits for this public search call.
	HNSWSearchPackCacheHits uint64 `json:"hnsw_search_pack_cache_hits,omitempty"`
	// HNSWSearchPackCacheMisses reports collection-level prepared hnsw_search_pack_v1 cache misses/build admissions for this public search call.
	HNSWSearchPackCacheMisses uint64 `json:"hnsw_search_pack_cache_misses,omitempty"`
	// HNSWSearchPackCacheWaits reports waits behind an in-flight collection-level hnsw_search_pack_v1 cache build for this public search call.
	HNSWSearchPackCacheWaits uint64 `json:"hnsw_search_pack_cache_waits,omitempty"`
	// HNSWSearchPackCacheBuilds reports collection-level prepared hnsw_search_pack_v1 cache builds started by this public search call.
	HNSWSearchPackCacheBuilds uint64 `json:"hnsw_search_pack_cache_builds,omitempty"`
	// OpenSearcherCalls reports collection-level SearchVectorIndex calls that entered the one-shot VectorIndexSearcher open/setup boundary.
	OpenSearcherCalls uint64 `json:"open_searcher_calls,omitempty"`
	// OpenSetupInTimedLoop reports collection-level SearchVectorIndex calls whose one-shot open/setup work is part of the call boundary.
	OpenSetupInTimedLoop uint64 `json:"open_setup_in_timed_loop,omitempty"`
	// ResponseOwnedResultAllocs reports response-owned result storage creation by Search or SearchVectorIndex. Buffered APIs leave this zero.
	ResponseOwnedResultAllocs uint64 `json:"response_owned_result_allocs,omitempty"`

	// BenchmarkDebugSearches reports searches collected with benchmark_debug graph-control-flow instrumentation.
	BenchmarkDebugSearches uint64 `json:"benchmark_debug_searches,omitempty"`
	// NeighborTiles counts expanded adjacency neighbor tiles.
	NeighborTiles uint64 `json:"neighbor_tiles,omitempty"`
	// NeighborTileNeighbors sums neighbor counts across expanded adjacency tiles.
	NeighborTileNeighbors uint64 `json:"neighbor_tile_neighbors,omitempty"`
	// NeighborTileMaxSize is the largest expanded adjacency tile.
	NeighborTileMaxSize    uint64 `json:"neighbor_tile_max_size,omitempty"`
	NeighborTileSize0      uint64 `json:"neighbor_tile_size_0,omitempty"`
	NeighborTileSize1      uint64 `json:"neighbor_tile_size_1,omitempty"`
	NeighborTileSize2To4   uint64 `json:"neighbor_tile_size_2_4,omitempty"`
	NeighborTileSize5To8   uint64 `json:"neighbor_tile_size_5_8,omitempty"`
	NeighborTileSize9To16  uint64 `json:"neighbor_tile_size_9_16,omitempty"`
	NeighborTileSize17Plus uint64 `json:"neighbor_tile_size_17_plus,omitempty"`
	// ScoreBatchSingletons counts singleton scoring batches in benchmark_debug mode.
	ScoreBatchSingletons uint64 `json:"score_batch_singletons,omitempty"`
	ScoreBatchSize2To4   uint64 `json:"score_batch_size_2_4,omitempty"`
	ScoreBatchSize5To8   uint64 `json:"score_batch_size_5_8,omitempty"`
	ScoreBatchSize9To16  uint64 `json:"score_batch_size_9_16,omitempty"`
	ScoreBatchSize17Plus uint64 `json:"score_batch_size_17_plus,omitempty"`
	// ScoredNeighbors counts graph neighbors that reached scoring; skipped neighbors partition filter and already-visited skips.
	ScoredNeighbors                       uint64 `json:"scored_neighbors,omitempty"`
	SkippedNeighbors                      uint64 `json:"skipped_neighbors,omitempty"`
	AlreadyVisitedSkips                   uint64 `json:"already_visited_skips,omitempty"`
	FilterSkips                           uint64 `json:"filter_skips,omitempty"`
	UpperLayerScores                      uint64 `json:"upper_layer_scores,omitempty"`
	UpperLayerEntryScores                 uint64 `json:"upper_layer_entry_scores,omitempty"`
	UpperLayerNeighborScores              uint64 `json:"upper_layer_neighbor_scores,omitempty"`
	UpperLayerScoreTiles                  uint64 `json:"upper_layer_score_tiles,omitempty"`
	UpperLayerScoreTileCandidates         uint64 `json:"upper_layer_score_tile_candidates,omitempty"`
	UpperLayerScoreTileMaxSize            uint64 `json:"upper_layer_score_tile_max_size,omitempty"`
	UpperLayerAdjacencyLoads              uint64 `json:"upper_layer_adjacency_loads,omitempty"`
	UpperLayerAdjacencyNeighbors          uint64 `json:"upper_layer_adjacency_neighbors,omitempty"`
	UpperLayerEdgeVisits                  uint64 `json:"upper_layer_edge_visits,omitempty"`
	UpperLayerScoredNeighbors             uint64 `json:"upper_layer_scored_neighbors,omitempty"`
	UpperLayerFilterSkips                 uint64 `json:"upper_layer_filter_skips,omitempty"`
	Layer0Scores                          uint64 `json:"layer0_scores,omitempty"`
	Layer0SeedScores                      uint64 `json:"layer0_seed_scores,omitempty"`
	Layer0NeighborScores                  uint64 `json:"layer0_neighbor_scores,omitempty"`
	Layer0ScoreTiles                      uint64 `json:"layer0_score_tiles,omitempty"`
	Layer0ScoreTileCandidates             uint64 `json:"layer0_score_tile_candidates,omitempty"`
	Layer0ScoreTileMaxSize                uint64 `json:"layer0_score_tile_max_size,omitempty"`
	Layer0AdjacencyLoads                  uint64 `json:"layer0_adjacency_loads,omitempty"`
	Layer0AdjacencyNeighbors              uint64 `json:"layer0_adjacency_neighbors,omitempty"`
	Layer0EdgeVisits                      uint64 `json:"layer0_edge_visits,omitempty"`
	Layer0ScoredNeighbors                 uint64 `json:"layer0_scored_neighbors,omitempty"`
	Layer0AlreadyVisitedSkips             uint64 `json:"layer0_already_visited_skips,omitempty"`
	Layer0FilterSkips                     uint64 `json:"layer0_filter_skips,omitempty"`
	Layer0StopChecks                      uint64 `json:"layer0_stop_checks,omitempty"`
	Layer0StopTrue                        uint64 `json:"layer0_stop_true,omitempty"`
	Layer0StopFalse                       uint64 `json:"layer0_stop_false,omitempty"`
	CandidateComparisons                  uint64 `json:"candidate_comparisons,omitempty"`
	FrontierComparisons                   uint64 `json:"frontier_comparisons,omitempty"`
	TopKComparisons                       uint64 `json:"top_k_comparisons,omitempty"`
	FrontierPushes                        uint64 `json:"frontier_pushes,omitempty"`
	FrontierPops                          uint64 `json:"frontier_pops,omitempty"`
	HeapPushes                            uint64 `json:"heap_pushes,omitempty"`
	HeapPops                              uint64 `json:"heap_pops,omitempty"`
	FrontierPopMisses                     uint64 `json:"frontier_pop_misses,omitempty"`
	FrontierSiftUpCalls                   uint64 `json:"frontier_sift_up_calls,omitempty"`
	FrontierSiftDownCalls                 uint64 `json:"frontier_sift_down_calls,omitempty"`
	FrontierSiftUpSteps                   uint64 `json:"frontier_sift_up_steps,omitempty"`
	FrontierSiftDownSteps                 uint64 `json:"frontier_sift_down_steps,omitempty"`
	TopKInsertAttempts                    uint64 `json:"top_k_insert_attempts,omitempty"`
	TopKInsertSuccesses                   uint64 `json:"top_k_insert_successes,omitempty"`
	TopKInsertRejections                  uint64 `json:"top_k_insert_rejections,omitempty"`
	TopKShiftSteps                        uint64 `json:"top_k_shift_steps,omitempty"`
	VisitedMarkChecks                     uint64 `json:"visited_mark_checks,omitempty"`
	VisitedMarkHits                       uint64 `json:"visited_mark_hits,omitempty"`
	VisitedMarkMisses                     uint64 `json:"visited_mark_misses,omitempty"`
	VisitedMarkInserts                    uint64 `json:"visited_mark_inserts,omitempty"`
	VisitedResetEpochAdvances             uint64 `json:"visited_reset_epoch_advances,omitempty"`
	VisitedResetClearedRows               uint64 `json:"visited_reset_cleared_rows,omitempty"`
	ExactModeSearches                     uint64 `json:"exact_mode_searches,omitempty"`
	ExactCandidateOrderObservations       uint64 `json:"exact_candidate_order_observations,omitempty"`
	ExactCandidateOrderTransitions        uint64 `json:"exact_candidate_order_transitions,omitempty"`
	ExactCandidateOrderAdjacentForward    uint64 `json:"exact_candidate_order_adjacent_forward,omitempty"`
	ExactCandidateOrderNonAdjacentForward uint64 `json:"exact_candidate_order_non_adjacent_forward,omitempty"`
	ExactCandidateOrderBackwardJumps      uint64 `json:"exact_candidate_order_backward_jumps,omitempty"`
	ExactCandidateOrderMaxForwardRun      uint64 `json:"exact_candidate_order_max_forward_run,omitempty"`
	// WorkAccountingSearches reports that this search collected explicit work-accounting counters/timers.
	WorkAccountingSearches uint64 `json:"work_accounting_searches,omitempty"`
	// DistanceKernelNanos attributes query-local candidate scoring time to exact/quantized distance kernels.
	DistanceKernelNanos uint64 `json:"distance_kernel_nanos,omitempty"`
	// GraphTraversalNanos attributes HNSW traversal wall time excluding recorded distance-kernel time.
	GraphTraversalNanos uint64 `json:"graph_traversal_nanos,omitempty"`
	// ServiceResponseNanos attributes document-service response construction after collection search.
	ServiceResponseNanos uint64 `json:"service_response_nanos,omitempty"`
	// DocumentRowRefStateFetches counts post-top-k document fetches served with vector-index row-ref state.
	DocumentRowRefStateFetches uint64 `json:"document_row_ref_state_fetches,omitempty"`
	// DocumentRowRefLookupFallbacks counts post-top-k document fetches that fell back to ID-to-row-ref lookup.
	DocumentRowRefLookupFallbacks uint64 `json:"document_row_ref_lookup_fallbacks,omitempty"`
}

VectorIndexSearchStats reports search telemetry. Graph/search and reader counters are per-search deltas unless the field starts with Open; Open* counters describe bound reader setup performed before Search or collection-level one-shot open/setup performed inside SearchVectorIndex.

func (VectorIndexSearchStats) Diagnostics 

func (s VectorIndexSearchStats) Diagnostics() VectorIndexSearchDiagnostics

Diagnostics returns a compact route/status summary derived from the stats.

func (VectorIndexSearchStats) ExactHNSWSearchPackNoDocumentRoute 

func (s VectorIndexSearchStats) ExactHNSWSearchPackNoDocumentRoute() bool

ExactHNSWSearchPackNoDocumentRoute reports the exact FP32 no-document pack route guardrail.

func (VectorIndexSearchStats) FallbackReason 

func (s VectorIndexSearchStats) FallbackReason() VectorIndexSearchFallbackReason

FallbackReason reports the first low-cardinality fallback reason visible in stats.

func (VectorIndexSearchStats) HNSWSearchPackStatus 

func (s VectorIndexSearchStats) HNSWSearchPackStatus() VectorIndexSearchHNSWSearchPackStatus

HNSWSearchPackStatus reports exact hnsw_search_pack_v1 health for this search.

func (VectorIndexSearchStats) NoDocumentGuardrailsOK 

func (s VectorIndexSearchStats) NoDocumentGuardrailsOK() bool

NoDocumentGuardrailsOK reports whether shared no-document guardrail counters are clear.

func (VectorIndexSearchStats) RouteKind 

func (s VectorIndexSearchStats) RouteKind() VectorIndexSearchRouteKind

RouteKind reports the low-cardinality route selected for this search.

type VectorIndexSearchStatsMode 

type VectorIndexSearchStatsMode string

VectorIndexSearchStatsMode selects how much vector graph-search telemetry is collected. The zero value preserves full diagnostics for compatibility. Production/minimal mode is the steady-state low-overhead mode: it keeps source-health, admission, result, and fallback counters while avoiding per-edge/per-candidate diagnostic counters on the healthy prepared path. Work-accounting mode is an explicit diagnostic mode for explaining per-query search cost; do not mix it into low-overhead production throughput evidence. 

const (
	VectorIndexSearchStatsModeDefault         VectorIndexSearchStatsMode = ""
	VectorIndexSearchStatsModeMinimal         VectorIndexSearchStatsMode = "minimal"
	VectorIndexSearchStatsModeProduction      VectorIndexSearchStatsMode = "production"
	VectorIndexSearchStatsModeFullDiagnostics VectorIndexSearchStatsMode = "full_diagnostics"
	VectorIndexSearchStatsModeWorkAccounting  VectorIndexSearchStatsMode = "work_accounting"
	VectorIndexSearchStatsModeBenchmarkDebug  VectorIndexSearchStatsMode = "benchmark_debug"
)

type VectorIndexSearcher 

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

VectorIndexSearcher is a reusable, snapshot-bound vector index search handle. It is not concurrency-safe; parallel query workers should open independent searchers/buffers. Current-format column_graph searchers opened over the same immutable generation share prepared mmap/resource views internally, so worker isolation applies to mutable scratch/result buffers rather than immutable typed-column assets. Close and reopen the searcher after writes/rebuilds when callers need the newest column_graph generation.

func (*VectorIndexSearcher) Close 

func (s *VectorIndexSearcher) Close() error

Close releases the searcher's bound physical reader and snapshot.

func (*VectorIndexSearcher) Search 

func (s *VectorIndexSearcher) Search(opts VectorIndexSearcherSearchOptions) (VectorIndexSearchResponse, error)

Search runs one vector-index query against the searcher's bound snapshot. Returned result IDs and documents are copied into response-owned buffers.

func (*VectorIndexSearcher) SearchWithBuffer 

func (s *VectorIndexSearcher) SearchWithBuffer(opts VectorIndexSearcherSearchOptions, buffer *VectorIndexSearchBuffer) (VectorIndexSearchResponse, error)

SearchWithBuffer runs one no-document vector-index query against the searcher's bound snapshot using caller-owned reusable response storage. Returned result slices and result IDs alias buffer and are valid only until buffer is reused or Reset is called. The same buffer must not be reused concurrently; parallel callers should use independent searcher/buffer pairs per worker. IncludeDocuments is not supported by this reusable no-document path.

The high-QPS exact public contract for this path is exact/zero QueryMode with no document projection and no document materialization. Healthy exact current-format evidence should show hnsw_search_pack_v1 active and selected, zero document fetches, zero graph-row fallback, zero typed-column vector fallback, and zero vector scratch decodes. Explicit quantized modes use the column_graph quantized scorer route; rabitq_1bit uses the prepared hnsw_search_pack_v1 score-plane traversal when eligible. Quantized modes must fail closed with quantized_* asset counters when the selected score plane is unavailable.

On any error after a non-nil buffer is supplied, the buffer's reusable result/id views are reset to length zero and the returned response has no Results. Search metadata and any telemetry collected before the error may still be present in the returned response.

type VectorIndexSearcherOptions 

type VectorIndexSearcherOptions struct {
	// IndexName is the declared collection vector-index name.
	IndexName string
	// MaxDecodedBlocks bounds the generic physical column reader cache used by
	// the column_graph path. Zero uses the reader default.
	MaxDecodedBlocks int
}

VectorIndexSearcherOptions configures a reusable snapshot-bound vector-index searcher. Reuse this path for steady-state queries when setup/open cost should not be paid on every search.

type VectorIndexSearcherSearchOptions 

type VectorIndexSearcherSearchOptions struct {
	// Query is the query vector. V4 column_graph search supports cosine indexes.
	Query []float32
	// QueryMode selects exact, quantized-only, or quantized-rerank search. The
	// zero value is exact; quantized modes require QuantizedIndexName and fail
	// closed until matching assets/scorers are available.
	QueryMode VectorIndexQueryMode
	// QuantizedIndexName selects the named derived score plane for quantized modes.
	QuantizedIndexName string
	// QuantizedRerankCandidates bounds the quantized candidate set reranked by
	// exact float32 vectors in quantized_rerank mode. Zero uses the normalized
	// ef_search candidate set.
	QuantizedRerankCandidates int
	// TopK is the maximum number of nearest results to return.
	TopK int
	// EfSearch bounds graph exploration. Zero uses the persisted index default.
	EfSearch int
	// IncludeDocuments materializes documents after top-k selection.
	IncludeDocuments bool
	// DocumentFetchOptions controls optional projected final-fetch materialization.
	// It is used only when IncludeDocuments is true; the zero value returns full documents.
	DocumentFetchOptions DocumentFetchOptions
	// StatsMode selects graph-search telemetry detail. The zero value preserves
	// full diagnostics; production/minimal mode avoids per-candidate/per-edge
	// diagnostic accounting on the healthy combined prepared path while still
	// reporting source-health, fallback, admission, and result counters.
	StatsMode VectorIndexSearchStatsMode
	// contains filtered or unexported fields
}

VectorIndexSearcherSearchOptions configures one Search call on an opened VectorIndexSearcher.

type VectorIndexState 

type VectorIndexState string
const (
	VectorIndexStateNativeRuntime            VectorIndexState = "native_runtime"
	VectorIndexStateColumnGraphLoaded        VectorIndexState = "column_graph_loaded"
	VectorIndexStateColumnGraphUnavailable   VectorIndexState = "column_graph_unavailable"
	VectorIndexStateColumnGraphRebuildNeeded VectorIndexState = "column_graph_rebuild_needed"
)

type VectorIndexStats 

type VectorIndexStats struct {
	Name                string
	Field               string
	Metric              VectorMetric
	Encoding            VectorIndexEncoding
	Dimensions          int
	M                   int
	EfConstruction      int
	EfSearch            int
	Nodes               int
	LiveDocs            int
	DeletedDocs         int
	DeletedRatio        float64
	BytesMemory         int64
	BytesDisk           int64
	AvgDegree           float64
	MaxLevel            int
	Epoch               uint64
	SnapshotDirty       bool
	LastRebuildDuration time.Duration
	RebuildNeeded       bool
}

VectorIndexStats reports process-local in-memory vector index state.

type VectorIndexStatus 

type VectorIndexStatus struct {
	Definition          VectorIndexDefinition
	Name                string
	Strategy            VectorIndexStrategy
	State               VectorIndexState
	Reason              VectorIndexReason
	Loaded              bool
	RootName            string
	RootID              uint64
	NativeRootLoaded    bool
	NativeRootBytes     int64
	ExactFallbackReason string
	Registered          bool
	Stats               VectorIndexStats
	RebuildNeeded       bool
	Duration            time.Duration
}

VectorIndexStatus reports the operational state of one declared collection vector index. Status checks may inspect the persisted graph root and are intended for operational paths, not search hot paths.

type VectorIndexStrategy 

type VectorIndexStrategy string
const (
	VectorIndexStrategyNativeRuntime VectorIndexStrategy = "native_runtime"
	// VectorIndexStrategyColumnGraph selects the physical column-store graph path.
	// Until graph assets are built and published, status must report unavailable
	// or rebuild-needed rather than falling back to a decoded in-memory graph.
	VectorIndexStrategyColumnGraph VectorIndexStrategy = "column_graph"
)

type VectorIndexTrace 

type VectorIndexTrace struct {
	Strategy                 string
	EfSearch                 int
	FetchMultiplier          int
	CandidatesExamined       int
	CandidatesAfterTombstone int
	CandidatesAfterFilter    int
	RerankCount              int
	ReturnedCount            int
	ExactFallbackReason      string
}

VectorIndexTrace reports how one vector-index search was executed.

type VectorMetric 

type VectorMetric uint8

VectorMetric selects the exact distance function used by collection vector search. Smaller returned distances are better for every metric. 

const (
	VectorMetricCosine VectorMetric = iota
	VectorMetricL2
	VectorMetricInnerProduct
)

func (VectorMetric) MarshalJSON 

func (m VectorMetric) MarshalJSON() ([]byte, error)

func (VectorMetric) String 

func (m VectorMetric) String() string

func (*VectorMetric) UnmarshalJSON 

func (m *VectorMetric) UnmarshalJSON(raw []byte) error

type VectorSearchOptions 

type VectorSearchOptions struct {
	// Field is the JSON field path containing a numeric vector. Nested fields can
	// be addressed with dot notation, for example "embedding.body".
	Field string
	// Metric selects the distance function. The zero value is cosine distance.
	Metric VectorMetric
	// TopK is the maximum number of nearest documents to return.
	TopK int
	// Filter is an optional metadata filter applied before vector extraction and
	// distance calculation. The callback receives owned stored-document bytes.
	Filter func(DocumentRecord) (bool, error)
	// IndexRangeFilter optionally restricts exact vector search to document IDs
	// returned by an existing scalar secondary-index range. Range.Limit is ignored
	// for correctness; the full logical range is scanned.
	IndexRangeFilter *VectorIndexRangeFilter
}

VectorSearchOptions configures exact vector search over collection primary documents.

type VectorSearchResult 

type VectorSearchResult struct {
	DocumentID []byte
	Distance   float32
	Document   []byte
}

VectorSearchResult is one exact vector-search match.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.