runtime

Documentation

Overview

Package runtime holds the IVF-PQ algorithm's catalog-side metadata: hidden-table types, parameter schema, op-type set, default options.

What lives here (and what doesn't):

• Algorithm-metadata constants and table-driven facts (op_type set, supported quantizations, default param values).
• The implementation of plugin/catalog.Hooks.
• Pure CREATE-INDEX param parsing (no QueryBuilder / *Scope state).

Anything that drives a SQL pipeline stage — CREATE/ALTER/DROP execution, plan-tree construction, query rewriting — belongs in compile/ or plan/ next door, not here. The rule is: lifted code follows the pkg/sql/<layer> it came from; runtime/ is only for facts that aren't tied to a layer.

Lifted from the IVF-PQ case of catalog.indexParamsToMap (pkg/catalog/secondary_index_utils.go:434-477).

Index

• Constants
• type CatalogHooks
  • func (CatalogHooks) AlterTableCloneBehavior() catalogplugin.AlterTableCloneBehavior
  • func (CatalogHooks) BuildSessionVars() []string
  • func (CatalogHooks) DefaultOptions() map[string]string
  • func (CatalogHooks) ExperimentalFlag() string
  • func (CatalogHooks) HiddenTableTypes() []string
  • func (CatalogHooks) ParamsFromTree(idx *tree.Index) (map[string]string, error)
  • func (CatalogHooks) RestoreBehavior() catalogplugin.RestoreBehavior
  • func (CatalogHooks) ShouldTruncateHiddenTable(_ string) bool
  • func (CatalogHooks) SupportedIncludeColumnTypes() []types.T
  • func (CatalogHooks) SupportedOpTypes() map[string]string
  • func (CatalogHooks) SupportedPrimaryKeyTypes() []types.T
  • func (CatalogHooks) SupportedVectorTypes() []types.T
  • func (CatalogHooks) SyncDescriptor() catalogplugin.SyncDescriptor

Constants

const (
	DefaultKmeansTrainPercent = float64(10)
	DefaultKmeansMaxIteration = int64(20)
	DefaultMaxIndexCapacity   = int64(0)
)

Build-param defaults mirror the frontend session-var defaults; the build path (ivfpq_create) uses them when the flat algo_params key is absent (a legacy index). Capacity 0 means "auto-detect from source row count".

const IvfpqIndexFlag = "experimental_ivfpq_index"

IvfpqIndexFlag is the experimental-feature flag gating IVF-PQ DDL. Single source of truth; both the catalog gate (pkg/sql/compile/util.go via ExperimentalFlag) and the per-plugin HandleCreateIndex gate reference this constant.

Types

type CatalogHooks

type CatalogHooks struct{}

CatalogHooks implements plugin/catalog.Hooks for IVF-PQ.

All four methods are required by the framework — see pkg/indexplugin/catalog/hooks.go for the contract. The compile- time interface check below catches missing methods.

func (CatalogHooks) AlterTableCloneBehavior

func (CatalogHooks) AlterTableCloneBehavior() catalogplugin.AlterTableCloneBehavior

AlterTableCloneBehavior — IVF-PQ leaves both hidden tables empty at CREATE-INDEX time. Mirrors HNSW.

func (CatalogHooks) BuildSessionVars

func (CatalogHooks) BuildSessionVars() []string

BuildSessionVars are the environmental/perf vars captured into algo_params.session_vars at CREATE INDEX. The index-defining k-means knobs and max_index_capacity ride flat algo_params keys written by ParamsFromTree only when explicitly set in CREATE INDEX. The experimental flag is NOT captured: the background reindex (ProcessInitSQL, IsFrontend=false) skips the experimental gate, so its create-time value is never consulted.

func (CatalogHooks) DefaultOptions

func (CatalogHooks) DefaultOptions() map[string]string

DefaultOptions is the params map produced when CREATE INDEX is issued without a WITH(...) clause. Return nil if your algorithm requires explicit options. Keys come from pkg/catalog (IndexAlgoParamOpType etc.).

func (CatalogHooks) ExperimentalFlag

func (CatalogHooks) ExperimentalFlag() string

ExperimentalFlag: IVF-PQ DDL is gated by IvfpqIndexFlag.

func (CatalogHooks) HiddenTableTypes

func (CatalogHooks) HiddenTableTypes() []string

HiddenTableTypes lists the IndexAlgoTableType strings this algorithm uses for its hidden tables. The order does not matter; downstream code keys into the map by name. IVF-PQ needs two: metadata + storage. IVF-FLAT (for contrast) returns three: metadata, centroids, entries.

func (CatalogHooks) ParamsFromTree

func (CatalogHooks) ParamsFromTree(idx *tree.Index) (map[string]string, error)

ParamsFromTree is lifted verbatim from catalog.indexParamsToMap's INDEX_TYPE_IVFPQ case (pkg/catalog/secondary_index_utils.go:434-477).

func (CatalogHooks) RestoreBehavior

func (CatalogHooks) RestoreBehavior() catalogplugin.RestoreBehavior

RestoreBehavior — IVF-PQ's hidden tables (Storage tag=0 model blob + Metadata) are keyed by index_id, so the restore's block-level clone overwrites the CreateTable seed rather than appending — nothing needs delete-before-clone (empty DeleteBeforeClone). The model is rebuilt post-clone by the compile hook's RestoreInitSQL (ALTER … REINDEX … ivfpq FORCE_SYNC), run by the CDC's first iteration.

func (CatalogHooks) ShouldTruncateHiddenTable

func (CatalogHooks) ShouldTruncateHiddenTable(_ string) bool

ShouldTruncateHiddenTable — IVF-PQ has no preserved-across-truncate state; both hidden tables are derived from source rows and must reset.

func (CatalogHooks) SupportedIncludeColumnTypes

func (CatalogHooks) SupportedIncludeColumnTypes() []types.T

SupportedIncludeColumnTypes: cuvs INCLUDE (pre-filter) columns accept int32/int64/float32/float64 scalars.

func (CatalogHooks) SupportedOpTypes

func (CatalogHooks) SupportedOpTypes() map[string]string

func (CatalogHooks) SupportedPrimaryKeyTypes

func (CatalogHooks) SupportedPrimaryKeyTypes() []types.T

SupportedPrimaryKeyTypes: requires an int64 primary key.

func (CatalogHooks) SupportedVectorTypes

func (CatalogHooks) SupportedVectorTypes() []types.T

SupportedOpTypes maps the SQL-visible op_type strings (e.g. "vector_l2_ops") to a stable internal identifier. Used by plan-side op_type validation when matching an ORDER BY distance function against the index's declared op_type. SupportedVectorTypes: IVF-PQ (cuvs) indexes f32 vectors only.

func (CatalogHooks) SyncDescriptor

func (CatalogHooks) SyncDescriptor() catalogplugin.SyncDescriptor

SyncDescriptor: IVF-PQ mirrors CAGRA — always async via ISCP CDC (event-level deltas) AND participates in idxcron (periodic model rebuild). See pkg/vectorindex/cagra/plugin/runtime/runtime.go's SyncDescriptor for the full rationale.