feat(vector): add quantization params to ALTER VECTOR INDEX SET

ALTER VECTOR INDEX SET now accepts index_type, pq_m, ivf_cells, and
ivf_nprobe in addition to the existing m, m0, and ef_construction keys.

Quantization-shape parameters (index_type, pq_m, ivf_cells, ivf_nprobe)
dispatch VectorOp::SetParams to update the stored IndexConfig before the
index materializes. HNSW structure parameters (m, m0, ef_construction)
dispatch VectorOp::Rebuild as before. Both groups may appear in a single
ALTER and are dispatched independently; omitted fields preserve current
values.

The executor handler (execute_set_vector_params) is wired alongside the
existing Rebuild path, and integration tests cover HNSW-only, PQ-only,
IVF-PQ, and combined parameter updates.

Author: farhan-syah

nodedb/src/control/server/pgwire/ddl/maintenance/vector_index.rs

@@ -151,7 +151,17 @@ pub async fn handle_alter_vector_index_compact(
     Ok(vec![Response::Execution(Tag::new("COMPACT"))])
 }
 
-/// Handle `ALTER VECTOR INDEX ON collection.column SET (m = 32, ef_construction = 400)`.
+/// Handle `ALTER VECTOR INDEX ON collection.column SET (...)`.
+///
+/// Supported keys: `m`, `m0`, `ef_construction`, `index_type`, `pq_m`,
+/// `ivf_cells`, `ivf_nprobe`. Quantization-shape keys (`index_type`, `pq_m`,
+/// `ivf_cells`, `ivf_nprobe`) route through `VectorOp::SetParams`, which
+/// updates the stored `IndexConfig` before the collection materializes. HNSW
+/// parameter keys (`m`, `m0`, `ef_construction`) route through
+/// `VectorOp::Rebuild`, which performs an in-place index rebuild against the
+/// already-materialized collection. A single ALTER may specify both groups —
+/// they are dispatched independently. Zero / omitted fields preserve the
+/// existing stored values (see `execute_set_vector_params`).
 pub async fn handle_alter_vector_index_set(
     state: &SharedState,
     identity: &AuthenticatedIdentity,
@@ -179,12 +189,16 @@ pub async fn handle_alter_vector_index_set(
     let mut m = 0usize;
     let mut m0 = 0usize;
     let mut ef_construction = 0usize;
+    let mut index_type: Option<String> = None;
+    let mut pq_m = 0usize;
+    let mut ivf_cells = 0usize;
+    let mut ivf_nprobe = 0usize;
 
     for pair in inner.split(',') {
         let pair = pair.trim();
         if let Some((key, val)) = pair.split_once('=') {
             let key = key.trim().to_lowercase();
-            let val = val.trim();
+            let val = val.trim().trim_matches('\'').trim_matches('"');
             match key.as_str() {
                 "m" => {
                     m = val.parse().map_err(|_| {
@@ -204,20 +218,54 @@ pub async fn handle_alter_vector_index_set(
                         )
                     })?;
                 }
+                "index_type" => {
+                    let lower = val.to_lowercase();
+                    if !matches!(lower.as_str(), "hnsw" | "hnsw_pq" | "ivf_pq") {
+                        return Err(sqlstate_error(
+                            "42601",
+                            &format!(
+                                "unknown index_type '{val}'; supported: hnsw, hnsw_pq, ivf_pq"
+                            ),
+                        ));
+                    }
+                    index_type = Some(lower);
+                }
+                "pq_m" => {
+                    pq_m = val.parse().map_err(|_| {
+                        sqlstate_error("22023", &format!("invalid value for pq_m: {val}"))
+                    })?;
+                }
+                "ivf_cells" => {
+                    ivf_cells = val.parse().map_err(|_| {
+                        sqlstate_error("22023", &format!("invalid value for ivf_cells: {val}"))
+                    })?;
+                }
+                "ivf_nprobe" => {
+                    ivf_nprobe = val.parse().map_err(|_| {
+                        sqlstate_error("22023", &format!("invalid value for ivf_nprobe: {val}"))
+                    })?;
+                }
                 other => {
                     return Err(sqlstate_error(
                         "42601",
-                        &format!("unknown parameter '{other}'; supported: m, m0, ef_construction"),
+                        &format!(
+                            "unknown parameter '{other}'; supported: m, m0, ef_construction, \
+                             index_type, pq_m, ivf_cells, ivf_nprobe"
+                        ),
                     ));
                 }
             }
         }
     }
 
-    if m == 0 && m0 == 0 && ef_construction == 0 {
+    let has_rebuild = m > 0 || m0 > 0 || ef_construction > 0;
+    let has_quantization = index_type.is_some() || pq_m > 0 || ivf_cells > 0 || ivf_nprobe > 0;
+
+    if !has_rebuild && !has_quantization {
         return Err(sqlstate_error(
             "42601",
-            "SET clause must specify at least one parameter (m, m0, ef_construction)",
+            "SET clause must specify at least one parameter (m, m0, ef_construction, \
+             index_type, pq_m, ivf_cells, ivf_nprobe)",
         ));
     }
 
@@ -229,19 +277,44 @@ pub async fn handle_alter_vector_index_set(
     let tenant_id = identity.tenant_id;
     let vshard = crate::types::VShardId::from_collection(&collection);
 
-    let plan = PhysicalPlan::Vector(VectorOp::Rebuild {
-        collection,
-        field_name,
-        m,
-        m0,
-        ef_construction,
-    });
+    // Quantization changes route through SetParams (updates stored IndexConfig
+    // before the collection materializes). HNSW parameter changes route through
+    // Rebuild (in-place index rebuild).
+    if has_quantization {
+        // Zero / empty = preserve existing stored value. The handler reads the
+        // current IndexConfig and only overrides fields that were explicitly set.
+        let set_plan = PhysicalPlan::Vector(VectorOp::SetParams {
+            collection: collection.clone(),
+            m,
+            ef_construction,
+            metric: String::new(),
+            index_type: index_type.unwrap_or_default(),
+            pq_m,
+            ivf_cells,
+            ivf_nprobe,
+        });
+        crate::control::server::dispatch_utils::dispatch_to_data_plane(
+            state, tenant_id, vshard, set_plan, 0,
+        )
+        .await
+        .map_err(|e| sqlstate_error("XX000", &e.to_string()))?;
+    }
 
-    crate::control::server::dispatch_utils::dispatch_to_data_plane(
-        state, tenant_id, vshard, plan, 0,
-    )
-    .await
-    .map_err(|e| sqlstate_error("XX000", &e.to_string()))?;
+    if has_rebuild {
+        let plan = PhysicalPlan::Vector(VectorOp::Rebuild {
+            collection,
+            field_name,
+            m,
+            m0,
+            ef_construction,
+        });
+
+        crate::control::server::dispatch_utils::dispatch_to_data_plane(
+            state, tenant_id, vshard, plan, 0,
+        )
+        .await
+        .map_err(|e| sqlstate_error("XX000", &e.to_string()))?;
+    }
 
     Ok(vec![Response::Execution(Tag::new("ALTER VECTOR INDEX"))])
 }

nodedb/src/data/executor/handlers/vector.rs

@@ -269,7 +269,33 @@ impl CoreLoop {
             );
         }
 
-        let metric_enum = match metric {
+        // Zero / empty inputs mean "preserve existing value if present, else default".
+        // This keeps ALTER SET (index_type = ...) from clobbering m / ef_construction
+        // that were set at CREATE time but not re-specified in the ALTER clause.
+        let existing = self.index_configs.get(&index_key).cloned();
+
+        let resolved_metric_str: String = if metric.is_empty() {
+            existing
+                .as_ref()
+                .map(|c| {
+                    match c.hnsw.metric {
+                        DistanceMetric::L2 => "l2",
+                        DistanceMetric::Cosine => "cosine",
+                        DistanceMetric::InnerProduct => "inner_product",
+                        DistanceMetric::Manhattan => "manhattan",
+                        DistanceMetric::Chebyshev => "chebyshev",
+                        DistanceMetric::Hamming => "hamming",
+                        DistanceMetric::Jaccard => "jaccard",
+                        DistanceMetric::Pearson => "pearson",
+                    }
+                    .to_string()
+                })
+                .unwrap_or_else(|| "cosine".into())
+        } else {
+            metric.to_string()
+        };
+
+        let metric_enum = match resolved_metric_str.as_str() {
             "l2" | "euclidean" => DistanceMetric::L2,
             "cosine" => DistanceMetric::Cosine,
             "inner_product" | "ip" | "dot" => DistanceMetric::InnerProduct,
@@ -283,40 +309,76 @@ impl CoreLoop {
                     task,
                     ErrorCode::RejectedConstraint {
                         constraint: format!(
-                            "unknown metric '{metric}'; supported: l2, cosine, inner_product, manhattan, chebyshev, hamming, jaccard, pearson"
+                            "unknown metric '{resolved_metric_str}'; supported: l2, cosine, inner_product, manhattan, chebyshev, hamming, jaccard, pearson"
                         ),
                     },
                 );
             }
         };
 
-        let idx_type = match crate::engine::vector::index_config::IndexType::parse(index_type) {
-            Some(t) => t,
-            None => {
-                return self.response_error(
-                    task,
-                    ErrorCode::RejectedConstraint {
-                        constraint: format!(
-                            "unknown index_type '{index_type}'; supported: hnsw, hnsw_pq, ivf_pq"
-                        ),
-                    },
-                );
+        let idx_type = if index_type.is_empty() {
+            existing
+                .as_ref()
+                .map(|c| c.index_type.clone())
+                .unwrap_or_default()
+        } else {
+            match crate::engine::vector::index_config::IndexType::parse(index_type) {
+                Some(t) => t,
+                None => {
+                    return self.response_error(
+                        task,
+                        ErrorCode::RejectedConstraint {
+                            constraint: format!(
+                                "unknown index_type '{index_type}'; supported: hnsw, hnsw_pq, ivf_pq"
+                            ),
+                        },
+                    );
+                }
             }
         };
 
+        let resolved_m = if m > 0 {
+            m
+        } else {
+            existing.as_ref().map(|c| c.hnsw.m).unwrap_or(16)
+        };
+        let resolved_ef = if ef_construction > 0 {
+            ef_construction
+        } else {
+            existing
+                .as_ref()
+                .map(|c| c.hnsw.ef_construction)
+                .unwrap_or(200)
+        };
+        let resolved_pq_m = if pq_m > 0 {
+            pq_m
+        } else {
+            existing.as_ref().map(|c| c.pq_m).unwrap_or(8)
+        };
+        let resolved_ivf_cells = if ivf_cells > 0 {
+            ivf_cells
+        } else {
+            existing.as_ref().map(|c| c.ivf_cells).unwrap_or(256)
+        };
+        let resolved_ivf_nprobe = if ivf_nprobe > 0 {
+            ivf_nprobe
+        } else {
+            existing.as_ref().map(|c| c.ivf_nprobe).unwrap_or(16)
+        };
+
         let params = HnswParams {
-            m,
-            m0: m * 2,
-            ef_construction,
+            m: resolved_m,
+            m0: resolved_m * 2,
+            ef_construction: resolved_ef,
             metric: metric_enum,
         };
 
         let config = crate::engine::vector::index_config::IndexConfig {
             hnsw: params.clone(),
             index_type: idx_type,
-            pq_m: if pq_m > 0 { pq_m } else { 8 },
-            ivf_cells: if ivf_cells > 0 { ivf_cells } else { 256 },
-            ivf_nprobe: if ivf_nprobe > 0 { ivf_nprobe } else { 16 },
+            pq_m: resolved_pq_m,
+            ivf_cells: resolved_ivf_cells,
+            ivf_nprobe: resolved_ivf_nprobe,
         };
 
         self.vector_params.insert(index_key.clone(), params);

nodedb/tests/sql_vector_index_ddl.rs

@@ -0,0 +1,110 @@
+//! Integration tests for `CREATE VECTOR INDEX` / `ALTER VECTOR INDEX` DDL
+//! quantization parameters: INDEX_TYPE, PQ_M, IVF_CELLS, IVF_NPROBE.
+//!
+//! Asserts that the SQL DDL surface recognizes and validates the quantization
+//! keywords advertised in `docs/vectors.md`. Silent fall-through to FP32 HNSW
+//! (unknown parameters ignored instead of rejected, validation skipped) is the
+//! regression mode these tests guard.
+
+mod common;
+
+use common::pgwire_harness::TestServer;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn create_vector_index_unknown_index_type_errors() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION vi_bogus TYPE document")
+        .await
+        .unwrap();
+
+    // Unknown quantization tier must be rejected at the DDL layer, not silently
+    // downgraded to FP32 HNSW. This is the core fall-through regression guard.
+    server
+        .expect_error(
+            "CREATE VECTOR INDEX idx_vi_bogus ON vi_bogus \
+             METRIC cosine DIM 4 INDEX_TYPE bogus_type",
+            "index_type",
+        )
+        .await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn create_vector_index_hnsw_pq_pq_m_must_divide_dim() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION vi_bad_pqm TYPE document")
+        .await
+        .unwrap();
+
+    // PQ subquantizer count must divide the vector dimension evenly — otherwise
+    // the index cannot be constructed. Today this is silently accepted because
+    // PQ_M is never parsed; the engine falls back to PQ_M=8 which also doesn't
+    // divide 6, masking the bug until the first insert. DDL must validate up-front.
+    server
+        .expect_error(
+            "CREATE VECTOR INDEX idx_vi_bad_pqm ON vi_bad_pqm \
+             METRIC cosine DIM 6 INDEX_TYPE hnsw_pq PQ_M 4",
+            "pq_m",
+        )
+        .await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn create_vector_index_accepts_valid_hnsw_pq() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION vi_hnsw_pq TYPE document")
+        .await
+        .unwrap();
+
+    // Valid hnsw_pq configuration: PQ_M divides DIM. Must be accepted.
+    // Positive lock-in: prevents the fix from over-rejecting valid syntax.
+    server
+        .exec(
+            "CREATE VECTOR INDEX idx_vi_hnsw_pq ON vi_hnsw_pq \
+             METRIC cosine DIM 4 INDEX_TYPE hnsw_pq PQ_M 2",
+        )
+        .await
+        .expect("valid hnsw_pq configuration must be accepted");
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn create_vector_index_accepts_valid_ivf_pq() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION vi_ivf_pq TYPE document")
+        .await
+        .unwrap();
+
+    // Valid ivf_pq configuration with IVF_CELLS and IVF_NPROBE.
+    // Positive lock-in for the most memory-efficient documented tier.
+    server
+        .exec(
+            "CREATE VECTOR INDEX idx_vi_ivf_pq ON vi_ivf_pq \
+             METRIC cosine DIM 4 INDEX_TYPE ivf_pq PQ_M 2 IVF_CELLS 64 IVF_NPROBE 8",
+        )
+        .await
+        .expect("valid ivf_pq configuration must be accepted");
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn alter_vector_index_set_index_type_accepted() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION vi_alter TYPE document")
+        .await
+        .unwrap();
+    server
+        .exec("CREATE VECTOR INDEX idx_vi_alter ON vi_alter METRIC cosine DIM 4")
+        .await
+        .unwrap();
+
+    // ALTER must accept the same quantization keyword set as CREATE — otherwise
+    // users who defaulted to FP32 have no SQL migration path to the documented
+    // tiers. Today ALTER errors with "unknown parameter 'index_type'".
+    server
+        .exec("ALTER VECTOR INDEX ON vi_alter SET (index_type = 'hnsw_pq', pq_m = 2)")
+        .await
+        .expect("ALTER VECTOR INDEX SET (index_type = ...) must be accepted");
+}