pingcap/tidb · error

TiFlash does not support vector index with pedicates

Error message

TiFlash does not support vector index with pedicates

What it means

A planner assertion in tiflash_predicate_push_down.go: for a large table (RealtimeCount > tiflashDataPackSize), not KeepOrder, with non-empty FilterCondition - i.e. predicates would be pushed to a TiFlash scan - the code verifies no used columnar index is a vector index, because TiFlash cannot serve a vector index scan together with predicates. If ts.UsedColumnWith VectorInfo is found it panics (message typo 'pedicates' included) rather than generating an unsupported plan.

Source

Thrown at pkg/planner/core/operator/physicalop/tiflash_predicate_push_down.go:281

// handleTiFlashPredicatePushDown is used to handle the TiFlash predicate push down.
// 1. Whether to use the inverted index.
// 2. Whether to push down the conditions to the table scan.
func handleTiFlashPredicatePushDown(pctx base.PlanContext, ts *PhysicalTableScan, indexHints []*ast.IndexHint) {
	// When the table is small, there is no need to push down the conditions.
	if ts.TblColHists.RealtimeCount <= tiflashDataPackSize || ts.KeepOrder || len(ts.FilterCondition) == 0 {
		return
	}

	// Currently, TiFlash does not support vector index with predicates.
	// So for now, one DataSource only contains one TiFlash !keepOrder path,
	// which means that the following code will only be executed once.
	// TODO: If there are multiple TiFlash !keepOrder paths in one DataSource in the future,
	// we need to move the following code to another place.
	// Since caculating selectivity is expensive, we need to avoid duplicate execution.
	for _, index := range ts.UsedColumnarIndexes {
		if index.IndexInfo.VectorInfo != nil {
			panic("TiFlash does not support vector index with pedicates")
		}
	}

	// Consider use index hints
	indexMap := make(map[string]int, len(ts.Table.Indices))
	for _, hint := range indexHints {
		if hint.HintScope != ast.HintForScan {
			continue
		}

		switch hint.HintType {
		case ast.HintUse:
			for _, name := range hint.IndexNames {
				if indexMap[name.L] != math.MaxInt {
					indexMap[name.L]++
				}
			}
		case ast.HintIgnore:

View on GitHub (pinned to d01f9615c1)

Solutions

1. Upgrade TiDB to a version where vector index plus predicate handling is complete and this invariant cannot be violated.
2. Rewrite the query so predicates and the vector index do not share one plan: do the vector search into a subquery/CTE and apply filters outside it.
3. Remove any index hints (USE_INDEX / USE_VECTOR_INDEX / read_from_storage hints) that force the vector index on the filtered scan.
4. If it reproduces without hints on the latest version, report it at github.com/pingcap/tidb with the query, table schema, and EXPLAIN output.

Example fix

-- before: filter + vector index in one scan can trip the planner assertion
SELECT id FROM docs WHERE content_vec <@ '[1,2,3]' AND category = 5 LIMIT 10;

-- after: isolate the ANN search, then filter
WITH ann AS (
  SELECT id FROM docs ORDER BY content_vec <@ '[1,2,3]' LIMIT 100
)
SELECT a.id FROM ann a JOIN docs d ON d.id = a.id WHERE d.category = 5;

-- before relying on a vector index with filters, check plan shape: the ANN scan
-- must appear as a separate TABLE_SCAN/VectorScan without pushed predicates
EXPLAIN SELECT id FROM docs WHERE content_vec <@ '[1,2,3]' AND category = 5;
-- if predicates sit on the same TiFlash scan as the vector index, rewrite the query

When it happens

Trigger: A SELECT over a table with a VECTOR index where the planner both keeps the vector index as a UsedColumnarIndexes entry AND pushes a WHERE predicate into the TiFlash !KeepOrder path - normally prevented upstream by forcing vector-index plans to bypass this path (e.g. via VECTOR_INDEX hints on filtered queries). Reaching the panic means the guard failed, typically a planner bug.

Common situations: Using a vector index (ANN search) together with additional WHERE filters in versions where the vector-index-with-predicates plan path was incomplete (feature in preview/beta); index hints like /*+ USE_VECTOR_INDEX(...) */ combined with filters forcing the predicate-push-down branch; upgrading TiDB and hitting a regression in the vector index plan pruning.

Related errors

• Out Of Global Memory Limit!
• Out Of Global Analyze Memory Limit!
• Out Of Quota For Local Temporary Space!
• Out of Unknown Resource Quota!
• fail to create iterator

AI-assisted analysis of pingcap/tidb@d01f9615c1 (2026-08-15). Data as JSON: /api/errors/6689405d50a60a2d. Report an issue: GitHub.