refactor(sql): unify CREATE ... INDEX DDL parsing through a shared grammar

Route vector, fulltext/search, sparse, and spatial index DDL through a
common options/header parser instead of each handler hand-splitting
tokens, so an unrecognized option is now a parse error rather than a
silently skipped token. Split the vector apply_put handler into a
directory and add a dedicated vector_params module to keep the
resulting executor and WAL-replay plumbing consistent with the new
grammar.

Author: farhan-syah

docs/full-text-search.md

@@ -39,6 +39,12 @@ CREATE SEARCH INDEX ON articles FIELDS title, body
     ANALYZER 'english'
     FUZZY true;
 
+-- `CREATE FULLTEXT INDEX` is an exact alias, and the column list may also be
+-- written in parentheses. ANALYZER takes 'standard' or a supported language
+-- name; an unknown name is rejected rather than silently falling back.
+-- FUZZY sets the collection default — queries may still opt in per call.
+CREATE FULLTEXT INDEX idx_articles_text ON articles (title, body) ANALYZER 'english';
+
 -- Basic search with text_match
 SELECT title, bm25_score(body, 'distributed database rust') AS score
 FROM articles

docs/vectors.md

@@ -36,6 +36,11 @@ NodeDB's vector engine is built for production semantic search — not vectors s
 CREATE COLLECTION articles;
 CREATE VECTOR INDEX idx_articles_embedding ON articles METRIC cosine DIM 384;
 
