enhance: add switch for query driver prefetch (#51081)

issue: #51252

## What
- Add `common.enableDriverPrefetch` with default `false`.
- Wire the config into segcore via initcore and a refresh callback.
- Skip `Driver::PrefetchAsync()` when the switch is disabled.

## Why
This provides a runtime mitigation for regressions caused by query
driver operator prefetch on short scalar queries, while keeping prefetch
configurable for follow-up validation.

## Notes
When disabled, expression execution path determination still runs lazily
on the query thread; this only disables driver-level async prefetch
submission/waiting.

## Tests
- `make generate-yaml`
- `CLANG_FORMAT=/opt/homebrew/opt/llvm@15/bin/clang-format
internal/core/run_clang_format.sh internal/core`
- `make lint-fix`

Signed-off-by: sunby <sunbingyi1992@gmail.com>

configs/milvus.yaml

@@ -1127,6 +1127,7 @@ common:
   sync:
     taskPoolReleaseTimeoutSeconds: 60 # The maximum time to wait for the task to finish and release resources in the pool
   enabledOptimizeExpr: true # Indicates whether to enable optimize expr
+  enableDriverPrefetch: false # Indicates whether to enable query driver prefetch in segcore.
   enabledJSONShredding: true # Indicates sealedsegment whether to enable JSON key stats
   enabledGrowingSegmentJSONShredding: false # Indicates growingsegment whether to enable JSON key stats
   enableConfigParamTypeCheck: true # Indicates whether to enable config param type check

internal/core/src/common/Common.cpp

@@ -34,6 +34,7 @@ std::atomic<int64_t> DELETE_DUMP_BATCH_SIZE(DEFAULT_DELETE_DUMP_BATCH_SIZE);
 std::atomic<bool> ENABLE_LATEST_DELETE_SNAPSHOT_OPTIMIZATION(
     DEFAULT_ENABLE_LATEST_DELETE_SNAPSHOT_OPTIMIZATION);
 std::atomic<bool> OPTIMIZE_EXPR_ENABLED(DEFAULT_OPTIMIZE_EXPR_ENABLED);
+std::atomic<bool> ENABLE_DRIVER_PREFETCH(DEFAULT_ENABLE_DRIVER_PREFETCH);
 
 std::atomic<bool> JSON_KEY_STATS_ENABLED(DEFAULT_JSON_KEY_STATS_ENABLED);
 
@@ -82,6 +83,13 @@ SetDefaultOptimizeExprEnable(bool val) {
              OPTIMIZE_EXPR_ENABLED.load());
 }
 
