[4.2] feat: backport FULLTEXT2 from main

docs/fulltext2-backport-4.2dev-manifest.md

@@ -0,0 +1,29 @@
+# FULLTEXT2 4.2-dev backport manifest
+
+This branch is a bounded backport from the refs captured on 2026-08-26. The
+source and target refs are intentionally fixed for this run; later commits on
+`upstream/main` are not followed.
+
+| source | scope | local commit |
+| --- | --- | --- |
+| `1d7b6311ce91df0968da435bb405f3d68137c595` (#25904) | FULLTEXT2 engine, parser/catalog contracts, plugin/CDC, planner/DDL and tests | `966acb2a92bb740e57b0b7a181df2d21956e1d3`, `0eb9a921ece274c956447640b41ad2a255079e8d`, `403a99fb65304e75b82e75793448f0690a871d0e`, `bfa83f42737ca6304c0af3f6913e70ccc961464` |
+| `ec591dc9d4ec6b3beb81b804dac11aceb9b66441` (#27165) | delayed phrase-position decode after document alignment | `2b142144c3c24a2100d7d313e952717025d56aeb` |
+| `3da66f2ca28d62f5e657c46d90b7cde9475486d0` (#27171), selective FT2 portion | wrapped FT2 score expressions, argument-aware score resolution, AND-reachable score ranges, and conservative float32 bounds; classic/view/vector changes from the source commit are excluded | `835e046faa9242dbe288bd72364a475e2132bbed` |
+| `6dccc954a1a32c12a2114328c752f15cf97ef2ba` (#27461) | cold-load reason/latency observation and cache-load lifecycle | `e4abf5e90d0b5e09590571ca78447e50806527c` |
+| `b8aa3f7f7351aacaaa37da27891d8f8d85e2e44d` (#27462) | immutable base/tail reuse across cache generations | `e4abf5e90d0b5e09590571ca78447e50806527c` |
+| `e07a7a792749db4228c1acf96d72827161747e60` (#27598) | FULLTEXT2 BVT readiness polling in place of fixed sleeps | `e3a7440e2ac32bac780669f33c656960e22cff22` |
+| current validation and review repairs | restore execution-level wrapped-score coverage, repair reverse score-bound membership and ISCP error propagation, and remove fixed-sleep/whitespace gate failures | `35f910dd543e1d3a952e4bd1a1b9852558ee2e27`, `fbea073c3b55836317c7aeb49d090ed2167f004c`, `06ab54d812ffcae1b4910e74f2f42a85ae9dfe0b`, `4cce042c8d3ad2cbada59ddd24e287785c297c1a` |
+
+## Ref closure
+
+- Source reference: `upstream/main` = `8e616a693458652cc26b3c4be45c6602dff298d4`
+- Target reference: `upstream/4.2-dev` = `d2393868a7aaa6343518d80849fe4696aa3577e9`
+- Branch: `backport/fulltext2-main-8e616a6-4.2dev-d239386`
+- The repair/BVT commits above are ancestors of the manifest update; the exact
+  post-update branch head is recorded in the PR and the final remote reread.
+- The target branch's existing parser/PERFORM and pipe changes were preserved;
+  the generated MySQL parser was regenerated from the merged 4.2 grammar.
+
+The diff does not use classic FULLTEXT as validation evidence. No local image,
+direct `4.2-dev` push, Kubernetes mutation, or GitOps file mutation is part of
+this backport.

go.mod

@@ -22,6 +22,7 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sts v1.33.1
 	github.com/aws/smithy-go v1.22.1
 	github.com/axiomhq/hyperloglog v0.2.6
+	github.com/blevesearch/vellum v1.2.0
 	github.com/buger/jsonparser v1.1.1
 	github.com/bytedance/sonic v1.15.2
 	github.com/cakturk/go-netstat v0.0.0-20200220111822-e5b49efee7a5
@@ -83,7 +84,7 @@ require (
 	github.com/segmentio/encoding v0.4.0
 	github.com/shirou/gopsutil/v3 v3.23.12
 	github.com/smartystreets/goconvey v1.7.2
-	github.com/spf13/cobra v1.8.0
+	github.com/spf13/cobra v1.10.2
 	github.com/spkg/bom v1.0.0
 	github.com/stretchr/testify v1.11.1
 	github.com/syncthing/notify v0.0.0-20250528144937-c7027d4f7465
@@ -138,6 +139,8 @@ require (
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bits-and-blooms/bitset v1.24.2 // indirect
+	github.com/blevesearch/mmap-go v1.2.0 // indirect
+	github.com/bufbuild/protocompile v0.6.0 // indirect
 	github.com/bytedance/gopkg v0.1.3 // indirect
 	github.com/bytedance/sonic/loader v0.5.1 // indirect
 	github.com/charmbracelet/colorprofile v0.2.3-0.20250311203215-f60798e515dc // indirect
@@ -231,7 +234,7 @@ require (
 	github.com/shoenig/go-m1cpu v0.1.6 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/smartystreets/assertions v1.13.1 // indirect
-	github.com/spf13/pflag v1.0.5 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
 	github.com/tetratelabs/wabin v0.0.0-20230304001439-f6f874872834 // indirect
 	github.com/tetratelabs/wazero v1.8.1-0.20240916092830-1353ca24fef0 // indirect
 	github.com/tinylib/msgp v1.6.1 // indirect

go.sum

@@ -117,6 +117,12 @@ github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6r
 github.com/bits-and-blooms/bitset v1.24.2 h1:M7/NzVbsytmtfHbumG+K2bremQPMJuqv1JD3vOaFxp0=
 github.com/bits-and-blooms/bitset v1.24.2/go.mod h1:7hO7Gc7Pp1vODcmWvKMRA9BNmbv6a/7QIWpPxHddWR8=
 github.com/blang/semver v3.5.1+incompatible/go.mod h1:kRBLl5iJ+tD4TcOOxsy/0fnwebNt5EWlYSAyrTnjyyk=
+github.com/blevesearch/mmap-go v1.2.0 h1:l33nNKPFcBjJUMwem6sAYJPUzhUCABoK9FxZDGiFNBI=
+github.com/blevesearch/mmap-go v1.2.0/go.mod h1:Vd6+20GBhEdwJnU1Xohgt88XCD/CTWcqbCNxkZpyBo0=
+github.com/blevesearch/vellum v1.2.0 h1:xkDiOEsHc2t3Cp0NsNZZ36pvc130sCzcGKOPMzXe+e0=
+github.com/blevesearch/vellum v1.2.0/go.mod h1:uEcfBJz7mAOf0Kvq6qoEKQQkLODBF46SINYNkZNae4k=
+github.com/bufbuild/protocompile v0.6.0 h1:Uu7WiSQ6Yj9DbkdnOe7U4mNKp58y9WDMKDn28/ZlunY=
+github.com/bufbuild/protocompile v0.6.0/go.mod h1:YNP35qEYoYGme7QMtz5SBCoN4kL4g12jTtjuzRNdjpE=
 github.com/buger/goterm v1.0.4 h1:Z9YvGmOih81P0FbVtEYTFF6YsSgxSUKEhf/f9bTMXbY=
 github.com/buger/goterm v1.0.4/go.mod h1:HiFWV3xnkolgrBV3mY8m0X0Pumt4zg4QhbdOzQtB8tE=
 github.com/buger/jsonparser v1.1.1 h1:2PnMjfWD7wBILjqQbt530v576A/cAbQvEW9gGIpYMUs=
@@ -204,7 +210,7 @@ github.com/cpegeric/pdftotext-go v0.0.0-20241112123704-49cb86a3790e/go.mod h1:zt
 github.com/cpuguy83/dockercfg v0.3.1 h1:/FpZ+JaygUR/lZP2NlFI2DVfrOEMAIKP5wWEJdoYe9E=
 github.com/cpuguy83/dockercfg v0.3.1/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
 github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
-github.com/cpuguy83/go-md2man/v2 v2.0.3/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -801,13 +807,13 @@ github.com/spf13/afero v1.1.2/go.mod h1:j4pytiNVoe2o6bmDsKpLACNPDBIoEAkihy7loJ1B
 github.com/spf13/cast v1.3.0/go.mod h1:Qx5cxh0v+4UWYiBimWS+eyWzqEqokIECu5etghLkUJE=
 github.com/spf13/cobra v0.0.3/go.mod h1:1l0Ry5zgKvJasoi3XT1TypsSe7PqH0Sj9dhYf7v3XqQ=
 github.com/spf13/cobra v0.0.5/go.mod h1:3K3wKZymM7VvHMDS9+Akkh4K60UwM26emMESw8tLCHU=
-github.com/spf13/cobra v1.8.0 h1:7aJaZx1B85qltLMc546zn58BxxfZdR/W22ej9CFoEf0=
-github.com/spf13/cobra v1.8.0/go.mod h1:WXLWApfZ71AjXPya3WOlMsY9yMs7YeiHhFVlvLyhcho=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
 github.com/spf13/jwalterweatherman v1.0.0/go.mod h1:cQK4TGJAtQXfYWX+Ddv3mKDzgVb68N+wFjFa4jdeBTo=
 github.com/spf13/pflag v1.0.1/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
 github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4=
-github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
-github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/spf13/viper v1.3.2/go.mod h1:ZiWeW+zYFKm7srdB9IoDzzZXaJaI5eL9QjNiN/DMA2s=
 github.com/spkg/bom v1.0.0 h1:S939THe0ukL5WcTGiGqkgtaW5JW+O6ITaIlpJXTYY64=
 github.com/spkg/bom v1.0.0/go.mod h1:lAz2VbTuYNcvs7iaFF8WW0ufXrHShJ7ck1fYFFbVXJs=

pkg/catalog/fulltext2_params_test.go

@@ -0,0 +1,69 @@
+// Copyright 2026 Matrix Origin
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package catalog
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+// TestIndexParamsToStringListFulltext2Options pins that the shared SHOW CREATE /
+// checkpoint-restore option renderer emits the fulltext2 build options —
+// position_free plus the capacities — so a rebuilt index keeps them instead of
+// silently reverting to a positional / default-capacity one.
+func TestIndexParamsToStringListFulltext2Options(t *testing.T) {
+	params, err := IndexParamsMapToJsonString(map[string]string{
+		"parser":                          "ngram",
+		IndexAlgoParamPositionFree:        "true",
+		IndexAlgoParamMaxIndexCapacity:    "1000",
+		IndexAlgoParamMaxPostingsCapacity: "8000",
+	})
+	require.NoError(t, err)
+
+	s, err := IndexParamsToStringList(params)
+	require.NoError(t, err)
+	require.Contains(t, s, IndexAlgoParamPositionFree+" = true")
+	require.Contains(t, s, IndexAlgoParamMaxIndexCapacity+" = 1000")
+	require.Contains(t, s, IndexAlgoParamMaxPostingsCapacity+" = 8000")
+
+	// position_free=false ⇒ positional ⇒ NOT rendered (only recorded/rendered when true).
+	params2, err := IndexParamsMapToJsonString(map[string]string{IndexAlgoParamPositionFree: "false"})
+	require.NoError(t, err)
+	s2, err := IndexParamsToStringList(params2)
+	require.NoError(t, err)
+	require.NotContains(t, s2, IndexAlgoParamPositionFree)
+}
+
+// TestIndexParamsToStringListAsyncCadence pins that the AUTO_UPDATE compaction cadence —
+// DAY / HOUR / SECOND — round-trips through the shared SHOW CREATE / checkpoint-restore
+// renderer. SECOND in particular was dropped, so an async index (fulltext2 / ivfflat /
+// cagra / ivfpq — all persist it) created with SECOND=5 silently lost its cadence on
+// SHOW CREATE / checkpoint restore and reverted to the idxcron default interval.
+func TestIndexParamsToStringListAsyncCadence(t *testing.T) {
+	params, err := IndexParamsMapToJsonString(map[string]string{
+		AutoUpdate: "true",
+		Day:        "1",
+		Hour:       "2",
+		Second:     "5",
+	})
+	require.NoError(t, err)
+
+	s, err := IndexParamsToStringList(params)
+	require.NoError(t, err)
+	require.Contains(t, s, Day+" = 1")
+	require.Contains(t, s, Hour+" = 2")
+	require.Contains(t, s, Second+" = 5")
+}

pkg/catalog/secondary_index_utils.go

@@ -29,15 +29,16 @@ import (
 
 // Index Algorithm names
 const (
-	MoIndexDefaultAlgo  = tree.INDEX_TYPE_INVALID  // used by UniqueIndex or default SecondaryIndex
-	MoIndexBTreeAlgo    = tree.INDEX_TYPE_BTREE    // used for Mocking MySQL behaviour.
-	MoIndexRTreeAlgo    = tree.INDEX_TYPE_RTREE    // used for Spatial Index on GEOMETRY columns
-	MoIndexIvfFlatAlgo  = tree.INDEX_TYPE_IVFFLAT  // used for IVF flat index on Vector/Array columns
-	MOIndexMasterAlgo   = tree.INDEX_TYPE_MASTER   // used for Master Index on VARCHAR columns
-	MOIndexFullTextAlgo = tree.INDEX_TYPE_FULLTEXT // used for Fulltext Index on VARCHAR columns
-	MoIndexHnswAlgo     = tree.INDEX_TYPE_HNSW     // used for HNSW Index on Vector/Array columns
-	MoIndexCagraAlgo    = tree.INDEX_TYPE_CAGRA    // used for CAGRA Index on Vector/Array columns
-	MoIndexIvfpqAlgo    = tree.INDEX_TYPE_IVFPQ    // used for IVFPQ Index on Vector/Array columns
+	MoIndexDefaultAlgo   = tree.INDEX_TYPE_INVALID   // used by UniqueIndex or default SecondaryIndex
+	MoIndexBTreeAlgo     = tree.INDEX_TYPE_BTREE     // used for Mocking MySQL behaviour.
+	MoIndexRTreeAlgo     = tree.INDEX_TYPE_RTREE     // used for Spatial Index on GEOMETRY columns
+	MoIndexIvfFlatAlgo   = tree.INDEX_TYPE_IVFFLAT   // used for IVF flat index on Vector/Array columns
+	MOIndexMasterAlgo    = tree.INDEX_TYPE_MASTER    // used for Master Index on VARCHAR columns
+	MOIndexFullTextAlgo  = tree.INDEX_TYPE_FULLTEXT  // used for Fulltext Index on VARCHAR columns
+	MoIndexFullText2Algo = tree.INDEX_TYPE_FULLTEXT2 // CREATE FULLTEXT2 INDEX: WAND positional engine on TEXT/VARCHAR columns
+	MoIndexHnswAlgo      = tree.INDEX_TYPE_HNSW      // used for HNSW Index on Vector/Array columns
+	MoIndexCagraAlgo     = tree.INDEX_TYPE_CAGRA     // used for CAGRA Index on Vector/Array columns
+	MoIndexIvfpqAlgo     = tree.INDEX_TYPE_IVFPQ     // used for IVFPQ Index on Vector/Array columns
 )
 
 // ToLower is used for before comparing AlgoType and IndexAlgoParamOpType. Reason why they are strings
@@ -81,6 +82,14 @@ func IsFullTextIndexAlgo(algo string) bool {
 	return _algo == MOIndexFullTextAlgo.ToString()
 }
 
+// IsFullText2IndexAlgo reports the distinct WAND fulltext engine used by
+// CREATE FULLTEXT2 INDEX. It deliberately remains separate from classic
+// FULLTEXT so planner and plugin routing cannot depend on index enumeration order.
+func IsFullText2IndexAlgo(algo string) bool {
+	_algo := ToLower(algo)
+	return _algo == MoIndexFullText2Algo.ToString()
+}
+
 func IsHnswIndexAlgo(algo string) bool {
 	_algo := ToLower(algo)
 	return _algo == MoIndexHnswAlgo.ToString()
@@ -107,6 +116,7 @@ const (
 	AutoUpdate              = "auto_update"
 	Day                     = "day"
 	Hour                    = "hour"
+	Second                  = "second"
 	DistributionMode        = "distribution_mode"
 	Quantization            = "quantization"
 	BitsPerCode             = "bits_per_code"
@@ -128,6 +138,14 @@ const (
 	IndexAlgoParamQuantizerTrainLimit = "quantizer_train_limit"
 
 	IndexAlgoParamPrefixLengths = "prefix_lengths"
+	// IndexAlgoParamPrefixLengthsV2 stores a JSON object when a quoted column
+	// name contains a delimiter used by the legacy prefix encoding.
+	IndexAlgoParamPrefixLengthsV2     = "prefix_lengths_v2"
+	IndexAlgoParamMaxPostingsCapacity = "max_postings_capacity"
+	IndexAlgoParamPositionFree        = "position_free"
+	// IndexAlgoParamVersion identifies the index engine; v2 is the WAND
+	// FULLTEXT2 engine and absent/1 is the classic FULLTEXT engine.
+	IndexAlgoParamVersion = "version"
 )
 
 func ParseIncludeColumnsValue(raw string) ([]string, error) {
@@ -230,6 +248,10 @@ func IndexParamsToStringList(indexParams string) (string, error) {
 		res += fmt.Sprintf(" %s = %s ", Hour, val)
 	}
 
+	if val, ok := result[Second]; ok {
+		res += fmt.Sprintf(" %s = %s ", Second, val)
+	}
+
 	if val, ok := result[Quantization]; ok {
 		res += fmt.Sprintf(" %s '%s' ", Quantization, val)
 	}
@@ -266,9 +288,19 @@ func IndexParamsToStringList(indexParams string) (string, error) {
 		res += fmt.Sprintf(" %s = %s ", IndexAlgoParamMaxIndexCapacity, val)
 	}
 
+	if val, ok := result[IndexAlgoParamMaxPostingsCapacity]; ok {
+		res += fmt.Sprintf(" %s = %s ", IndexAlgoParamMaxPostingsCapacity, val)
+	}
+	if val, ok := result[IndexAlgoParamPositionFree]; ok && val == "true" {
+		res += fmt.Sprintf(" %s = %s ", IndexAlgoParamPositionFree, val)
+	}
+
 	if val, ok := result[IndexAlgoParamQuantizerTrainLimit]; ok {
 		res += fmt.Sprintf(" %s = %s ", IndexAlgoParamQuantizerTrainLimit, val)
 	}
+	if val, ok := result[IndexAlgoParamVersion]; ok {
+		res += fmt.Sprintf(" %s = %s ", IndexAlgoParamVersion, val)
+	}
 	return res, nil
 }
 
@@ -298,8 +330,16 @@ func IndexParamsMapToJsonString(res map[string]string) (string, error) {
 }
 
 func AddIndexPrefixLengthsToParams(indexParams string, keyParts []*tree.KeyPart) (string, error) {
-	prefixLengths := IndexPrefixLengthsToString(keyParts)
-	if prefixLengths == "" {
+	if len(keyParts) == 0 {
+		return indexParams, nil
+	}
+	prefixLengths := make(map[string]int, len(keyParts))
+	for _, keyPart := range keyParts {
+		if keyPart != nil && keyPart.ColName != nil && keyPart.Length > 0 {
+			prefixLengths[keyPart.ColName.ColName()] = keyPart.Length
+		}
+	}
+	if len(prefixLengths) == 0 {
 		return indexParams, nil
 	}
 
@@ -311,10 +351,38 @@ func AddIndexPrefixLengthsToParams(indexParams string, keyParts []*tree.KeyPart)
 		}
 		params = existing
 	}
-	params[IndexAlgoParamPrefixLengths] = prefixLengths
+	if err := SetIndexPrefixLengthsInParamMap(params, prefixLengths); err != nil {
+		return "", err
+	}
 	return IndexParamsMapToJsonString(params)
 }
 
+// SetIndexPrefixLengthsInParamMap keeps the legacy representation for ordinary
+// names and switches to a lossless JSON value when a quoted identifier contains
+// a legacy delimiter.
+func SetIndexPrefixLengthsInParamMap(params map[string]string, prefixLengths map[string]int) error {
+	if params == nil {
+		return moerr.NewInvalidInputNoCtx("nil index params map")
+	}
+	delete(params, IndexAlgoParamPrefixLengths)
+	delete(params, IndexAlgoParamPrefixLengthsV2)
+	if len(prefixLengths) == 0 {
+		return nil
+	}
+	for part := range prefixLengths {
+		if strings.ContainsAny(part, ":,") {
+			encoded, err := json.Marshal(prefixLengths)
+			if err != nil {
+				return err
+			}
+			params[IndexAlgoParamPrefixLengthsV2] = string(encoded)
+			return nil
+		}
+	}
+	params[IndexAlgoParamPrefixLengths] = indexPrefixLengthsMapToLegacyString(prefixLengths)
+	return nil
+}
+
 func IndexPrefixLengthsToString(keyParts []*tree.KeyPart) string {
 	if len(keyParts) == 0 {
 		return ""
@@ -331,6 +399,13 @@ func IndexPrefixLengthsToString(keyParts []*tree.KeyPart) string {
 		return ""
 	}
 
+	return indexPrefixLengthsMapToLegacyString(prefixLengths)
+}
+
+func indexPrefixLengthsMapToLegacyString(prefixLengths map[string]int) string {
+	if len(prefixLengths) == 0 {
+		return ""
+	}
 	parts := make([]string, 0, len(prefixLengths))
 	for part := range prefixLengths {
 		parts = append(parts, part)
@@ -361,6 +436,22 @@ func IndexPrefixLengthsFromParamsWithError(indexParams string) (map[string]int,
 		return nil, err
 	}
 
+	if encoded, ok := params[IndexAlgoParamPrefixLengthsV2]; ok {
+		if encoded == "" {
+			return nil, nil
+		}
+		prefixLengths := make(map[string]int)
+		if err := json.Unmarshal([]byte(encoded), &prefixLengths); err != nil {
+			return nil, moerr.NewInvalidInputNoCtxf("invalid v2 index prefix lengths %q", encoded)
+		}
+		for part, length := range prefixLengths {
+			if part == "" || length <= 0 {
+				return nil, moerr.NewInvalidInputNoCtxf("invalid v2 index prefix length %q", encoded)
+			}
+		}
+		return prefixLengths, nil
+	}
+
 	encoded := params[IndexAlgoParamPrefixLengths]
 	if encoded == "" {
 		return nil, nil
@@ -496,6 +587,33 @@ func IsIndexAsync(indexAlgoParams string) (bool, error) {
 	return false, nil
 }
 
+// IndexParamAsync is the descriptive name used by the index-plugin framework.
+// Keep IsIndexAsync above as a compatibility wrapper for existing callers.
+func IndexParamAsync(indexAlgoParams string) (bool, error) {
+	return IsIndexAsync(indexAlgoParams)
+}
+
+// IndexAlgoParamVersionOf returns the engine version recorded in algo_params.
+// Missing or malformed values are legacy/classic version 1.
+func IndexAlgoParamVersionOf(indexAlgoParams string) int64 {
+	if len(indexAlgoParams) == 0 {
+		return 1
+	}
+	val, err := sonic.Get([]byte(indexAlgoParams), IndexAlgoParamVersion)
+	if err != nil {
+		return 1
+	}
+	s, err := val.StrictString()
+	if err != nil {
+		return 1
+	}
+	n, err := strconv.ParseInt(s, 10, 64)
+	if err != nil {
+		return 1
+	}
+	return n
+}
+
 //------------------------[END] IndexAlgoParams------------------------
 
 // ------------------------[START] Aliaser------------------------