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.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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.
Source Files