plan

func BuildMultiGroupBatchSchema ¶

func BuildMultiGroupBatchSchema(measureSchemas []*databasev1.Measure, req *measurev1.QueryRequest) (*vectorized.BatchSchema, error)

BuildMultiGroupBatchSchema unions the per-group BatchSchemas produced by BuildBatchSchema and returns a single merged schema whose column order is:

metadata (timestamp, version, sid, shardID), then tags in
(TagFamilyIdx, TagIdx) walk order across all groups with duplicates
skipped, then fields ordered by request projection (or schema-walk
order when no projection is given).

Tag type-divergence (same name, different type across groups) falls back to ColumnTypeTagValue so the frame v3 proto-bytes passthrough carries each cell without forced type conversion. Field type-divergence falls back to ColumnTypeFieldValue, mirroring the row path's FIELD_TYPE_UNSPECIFIED fallback (schema.go:165-176).

When len(measureSchemas) == 1 the result is identical to BuildBatchSchema applied to that single schema (single-group hot path is unchanged).

func Dispatch ¶

func Dispatch(
	ctx context.Context,
	req *measurev1.QueryRequest,
	metadata *commonv1.Metadata,
	measureSchema *databasev1.Measure,
	logicalSchema logical.Schema,
	ec executor.MeasureExecutionContext,
	cfg measure.VectorizedConfig,
	emitPartial bool,
	skipProjectionValidation bool,
) (iter executor.MIterator, planStr string, handled bool, err error)

Dispatch is the G8d top-level entry into the vec measure subsystem.

Called from banyand/query/processor.go before the row-path Analyze runs. When the request is eligible for the vec subsystem, Dispatch:

1. Analyzes the request into a VecPlan via plan.Analyze (G8b)
2. Resolves the index.Query + entity table the storage layer needs (using inverted.BuildQuery / BuildIndexModeQuery — the same helpers the deprecated row path uses; the logical.Schema parameter threads through unchanged)
3. Calls ec.Query(ctx, opts) to obtain the MeasureQueryResult
4. Wraps the result as a vec PullOperator (BatchSourceFromBatchResult fast path when available; BatchScan fallback otherwise) and installs it on the leaf Scan node
5. Executes the plan via plan.Execute (G8c) to return an MIterator

Returns (iter, planStr, true, nil) when the request is handled; the caller MUST return that iterator and skip the row plan. Returns (nil, "", false, nil) when the request is NOT eligible — the caller should fall through to the row path. Returns (nil, "", true, err) when the request was eligible but execution failed; the caller must surface the error rather than fall through (the storage query may have already touched state).

Eligibility gate (v1):

• cfg.Enabled must be true
• request may carry GroupBy and/or Agg in any combination (group+agg, scalar reduce, raw GroupBy); plan.Analyze auto-extends the projection so the keys / agg field always resolve
• request may carry Top: the analyzer emits Scan → Top → Limit (or Scan → GroupByAgg → Top → Limit) and BatchTop reproduces the row path's top-N (G9a)
• a nil request.TimeRange is accepted: Dispatch normalises it to an epoch→epoch window for row-path parity (G9c), so callers do not need to pre-populate one
• hidden criteria tags (criteria tags absent from the projection) are projected for storage-side filtering, then stripped at egress by hiddenTagsMIterator so the wire format is byte-identical
• measureSchema and logicalSchema must be non-nil

func Execute ¶

func Execute(ctx context.Context, plan VecPlan, cfg measure.VectorizedConfig) (executor.MIterator, error)

Execute composes a vec plan tree into a runnable *vectorized.Pipeline and returns it as an executor.MIterator. The Scan node(s) in the plan must have Source already set — the executor (G8c) does not resolve storage on its own; G8d's top-level dispatch is responsible for building the scan source from a MeasureExecutionContext and stitching it in.

Lifecycle: a per-pipeline MemoryTracker is constructed from cfg.QueryMemoryMiB and threaded through the BuildContext so every memory-bookkeeping operator (BatchAggregation, future BatchGroupBy) charges against a single budget (G7a). Pipeline.Init is invoked before the iterator is returned so breaker stages (which lazily allocate their state on Init) are ready for the first Next.

On any error during Build, builder.Build, or Pipeline.Init, the function returns the error and closes any partially-constructed pipeline so source resources (BatchPool, underlying MeasureBatchResult) are released.

func FellThroughCount ¶

func FellThroughCount() int64

FellThroughCount returns the cumulative number of times Dispatch declined to handle a request (returned handled=false, err=nil) in this process.

func HandledCount ¶

func HandledCount() int64

HandledCount returns the cumulative number of vec dispatch successes observed by this process.

func PrintTree ¶

func PrintTree(root VecPlan) string

PrintTree renders a plan tree as multi-line text. Leaves first column, each parent indented two spaces deeper than its child. Useful for debugging analyzer output.

func SupportsDistributedRows ¶

func SupportsDistributedRows(req *measurev1.QueryRequest) bool

SupportsDistributedRows reports whether a non-aggregation request can use the native vectorized distributed row merge. Phase 2 lifts the OrderBy.IndexRuleName != "" gate; Phase 4 lifts the Top-without-Agg gate; Phase 5 lifts the GroupBy-without-Agg gate (raw GroupBy: first-seen row per group) and the multi-group + Top carve-out (per-group Limit is now calibrated rather than MaxUint32, so amplification is bounded).

Rejected: Agg != nil — aggregation requests always go through executeAgg.

func ValidateMultiGroupProjection ¶

func ValidateMultiGroupProjection(req *measurev1.QueryRequest, schemas []logical.Schema, measures []*databasev1.Measure) error

ValidateMultiGroupProjection is the multi-measure counterpart of the single-group validation Dispatch runs inline. A projected tag/field is accepted if it resolves in ANY group's schema/measure — mirroring the row path's measure_analyzer.Analyze, which calls mergeSchema(ss) to union the per-group schemas before validating the projection. Without this, a multi-measure query that projects a tag/field added to one group but not another (the classic schema-evolution case the `multi_group_new_tag_field` integration test pins) would be rejected per-group inside Dispatch even though the row path accepts it. Returns the same byte-identical error message ("<tag>: tag is not defined" / "field <name> not found in schema") as the single-group path so test fixtures and operator-facing errors match across the two routes.