fetch

Documentation

Overview

Package fetch is the storage seam: the contract every query language compiles to and every data source (head, parts, cluster fan-out) implements. A Request of label matchers + a time window resolves to an Iterator of lazily-produced [Batch]es.

This is the metrics shape of the contract — one batch per matching series, carrying its sample columns. The columnar/projection/second-pass and nested-reconstruction aspects (for logs/traces) extend it in later milestones; the seam itself stays the same.

Index

• type Batch
  • func Drain(ctx context.Context, it Iterator) ([]*Batch, error)
• type EqualMatcher
  • func (m EqualMatcher) Predicate() func(signal.Value) bool
• type Fetcher
  • func Merge(fetchers ...Fetcher) Fetcher
• type Iterator
• type Matcher
• type Request
• type SliceIterator
  • func NewSliceIterator(batches []*Batch) *SliceIterator
  • func (it *SliceIterator) Close() error
  • func (it *SliceIterator) Next(context.Context) (*Batch, error)

Types

type Batch

type Batch struct {
	ID         signal.SeriesID
	Series     signal.Series
	Timestamps []int64
	Values     []float64
}

Batch is one matching series and its samples within the request window, time-ordered.

func Drain

func Drain(ctx context.Context, it Iterator) ([]*Batch, error)

Drain reads an iterator to completion and returns all batches.

type EqualMatcher

type EqualMatcher struct {
	Name  string
	Value string
}

EqualMatcher is the serializable form of an exact label-equality predicate (see Matcher.Spec). EqualMatcher.Predicate reconstructs the equivalent Matcher.Match.

func (EqualMatcher) Predicate

func (m EqualMatcher) Predicate() func(signal.Value) bool

Predicate returns the Match closure equivalent to this equality: the label's canonical text projection equals Value (the same comparison the language layer's exact matcher makes).

type Fetcher

type Fetcher interface {
	Fetch(ctx context.Context, r Request) (Iterator, error)
}

Fetcher resolves a Request to an Iterator. It is implemented by the head, each part, and (later) the cluster fan-out.

func Merge

func Merge(fetchers ...Fetcher) Fetcher

Merge returns a Fetcher that fans a Request out to each child fetcher and merges the results by signal.SeriesID. Batches that share an id — the same series present in more than one child, e.g. equal labels across tenants (cross-tenant / multi-tenant reads) or replicas across nodes (cluster fan-out) — are combined into one batch with samples in timestamp order, the value from the later child winning on a duplicate timestamp.

With a single child it is a transparent pass-through (no copy or re-sort). The children are already bound to their data (a per-tenant engine, a remote node), so each receives the same Request and its Request.Tenant field is advisory. nil/empty input yields an empty fetcher.

type Iterator

type Iterator interface {
	Next(ctx context.Context) (*Batch, error)
	Close() error
}

Iterator yields batches lazily; Next returns (nil, io.EOF) at the end.

type Matcher

type Matcher struct {
	Name  []byte
	Match func(value signal.Value) bool

	// Spec is an optional **serializable** form of an equality predicate, set by the language
	// layer when Match is an exact compare. It lets the cluster fan-out push a selective
	// matcher (e.g. `__name__="metric"`) to a peer node — the Match closure cannot cross the
	// wire. It is metadata only: a [Fetcher] always matches via Match; a peer reconstructs an
	// equivalent closure from Spec. Only equality is carried (it is exact, so a peer's pushdown
	// never drops a matching series); other predicates fall back to the requester's re-check.
	Spec *EqualMatcher
}

Matcher is one label condition: the predicate Match selects which values of the attribute Name satisfy it. The condition is a **callback**, not an operator enum, so the contract carries no query-language semantics — a language supplies the predicate (a compiled regexp, an exact compare, a typed numeric range, a custom rule) over the typed signal.Value. A Fetcher applies Match while scanning the label's distinct values.

Negation and absent-label semantics compose at the language layer (a fetcher selects the matching values; the language decides whether to complement the result).

type Request

type Request struct {
	Tenant     signal.TenantID
	Start, End int64 // unix nanos, inclusive
	Matchers   []Matcher
}

Request selects series for a tenant within an inclusive time window, filtered by all matchers (their intersection).

type SliceIterator

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

SliceIterator is an Iterator over a fixed slice of batches — for simple fetchers and tests.

func NewSliceIterator

func NewSliceIterator(batches []*Batch) *SliceIterator

NewSliceIterator returns an iterator over batches.

func (*SliceIterator) Close

func (it *SliceIterator) Close() error

Close releases the iterator (a no-op for a slice).

func (*SliceIterator) Next

func (it *SliceIterator) Next(context.Context) (*Batch, error)

Next returns the next batch, or (nil, io.EOF) when exhausted.