collector

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package collector owns reader-compiled relation graphs and typed row assembly. SQLX supplies typed rows; collector reconciles parent-child relations without introducing another scanner or row-cache model.

Index

Constants

View Source 
const (
	MatchSequential = data.MatchSequential
	MatchReadAll    = data.MatchReadAll
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Collector 

type Collector struct {
	Id string
	// contains filtered or unexported fields
}

Collector collects and builds a result from one View fetched from the database. When a View or any of its With relations supports parallel fetching (ReadAll), call MergeData after all views have been fetched.

func NewCollector 

func NewCollector(view *View, dest interface{}, readAll bool) *Collector

NewCollector creates a root Collector for view, writing into dest. dest must be a pointer to a slice (or *interface{} for dynamic dispatch).

func (*Collector) Append 

func (r *Collector) Append(value interface{})

Append adds a decoded typed row to the collector destination.

func (*Collector) AppendPartition 

func (r *Collector) AppendPartition(ctx context.Context, source *Collector) error

AppendPartition merges one isolated partition into the canonical collector while preserving unmapped SQLx destinations used by relation keys.

func (*Collector) AppendSlice 

func (r *Collector) AppendSlice(ctx context.Context, rows any) error

AppendSlice indexes a reducer-produced typed slice into this collector.

func (*Collector) AssembleTrees 

func (r *Collector) AssembleTrees() error

AssembleTrees materializes self-referencing views after ordinary relation merging. Children are assembled first so parent rows retain hydrated child graphs before their own flat rows become a tree.

func (*Collector) BootstrapFromParentHolder 

func (r *Collector) BootstrapFromParentHolder() bool

BootstrapFromParentHolder seeds this collector from already-materialised parent holder data. Useful when parent OnFetch hooks populate a virtual relation in-memory and nested collectors still need a real source.

func (*Collector) Children 

func (r *Collector) Children() []*Collector

func (*Collector) Clone 

func (r *Collector) Clone() *Collector

func (*Collector) DataSync 

func (r *Collector) DataSync() *xhandler.DataSync

func (*Collector) Dest 

func (r *Collector) Dest() interface{}

func (*Collector) DestPtr 

func (r *Collector) DestPtr() interface{}

func (*Collector) EnableProvenance 

func (r *Collector) EnableProvenance() error

EnableProvenance opts this collector tree into final-ordinal read evidence. It must be called before scanning; normal reads allocate no evidence graph.

func (*Collector) Fetched 

func (r *Collector) Fetched()

Fetched signals that row scanning for this collector is complete.

func (*Collector) Len 

func (r *Collector) Len() int

func (*Collector) Lock 

func (r *Collector) Lock() *sync.Mutex

func (*Collector) MergeData 

func (r *Collector) MergeData() error

MergeData reconciles all ReadAll child collectors into their parents. Call on the root collector after all fetches complete.

func (*Collector) NewItem 

func (r *Collector) NewItem() func() interface{}

NewItem returns a factory that allocates and appends a typed model row.

func (*Collector) OnSkip 

func (r *Collector) OnSkip(_ []interface{}) error

OnSkip drops the last accumulated row when a record is skipped.

func (*Collector) OnSkipUnmapped 

func (r *Collector) OnSkipUnmapped(_ []interface{}) error

OnSkipUnmapped rolls back only resolver-owned hidden columns. Codec scan rows are not appended to the typed destination until after SQLx emits them.

func (*Collector) Parent 

func (r *Collector) Parent() *Collector

func (*Collector) ParentPlaceholders 

func (r *Collector) ParentPlaceholders() ([]interface{}, [][]interface{}, []string)

ParentPlaceholders returns the deduplicated parent key values needed to parameterise the child SQL query. The three return values are:

  • scalar values (single-column join)
  • composite rows (multi-column join)
  • column expressions for the SQL IN clause

func (*Collector) ParentRow 

func (r *Collector) ParentRow() func(value interface{}) (interface{}, error)

ParentRow returns a function that resolves the parent struct pointer for a child row. Used by codec pipelines that need to reach back to the parent.

func (*Collector) PartitionCopy 

func (r *Collector) PartitionCopy() *Collector

PartitionCopy creates an isolated collector for one partition. It retains relation identity for parent publication but never attaches concurrently; the canonical collector performs attachment during deterministic merge.

func (*Collector) Provenance 

func (r *Collector) Provenance(rootHolder string, direct bool) (*readmeta.Result, error)

Provenance snapshots the completed collector graph. It never walks values or re-matches relationships; edges came from actual attachment operations.

func (*Collector) ReadAll 

func (r *Collector) ReadAll() bool

func (*Collector) RebindToParent 

func (r *Collector) RebindToParent() error

RebindToParent refreshes a matched relation attachment after the child collector has been further hydrated (for example by nested read_all descendants). Streaming visitor attachment happens while scanning the child rows, so any later descendant merges would otherwise stay behind on the child collector copy instead of the parent-held relation values.

func (*Collector) RecordFields 

func (r *Collector) RecordFields(fields *readmeta.Fields)

RecordFields records the schema for the next accepted visitor row. Allocation addresses are deliberately not retained: value slices may grow and move.

func (*Collector) Relation 

func (r *Collector) Relation() *data.Relation

func (*Collector) Relations 

func (r *Collector) Relations(selector *Statelet) []*Collector

Relations creates child Collectors for each Relation on the view. selector may be nil (no column pruning).

func (*Collector) ReserveSQLKey 

func (r *Collector) ReserveSQLKey(column string) *any

ReserveSQLKey follows the unmapped allocator's row lifecycle, including rollback when a cache matcher skips a row. Fill the slot before row hooks.

func (*Collector) Resolve 

func (r *Collector) Resolve(column Column) func(ptr unsafe.Pointer) interface{}

Resolve returns a per-row allocator for an unmapped column, buffering the scanned values so that the position-index step can use them later.

func (*Collector) RunOnRelation 

func (r *Collector) RunOnRelation(ctx context.Context) error

RunOnRelation walks the collector tree and invokes the OnRelation hook on every materialized value that implements onRelationer.

func (*Collector) SQLKeyColumns 

func (r *Collector) SQLKeyColumns() map[string]bool

SQLKeyColumns includes keys for child reads and this view's attachment to its parent. Mapped columns need snapshots too, independent of row hooks.

func (*Collector) SetDest 

func (r *Collector) SetDest(dest interface{})

func (*Collector) Slice 

func (r *Collector) Slice() (unsafe.Pointer, *xunsafe.Slice)

func (*Collector) Unlock 

func (r *Collector) Unlock()

Unlock signals to dependents that this relation's data is ready.

func (*Collector) View 

func (r *Collector) View() *data.View

func (*Collector) Visitor 

func (r *Collector) Visitor(ctx context.Context) VisitorFn

Visitor returns the compound VisitorFn to call once per scanned row.

func (*Collector) WaitIfNeeded 

func (r *Collector) WaitIfNeeded()

WaitIfNeeded blocks until the parent collector signals that its rows are scanned (used by child collectors that need parent positions first).

type Column 

type Column interface {
	Name() string
	ScanType() reflect.Type
}

Column is the minimal interface the Collector needs from a sql.ColumnType wrapper. It mirrors sqlx/io.Column but avoids a hard import of that package in callers that don't have sqlx on the class path.

type Graph 

type Graph struct {
	Root *View
	// contains filtered or unexported fields
}

Graph is the immutable reader-compiled relation graph for one root view.

func Compile 

func Compile(root *data.View, rowTypes map[*data.View]reflect.Type) (*Graph, error)

Compile builds collector-only schema and field access without mutating data metadata. Row types are supplied by the reader compiler that resolved the component's output shape.

func (*Graph) Validate 

func (g *Graph) Validate() error

Validate verifies that every executable relation has a compiled row schema. A schema-less root is valid for components that expose only output relations.

func (*Graph) View 

func (g *Graph) View(metadata *data.View) *View

type KeySource 

type KeySource string
const (
	KeySourceField  KeySource = "field"
	KeySourceColumn KeySource = "column"
	KeySourceHook   KeySource = "hook"
)
type Link struct {
	*data.Link
	// KeySource is resolved once at compile time, never from a row's value.
	KeySource KeySource
	// XField is present only for typed field and hook sources. Every key
	// consumer uses this accessor or the captured SQL column, consistently.
	XField *xunsafe.Field
}
type Links []*Link

func (Links) InColumnExpression 

func (l Links) InColumnExpression() []string

type Relation 

type Relation struct {
	*data.Relation
	On          Links
	Of          *RelationRef
	HolderField *xunsafe.Field
	HolderSlice *xunsafe.Slice
}

Relation is reader-compiled state for one metadata relation.

type RelationRef 

type RelationRef struct {
	*data.RelationRef
	View *View
	On   Links
}

type Relations 

type Relations []*Relation

func (Relations) PopulateWithVisitor 

func (r Relations) PopulateWithVisitor() []*Relation

type Schema 

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

Schema is the reader-owned compiled row and slice access for one view.

func NewSchema 

func NewSchema(rowType reflect.Type) Schema

func (*Schema) RowType 

func (s *Schema) RowType() reflect.Type

func (*Schema) Slice 

func (s *Schema) Slice() *xunsafe.Slice

func (*Schema) SliceType 

func (s *Schema) SliceType() reflect.Type

type Statelet 

type Statelet struct {
	Columns []string
}

Statelet carries optional column-selection state used to prune relations.

func (*Statelet) Has 

func (s *Statelet) Has(holder string) bool

Has reports whether holder appears in the selected columns list.

type TreePlan 

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

TreePlan is immutable registration-compiled state for one self-referencing view. Declarative Holder/Child/Parent metadata remains on the canonical spec snapshot.

func NewTreePlan 

func NewTreePlan(view *View) (*TreePlan, error)

func (*TreePlan) Build 

func (p *TreePlan) Build(nodes interface{}) interface{}

Build connects direct children to parent rows and returns the roots in input order. Missing-parent rows are roots, matching the original reader behavior.

func (*TreePlan) VisitRow 

func (p *TreePlan) VisitRow(row any, visit func(any)) error

VisitRow visits actual materialized tree values child-first. Value-holder copies made while building the tree are the lifecycle targets, not old rows.

type View 

type View struct {
	*data.View
	Schema    Schema
	Relations []*Relation
	Tree      *TreePlan
}

View is reader-compiled state for one immutable data view.

type VisitorFn 

type VisitorFn func(value interface{}) error

VisitorFn is called once per scanned row. It indexes values and/or sets parent-struct fields for One/Many relations.

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.