+-- DIM is required and is enforced on every write: an embedding of any other
+-- width is rejected at INSERT rather than quietly indexed at the wrong size.
+-- Name the column explicitly to carry several embeddings on one collection.
+CREATE VECTOR INDEX idx_articles_clip ON articles (clip_embedding) METRIC cosine DIM 512;
+
 -- Insert documents with embeddings
 INSERT INTO articles {
     title: 'Understanding Transformers',

nodedb-cluster-tests/tests/cluster_array.rs

@@ -285,7 +285,7 @@ async fn cluster_array_vector_prefilter_distributed() {
         .expect("CREATE COLLECTION genes");
     cluster
         .exec_ddl_on_any_leader(
-            "CREATE VECTOR INDEX idx_genes_emb ON genes FIELD embedding METRIC cosine DIM 3",
+            "CREATE VECTOR INDEX idx_genes_emb ON genes (embedding) METRIC cosine DIM 3",
         )
         .await
         .expect("CREATE VECTOR INDEX");

nodedb-fts/src/index/analyzer_config.rs

@@ -3,8 +3,9 @@
 //! Per-collection analyzer configuration stored in backend metadata.
 //!
 //! Uses structural `(tid, collection, subkey)` meta blobs:
-//! - `subkey = "analyzer"` → analyzer name (e.g. "german", "cjk_bigram")
+//! - `subkey = "analyzer"` → analyzer name (e.g. "german", "standard")
 //! - `subkey = "language"` → lang code (e.g. "de", "ja")
+//! - `subkey = "fuzzy"` → `"1"` when the collection defaults to fuzzy matching
 //!
 //! Applied automatically at both index time and query time.
 
@@ -49,6 +50,37 @@ impl<B: FtsBackend> FtsIndex<B> {
         )
     }
 
+    /// Set whether searches over this collection fall back to fuzzy
+    /// (Levenshtein) matching by default. Persists to backend metadata.
+    pub fn set_collection_fuzzy(
+        &self,
+        database_id: u64,
+        tid: u64,
+        collection: &str,
+        fuzzy: bool,
+    ) -> Result<(), B::Error> {
+        self.backend.write_meta(
+            database_id,
+            tid,
+            collection,
+            "fuzzy",
+            if fuzzy { b"1" } else { b"0" },
+        )
+    }
+
+    /// Whether this collection defaults to fuzzy matching. `false` when unset.
+    pub fn get_collection_fuzzy(
+        &self,
+        database_id: u64,
+        tid: u64,
+        collection: &str,
+    ) -> Result<bool, B::Error> {
+        Ok(self
+            .backend
+            .read_meta(database_id, tid, collection, "fuzzy")?
+            .is_some_and(|bytes| bytes.as_slice() == b"1"))
+    }
+
     /// Get the configured analyzer name for a collection.
     pub fn get_collection_analyzer(
         &self,
@@ -115,6 +147,20 @@ impl<B: FtsBackend> FtsIndex<B> {
     }
 }
 
+/// Whether `name` resolves to a real analyzer.
+///
+/// [`resolve_analyzer`] falls back to the standard analyzer for anything it
+/// does not know, which silently turns a misspelled analyzer name into a
+/// different analyzer. Callers that accept a name from a user — DDL, config —
+/// gate on this first so the fallback is only ever reached for a name that
+/// was already checked. The two must stay in step: every arm below has a
+/// matching arm there.
+pub fn analyzer_exists(name: &str) -> bool {
+    name == "standard"
+        || LanguageAnalyzer::new(name).is_some()
+        || NoStemAnalyzer::new(name).is_some()
+}
+
 /// Resolve an analyzer name to a `Box<dyn TextAnalyzer>`.
 fn resolve_analyzer(name: &str) -> Box<dyn TextAnalyzer> {
     match name {

nodedb-fts/src/search/bm25_search.rs

@@ -82,6 +82,16 @@ impl<B: FtsBackend> FtsIndex<B> {
             mode,
             prefilter,
         } = params;
+        // A collection configured with `FUZZY true` falls back to fuzzy
+        // matching even when the query did not ask for it — that is what
+        // makes it an index property rather than a per-query flag. Resolved
+        // here, at the one point every search path funnels through, so no
+        // caller can be wired up without it.
+        let fuzzy_enabled = fuzzy_enabled
+            || self
+                .get_collection_fuzzy(database_id, tid, collection)
+                .map_err(FtsIndexError::backend)?;
+
         // Parse the query for NOT / - negation operators before analysis.
         let parsed = parse_query(query)?;
 

nodedb-physical/src/physical_plan/mod.rs

@@ -279,7 +279,7 @@ impl PhysicalPlan {
             | PhysicalPlan::Text(TextOp::BM25ScoreScan { collection, .. })
             | PhysicalPlan::Text(TextOp::FtsIndexDoc { collection, .. })
             | PhysicalPlan::Text(TextOp::FtsDeleteDoc { collection, .. })
-            | PhysicalPlan::Text(TextOp::SetAnalyzer { collection, .. })
+            | PhysicalPlan::Text(TextOp::SetTextConfig { collection, .. })
             | PhysicalPlan::Query(QueryOp::PartialAggregate { collection, .. })
             | PhysicalPlan::Query(QueryOp::FacetCounts { collection, .. })
             | PhysicalPlan::Document(DocumentOp::BulkUpdate { collection, .. })

nodedb-physical/src/physical_plan/text.rs

@@ -147,11 +147,15 @@ pub enum TextOp {
     /// the in-transaction staged-write overlay, and query-time scoring alike.
     /// Config-only, single-node, non-WAL-durable — the same dispatch shape
     /// `VectorOp::SetParams` uses for `CREATE VECTOR INDEX`.
-    SetAnalyzer {
+    SetTextConfig {
         collection: String,
-        /// Analyzer name (e.g. "standard", "simple", "english", "cjk_bigram").
-        /// Unrecognized names fall back to the standard analyzer at resolve
-        /// time (see `nodedb_fts::index::analyzer_config::resolve_analyzer`).
-        analyzer_name: String,
+        /// Analyzer name, already checked against
+        /// `nodedb_fts::index::analyzer_config::analyzer_exists` by the DDL
+        /// layer (e.g. "standard", "english", "japanese"). `None` leaves the
+        /// collection's current analyzer in place.
+        analyzer_name: Option<String>,
+        /// Whether searches over this collection fall back to fuzzy matching
+        /// by default. `None` leaves the current setting in place.
+        fuzzy_default: Option<bool>,
     },
 }

nodedb-physical/src/physical_plan/vector.rs

@@ -130,6 +130,11 @@ pub enum VectorOp {
         /// default (unnamed) vector field. Lets one collection carry
         /// multiple vector indexes, one per `VECTOR` / embedding column.
         field_name: String,
+        /// Declared vector dimension. Enforced against every vector written
+        /// to this field; `0` means "not declared" and leaves the index to
+        /// adopt the width of whatever arrives first.
+        #[serde(default)]
+        dim: usize,
         m: usize,
         ef_construction: usize,
         metric: String,

nodedb-test-support/src/tx_batch_helpers.rs

@@ -107,6 +107,7 @@ pub fn vector_set_params(collection: &str) -> PhysicalPlan {
     PhysicalPlan::Vector(VectorOp::SetParams {
         collection: collection.into(),
         field_name: String::new(),
+        dim: 0,
         m: 16,
         ef_construction: 200,
         metric: "cosine".into(),

nodedb-types/src/protocol/text_fields/decode.rs

@@ -320,6 +320,9 @@ impl<'a> zerompk::FromMessagePack<'a> for TextFields {
                 FID_INDEX_TYPE => {
                     out.index_type = Some(reader.read_string()?.into_owned());
                 }
+                FID_VECTOR_DIM => {
+                    out.vector_dim = Some(reader.read_u32()?);
+                }
                 FID_DATABASE => {
                     out.database = Some(reader.read_string()?.into_owned());
                 }