+void
+SetDefaultDriverPrefetchEnable(bool val) {
+    ENABLE_DRIVER_PREFETCH.store(val);
+    LOG_INFO("set default driver prefetch enabled: {}",
+             ENABLE_DRIVER_PREFETCH.load());
+}
+
 void
 SetDefaultJSONKeyStatsEnable(bool val) {
     JSON_KEY_STATS_ENABLED.store(val);

internal/core/src/common/Common.h

@@ -30,6 +30,7 @@ extern std::atomic<int64_t> EXEC_EVAL_EXPR_BATCH_SIZE;
 extern std::atomic<int64_t> DELETE_DUMP_BATCH_SIZE;
 extern std::atomic<bool> ENABLE_LATEST_DELETE_SNAPSHOT_OPTIMIZATION;
 extern std::atomic<bool> OPTIMIZE_EXPR_ENABLED;
+extern std::atomic<bool> ENABLE_DRIVER_PREFETCH;
 extern std::atomic<bool> JSON_KEY_STATS_ENABLED;
 extern std::atomic<bool> GROWING_JSON_KEY_STATS_ENABLED;
 extern std::atomic<bool> CONFIG_PARAM_TYPE_CHECK_ENABLED;
@@ -50,6 +51,9 @@ SetDefaultDeleteDumpBatchSize(int64_t val);
 void
 SetDefaultOptimizeExprEnable(bool val);
 
+void
+SetDefaultDriverPrefetchEnable(bool val);
+
 void
 SetDefaultJSONKeyStatsEnable(bool val);
 

internal/core/src/common/Consts.h

@@ -112,6 +112,7 @@ const std::string JSON_CAST_TYPE = "json_cast_type";
 const std::string JSON_PATH = "json_path";
 const std::string JSON_CAST_FUNCTION = "json_cast_function";
 const bool DEFAULT_OPTIMIZE_EXPR_ENABLED = true;
+const bool DEFAULT_ENABLE_DRIVER_PREFETCH = true;
 const int64_t DEFAULT_CONVERT_OR_TO_IN_NUMERIC_LIMIT = 150;
 const int64_t DEFAULT_JSON_INDEX_MEMORY_BUDGET = 16777216;  // bytes, 16MB
 const bool DEFAULT_JSON_KEY_STATS_ENABLED = true;

internal/core/src/common/init_c.cpp

@@ -91,6 +91,11 @@ SetDefaultOptimizeExprEnable(bool val) {
     milvus::SetDefaultOptimizeExprEnable(val);
 }
 
+void
+SetDefaultDriverPrefetchEnable(bool val) {
+    milvus::SetDefaultDriverPrefetchEnable(val);
+}
+
 void
 SetDefaultJSONKeyStatsEnable(bool val) {
     milvus::SetDefaultJSONKeyStatsEnable(val);

internal/core/src/common/init_c.h

@@ -55,6 +55,9 @@ SetDefaultDeleteDumpBatchSize(int64_t val);
 void
 SetDefaultOptimizeExprEnable(bool val);
 
+void
+SetDefaultDriverPrefetchEnable(bool val);
+
 void
 SetDefaultJSONKeyStatsEnable(bool val);
 

internal/core/src/exec/Driver.cpp

@@ -25,6 +25,7 @@
 #include <memory>
 #include <string>
 
+#include "common/Common.h"
 #include "common/EasyAssert.h"
 #include "common/Exception.h"
 #include "common/Tracer.h"
@@ -284,7 +285,9 @@ Driver::RunInternal(std::shared_ptr<Driver>& self,
                     RowVectorPtr& result) {
     try {
         initializeOperators();
-        std::call_once(self->once_, [self]() { self->PrefetchAsync(); });
+        if (ENABLE_DRIVER_PREFETCH.load(std::memory_order_relaxed)) {
+            std::call_once(self->once_, [self]() { self->PrefetchAsync(); });
+        }
         int num_operators = operators_.size();
         ContinueFuture future;
 

internal/util/initcore/init_core.go

@@ -605,6 +605,15 @@ func SetupCoreConfigChangelCallback() {
 			return nil
 		})
 
+		paramtable.Get().CommonCfg.EnableDriverPrefetch.RegisterCallback(func(ctx context.Context, key, oldValue, newValue string) error {
+			enable, err := strconv.ParseBool(newValue)
+			if err != nil {
+				return err
+			}
+			UpdateDefaultDriverPrefetchEnable(enable)
+			return nil
+		})
+
 		paramtable.Get().CommonCfg.EnabledJSONKeyStats.RegisterCallback(func(ctx context.Context, key, oldValue, newValue string) error {
 			enable, err := strconv.ParseBool(newValue)
 			if err != nil {

internal/util/initcore/query_node.go

@@ -140,6 +140,9 @@ func doInitQueryNodeOnce(ctx context.Context) error {
 	cOptimizeExprEnabled := C.bool(paramtable.Get().CommonCfg.EnabledOptimizeExpr.GetAsBool())
 	C.SetDefaultOptimizeExprEnable(cOptimizeExprEnabled)
 
+	cDriverPrefetchEnabled := C.bool(paramtable.Get().CommonCfg.EnableDriverPrefetch.GetAsBool())
+	C.SetDefaultDriverPrefetchEnable(cDriverPrefetchEnabled)
+
 	cJSONKeyStatsEnabled := C.bool(paramtable.Get().CommonCfg.EnabledJSONKeyStats.GetAsBool())
 	C.SetDefaultJSONKeyStatsEnable(cJSONKeyStatsEnabled)
 

internal/util/initcore/util.go

@@ -83,6 +83,10 @@ func UpdateDefaultOptimizeExprEnable(enable bool) {
 	C.SetDefaultOptimizeExprEnable(C.bool(enable))
 }
 
+func UpdateDefaultDriverPrefetchEnable(enable bool) {
+	C.SetDefaultDriverPrefetchEnable(C.bool(enable))
+}
+
 func UpdateDefaultJSONKeyStatsEnable(enable bool) {
 	C.SetDefaultJSONKeyStatsEnable(C.bool(enable))
 }

pkg/util/paramtable/component_param.go

@@ -344,6 +344,7 @@ type commonConfig struct {
 	SyncTaskPoolReleaseTimeoutSeconds ParamItem `refreshable:"true"`
 
 	EnabledOptimizeExpr               ParamItem `refreshable:"true"`
+	EnableDriverPrefetch              ParamItem `refreshable:"true"`
 	EnabledJSONKeyStats               ParamItem `refreshable:"true"`
 	EnabledGrowingSegmentJSONKeyStats ParamItem `refreshable:"true"`
 
@@ -1392,6 +1393,15 @@ If enabled, IPv6 ULA/global addresses will be prioritized ahead of IPv4.`,
 	}
 	p.EnabledOptimizeExpr.Init(base.mgr)
 
+	p.EnableDriverPrefetch = ParamItem{
+		Key:          "common.enableDriverPrefetch",
+		Version:      "3.0",
+		DefaultValue: "false",
+		Doc:          "Indicates whether to enable query driver prefetch in segcore.",
+		Export:       true,
+	}
+	p.EnableDriverPrefetch.Init(base.mgr)
+
 	p.UsingJSONStatsForQuery = ParamItem{
 		Key:          "common.usingJSONShreddingForQuery",
 		Version:      "2.6.5",