From 4259a3c76c46b9facb7b6feec165aeed0c153bba Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 11:35:19 +0800
Subject: [PATCH 1/6] [feature] paimon vector support
 <index-type>.fields.<field-name>.<option>

---
 docs/docs/multimodal-table/global-index.mdx   | 29 +++++++++
 .../index/VectorGlobalIndexerFactory.java     | 25 +++++++-
 .../vector/index/VectorGlobalIndexTest.java   |  5 +-
 .../index/VectorGlobalIndexerFactoryTest.java | 60 ++++++++++++++++++-
 4 files changed, 111 insertions(+), 8 deletions(-)

diff --git a/docs/docs/multimodal-table/global-index.mdx b/docs/docs/multimodal-table/global-index.mdx
index 747ccbaa9ad0..8ba1f9ec14ce 100644
--- a/docs/docs/multimodal-table/global-index.mdx
+++ b/docs/docs/multimodal-table/global-index.mdx
@@ -127,6 +127,35 @@ Supported vector index options:
 | `<index-type>.hnsw.ef-construction` | `150` | HNSW construction search width for `ivf-hnsw-flat` and `ivf-hnsw-sq`. |
 | `<index-type>.hnsw.max-level` | `7` | Maximum HNSW level for `ivf-hnsw-flat` and `ivf-hnsw-sq`. |
 
+**Per-Column Options**
+
+The options above can also be set at the table level (in `TBLPROPERTIES`), where they are shared
+by every vector column of the same index type. When a table has multiple vector columns, you can
+scope an option to a single column with `<index-type>.fields.<field-name>.<option>`. The field-level
+form takes precedence over the column-agnostic `<index-type>.<option>` for that column:
+
+```sql
+CREATE TABLE my_table (
+    id INT,
+    title_embedding ARRAY<FLOAT>,
+    image_embedding ARRAY<FLOAT>
+) TBLPROPERTIES (
+    'bucket' = '-1',
+    'row-tracking.enabled' = 'true',
+    'data-evolution.enabled' = 'true',
+    'global-index.enabled' = 'true',
+    -- per-column dimensions
+    'ivf-pq.fields.title_embedding.dimension' = '768',
+    'ivf-pq.fields.image_embedding.dimension' = '512',
+    -- shared by every ivf-pq column, overridden only for 'image_embedding'
+    'ivf-pq.nlist' = '256',
+    'ivf-pq.fields.image_embedding.nlist' = '512'
+);
+```
+
+With the properties above, `title_embedding` is indexed with `nlist=256` while `image_embedding`
+uses `nlist=512`.
+
 **Vector Search**
 
 Search-time options are passed with each vector search request:
diff --git a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
index 354c967b56ad..6d50f0a44246 100644
--- a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
+++ b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
@@ -37,14 +37,20 @@ public abstract class VectorGlobalIndexerFactory implements GlobalIndexerFactory
     public GlobalIndexer create(DataField field, Options options) {
         String identifier = identifier();
         return new VectorGlobalIndexer(
-                field.type(), nativeOptions(field.type(), options, identifier), identifier);
+                field.type(),
+                nativeOptions(field.type(), options, identifier, field.name()),
+                identifier);
     }
 
     static Map<String, String> nativeOptions(
-            DataType fieldType, Options tableOptions, String identifier) {
+            DataType fieldType, Options tableOptions, String identifier, String fieldName) {
         Map<String, String> nativeOptions = new LinkedHashMap<>();
         String optionPrefix = identifier + ".";
-        for (Map.Entry<String, String> entry : tableOptions.toMap().entrySet()) {
+        String fieldPrefix = optionPrefix + "fields." + fieldName + ".";
+        Map<String, String> tableOptionsMap = tableOptions.toMap();
+
+        // First collect index-type level options, e.g. <index-type>.xxx.
+        for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
             String optionKey = entry.getKey();
             if (optionKey.startsWith(optionPrefix)) {
                 String nativeKey = nativeOptionKey(optionKey.substring(optionPrefix.length()));
@@ -53,6 +59,19 @@ static Map<String, String> nativeOptions(
                 }
             }
         }
+
+        // Then collect field level options, e.g. <index-type>.fields.<field-name>.xxx, which take
+        // precedence over the index-type level options for this field.
+        for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
+            String optionKey = entry.getKey();
+            if (optionKey.startsWith(fieldPrefix)) {
+                String nativeKey = nativeOptionKey(optionKey.substring(fieldPrefix.length()));
+                if (nativeKey != null) {
+                    nativeOptions.put(nativeKey, entry.getValue());
+                }
+            }
+        }
+
         nativeOptions.put("index.type", identifier.replace('-', '_'));
         nativeOptions.put(
                 "dimension", String.valueOf(dimension(fieldType, nativeOptions, identifier)));
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexTest.java
index 73f8a4b28f49..b10c843ef20a 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexTest.java
@@ -347,7 +347,7 @@ public void testViaIndexer() throws IOException {
                 new VectorGlobalIndexer(
                         vectorType,
                         VectorGlobalIndexerFactory.nativeOptions(
-                                vectorType, options, IVF_PQ_IDENTIFIER),
+                                vectorType, options, IVF_PQ_IDENTIFIER, fieldName),
                         IVF_PQ_IDENTIFIER);
 
         GlobalIndexFileWriter fileWriter = createFileWriter(indexPath);
@@ -373,7 +373,8 @@ private VectorGlobalIndexWriter createIvfPqWriter(
         return new VectorGlobalIndexWriter(
                 fileWriter,
                 fieldType,
-                VectorGlobalIndexerFactory.nativeOptions(fieldType, options, IVF_PQ_IDENTIFIER),
+                VectorGlobalIndexerFactory.nativeOptions(
+                        fieldType, options, IVF_PQ_IDENTIFIER, fieldName),
                 IVF_PQ_IDENTIFIER);
     }
 
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
index 1caf082f2c4d..b2b413cd88d5 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
@@ -70,7 +70,8 @@ public void testNativeOptionsOnlyUsesIdentifierPrefix() {
                 VectorGlobalIndexerFactory.nativeOptions(
                         new ArrayType(new FloatType()),
                         options,
-                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER);
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
 
         assertThat(nativeOptions)
                 .containsEntry("index.type", "ivf_flat")
@@ -92,7 +93,8 @@ public void testNativeOptionsUsesVectorTypeDimension() {
                 VectorGlobalIndexerFactory.nativeOptions(
                         new VectorType(8, new FloatType()),
                         options,
-                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER);
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
 
         assertThat(nativeOptions).containsEntry("dimension", "8");
     }
@@ -107,9 +109,61 @@ public void testInvalidDimension() {
                                 VectorGlobalIndexerFactory.nativeOptions(
                                         new ArrayType(new FloatType()),
                                         options,
-                                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER))
+                                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                                        "vec"))
                 .isInstanceOf(IllegalArgumentException.class)
                 .hasMessageContaining("ivf-flat.dimension")
                 .hasMessageContaining("positive integer");
     }
+
+    @Test
+    public void testFieldLevelOptionsOverrideIndexTypeOptions() {
+        Options options = new Options();
+        options.setString("ivf-flat.dimension", "32");
+        options.setString("ivf-flat.nlist", "128");
+        options.setString("ivf-flat.fields.vec.nlist", "256");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
+
+        assertThat(nativeOptions)
+                .containsEntry("dimension", "32")
+                .containsEntry("nlist", "256")
+                .doesNotContainEntry("nlist", "128");
+    }
+
+    @Test
+    public void testFieldLevelOptionsOnlyApplyToMatchingField() {
+        Options options = new Options();
+        options.setString("ivf-flat.nlist", "128");
+        options.setString("ivf-flat.fields.vec.nlist", "256");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "other");
+
+        assertThat(nativeOptions).containsEntry("nlist", "128");
+    }
+
+    @Test
+    public void testFieldLevelOptionsWithoutIndexTypeOption() {
+        Options options = new Options();
+        options.setString("ivf-flat.fields.vec.distance.metric", "cosine");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
+
+        assertThat(nativeOptions).containsEntry("metric", "cosine");
+    }
 }

From f2244ae37ccb10771ab7a0772807ad703e2d1cda Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 16:35:51 +0800
Subject: [PATCH 2/6] Improve vector field option docs and tests

---
 docs/docs/multimodal-table/global-index.mdx      |  5 +++--
 .../index/VectorGlobalIndexerFactoryTest.java    | 16 ++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/docs/multimodal-table/global-index.mdx b/docs/docs/multimodal-table/global-index.mdx
index 8ba1f9ec14ce..a9dcc7c43652 100644
--- a/docs/docs/multimodal-table/global-index.mdx
+++ b/docs/docs/multimodal-table/global-index.mdx
@@ -127,12 +127,13 @@ Supported vector index options:
 | `<index-type>.hnsw.ef-construction` | `150` | HNSW construction search width for `ivf-hnsw-flat` and `ivf-hnsw-sq`. |
 | `<index-type>.hnsw.max-level` | `7` | Maximum HNSW level for `ivf-hnsw-flat` and `ivf-hnsw-sq`. |
 
-**Per-Column Options**
+**Per-Field Options**
 
 The options above can also be set at the table level (in `TBLPROPERTIES`), where they are shared
 by every vector column of the same index type. When a table has multiple vector columns, you can
 scope an option to a single column with `<index-type>.fields.<field-name>.<option>`. The field-level
-form takes precedence over the column-agnostic `<index-type>.<option>` for that column:
+form takes precedence over the column-agnostic `<index-type>.<option>` for that column. Use the
+stored table column name exactly as `<field-name>`:
 
 ```sql
 CREATE TABLE my_table (
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
index b2b413cd88d5..def38a363da7 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
@@ -152,6 +152,22 @@ public void testFieldLevelOptionsOnlyApplyToMatchingField() {
         assertThat(nativeOptions).containsEntry("nlist", "128");
     }
 
+    @Test
+    public void testFieldLevelOptionsRequireExactFieldName() {
+        Options options = new Options();
+        options.setString("ivf-flat.nlist", "128");
+        options.setString("ivf-flat.fields.vec_extra.nlist", "512");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
+
+        assertThat(nativeOptions).containsEntry("nlist", "128");
+    }
+
     @Test
     public void testFieldLevelOptionsWithoutIndexTypeOption() {
         Options options = new Options();

From f7d1bd6be3d03a7de8ecd67759fc7e5f6514d883 Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 16:51:46 +0800
Subject: [PATCH 3/6] Harden vector field option parsing

---
 .../vector/index/VectorGlobalIndexerFactory.java |  5 +++--
 .../index/VectorGlobalIndexerFactoryTest.java    | 16 ++++++++++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
index 6d50f0a44246..361107a45513 100644
--- a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
+++ b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
@@ -46,13 +46,14 @@ static Map<String, String> nativeOptions(
             DataType fieldType, Options tableOptions, String identifier, String fieldName) {
         Map<String, String> nativeOptions = new LinkedHashMap<>();
         String optionPrefix = identifier + ".";
-        String fieldPrefix = optionPrefix + "fields." + fieldName + ".";
+        String fieldsPrefix = optionPrefix + "fields.";
+        String fieldPrefix = fieldsPrefix + fieldName + ".";
         Map<String, String> tableOptionsMap = tableOptions.toMap();
 
         // First collect index-type level options, e.g. <index-type>.xxx.
         for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
             String optionKey = entry.getKey();
-            if (optionKey.startsWith(optionPrefix)) {
+            if (optionKey.startsWith(optionPrefix) && !optionKey.startsWith(fieldsPrefix)) {
                 String nativeKey = nativeOptionKey(optionKey.substring(optionPrefix.length()));
                 if (nativeKey != null) {
                     nativeOptions.put(nativeKey, entry.getValue());
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
index def38a363da7..de88ed80c409 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
@@ -136,6 +136,22 @@ public void testFieldLevelOptionsOverrideIndexTypeOptions() {
                 .doesNotContainEntry("nlist", "128");
     }
 
+    @Test
+    public void testFieldLevelDimensionOverridesIndexTypeDimension() {
+        Options options = new Options();
+        options.setString("ivf-flat.dimension", "32");
+        options.setString("ivf-flat.fields.vec.dimension", "64");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
+
+        assertThat(nativeOptions).containsEntry("dimension", "64");
+    }
+
     @Test
     public void testFieldLevelOptionsOnlyApplyToMatchingField() {
         Options options = new Options();

From c2510e99ada0a4b95c54d326edd65a9289c23846 Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 18:07:22 +0800
Subject: [PATCH 4/6] Use field-scoped vector options

---
 docs/docs/multimodal-table/global-index.mdx            |  8 ++++----
 .../vector/index/VectorGlobalIndexerFactory.java       | 10 +++++-----
 .../vector/index/VectorGlobalIndexerFactoryTest.java   | 10 +++++-----
 3 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/docs/multimodal-table/global-index.mdx b/docs/docs/multimodal-table/global-index.mdx
index a9dcc7c43652..5cc7af093a89 100644
--- a/docs/docs/multimodal-table/global-index.mdx
+++ b/docs/docs/multimodal-table/global-index.mdx
@@ -131,7 +131,7 @@ Supported vector index options:
 
 The options above can also be set at the table level (in `TBLPROPERTIES`), where they are shared
 by every vector column of the same index type. When a table has multiple vector columns, you can
-scope an option to a single column with `<index-type>.fields.<field-name>.<option>`. The field-level
+scope an option to a single column with `fields.<field-name>.<option>`. The field-level
 form takes precedence over the column-agnostic `<index-type>.<option>` for that column. Use the
 stored table column name exactly as `<field-name>`:
 
@@ -146,11 +146,11 @@ CREATE TABLE my_table (
     'data-evolution.enabled' = 'true',
     'global-index.enabled' = 'true',
     -- per-column dimensions
-    'ivf-pq.fields.title_embedding.dimension' = '768',
-    'ivf-pq.fields.image_embedding.dimension' = '512',
+    'fields.title_embedding.dimension' = '768',
+    'fields.image_embedding.dimension' = '512',
     -- shared by every ivf-pq column, overridden only for 'image_embedding'
     'ivf-pq.nlist' = '256',
-    'ivf-pq.fields.image_embedding.nlist' = '512'
+    'fields.image_embedding.nlist' = '512'
 );
 ```
 
diff --git a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
index 361107a45513..8b0bd2e551a3 100644
--- a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
+++ b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
@@ -46,14 +46,14 @@ static Map<String, String> nativeOptions(
             DataType fieldType, Options tableOptions, String identifier, String fieldName) {
         Map<String, String> nativeOptions = new LinkedHashMap<>();
         String optionPrefix = identifier + ".";
-        String fieldsPrefix = optionPrefix + "fields.";
-        String fieldPrefix = fieldsPrefix + fieldName + ".";
+        String indexFieldsPrefix = optionPrefix + "fields.";
+        String fieldPrefix = "fields." + fieldName + ".";
         Map<String, String> tableOptionsMap = tableOptions.toMap();
 
         // First collect index-type level options, e.g. <index-type>.xxx.
         for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
             String optionKey = entry.getKey();
-            if (optionKey.startsWith(optionPrefix) && !optionKey.startsWith(fieldsPrefix)) {
+            if (optionKey.startsWith(optionPrefix) && !optionKey.startsWith(indexFieldsPrefix)) {
                 String nativeKey = nativeOptionKey(optionKey.substring(optionPrefix.length()));
                 if (nativeKey != null) {
                     nativeOptions.put(nativeKey, entry.getValue());
@@ -61,8 +61,8 @@ static Map<String, String> nativeOptions(
             }
         }
 
-        // Then collect field level options, e.g. <index-type>.fields.<field-name>.xxx, which take
-        // precedence over the index-type level options for this field.
+        // Then collect field level options, e.g. fields.<field-name>.xxx, which take precedence
+        // over the index-type level options for this field.
         for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
             String optionKey = entry.getKey();
             if (optionKey.startsWith(fieldPrefix)) {
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
index de88ed80c409..2a3829ca6d69 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
@@ -121,7 +121,7 @@ public void testFieldLevelOptionsOverrideIndexTypeOptions() {
         Options options = new Options();
         options.setString("ivf-flat.dimension", "32");
         options.setString("ivf-flat.nlist", "128");
-        options.setString("ivf-flat.fields.vec.nlist", "256");
+        options.setString("fields.vec.nlist", "256");
 
         Map<String, String> nativeOptions =
                 VectorGlobalIndexerFactory.nativeOptions(
@@ -140,7 +140,7 @@ public void testFieldLevelOptionsOverrideIndexTypeOptions() {
     public void testFieldLevelDimensionOverridesIndexTypeDimension() {
         Options options = new Options();
         options.setString("ivf-flat.dimension", "32");
-        options.setString("ivf-flat.fields.vec.dimension", "64");
+        options.setString("fields.vec.dimension", "64");
 
         Map<String, String> nativeOptions =
                 VectorGlobalIndexerFactory.nativeOptions(
@@ -156,7 +156,7 @@ public void testFieldLevelDimensionOverridesIndexTypeDimension() {
     public void testFieldLevelOptionsOnlyApplyToMatchingField() {
         Options options = new Options();
         options.setString("ivf-flat.nlist", "128");
-        options.setString("ivf-flat.fields.vec.nlist", "256");
+        options.setString("fields.vec.nlist", "256");
 
         Map<String, String> nativeOptions =
                 VectorGlobalIndexerFactory.nativeOptions(
@@ -172,7 +172,7 @@ public void testFieldLevelOptionsOnlyApplyToMatchingField() {
     public void testFieldLevelOptionsRequireExactFieldName() {
         Options options = new Options();
         options.setString("ivf-flat.nlist", "128");
-        options.setString("ivf-flat.fields.vec_extra.nlist", "512");
+        options.setString("fields.vec_extra.nlist", "512");
 
         Map<String, String> nativeOptions =
                 VectorGlobalIndexerFactory.nativeOptions(
@@ -187,7 +187,7 @@ public void testFieldLevelOptionsRequireExactFieldName() {
     @Test
     public void testFieldLevelOptionsWithoutIndexTypeOption() {
         Options options = new Options();
-        options.setString("ivf-flat.fields.vec.distance.metric", "cosine");
+        options.setString("fields.vec.distance.metric", "cosine");
 
         Map<String, String> nativeOptions =
                 VectorGlobalIndexerFactory.nativeOptions(

From cc308a58b6809685a7babd2b45f94094bc4e212a Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 18:39:16 +0800
Subject: [PATCH 5/6] Remove obsolete vector option guard

---
 .../apache/paimon/vector/index/VectorGlobalIndexerFactory.java | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
index 8b0bd2e551a3..936772311478 100644
--- a/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
+++ b/paimon-vector/paimon-vector-index/src/main/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactory.java
@@ -46,14 +46,13 @@ static Map<String, String> nativeOptions(
             DataType fieldType, Options tableOptions, String identifier, String fieldName) {
         Map<String, String> nativeOptions = new LinkedHashMap<>();
         String optionPrefix = identifier + ".";
-        String indexFieldsPrefix = optionPrefix + "fields.";
         String fieldPrefix = "fields." + fieldName + ".";
         Map<String, String> tableOptionsMap = tableOptions.toMap();
 
         // First collect index-type level options, e.g. <index-type>.xxx.
         for (Map.Entry<String, String> entry : tableOptionsMap.entrySet()) {
             String optionKey = entry.getKey();
-            if (optionKey.startsWith(optionPrefix) && !optionKey.startsWith(indexFieldsPrefix)) {
+            if (optionKey.startsWith(optionPrefix)) {
                 String nativeKey = nativeOptionKey(optionKey.substring(optionPrefix.length()));
                 if (nativeKey != null) {
                     nativeOptions.put(nativeKey, entry.getValue());

From a8e78c05ed1381f967da7cb79f9b0a1800230361 Mon Sep 17 00:00:00 2001
From: yantian <lining.jln@alibaba-inc.com>
Date: Mon, 15 Jun 2026 18:40:51 +0800
Subject: [PATCH 6/6] Clarify field-scoped vector options

---
 docs/docs/multimodal-table/global-index.mdx   |  4 +++-
 .../index/VectorGlobalIndexerFactoryTest.java | 19 +++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/docs/docs/multimodal-table/global-index.mdx b/docs/docs/multimodal-table/global-index.mdx
index 5cc7af093a89..a7698f124a29 100644
--- a/docs/docs/multimodal-table/global-index.mdx
+++ b/docs/docs/multimodal-table/global-index.mdx
@@ -133,7 +133,9 @@ The options above can also be set at the table level (in `TBLPROPERTIES`), where
 by every vector column of the same index type. When a table has multiple vector columns, you can
 scope an option to a single column with `fields.<field-name>.<option>`. The field-level
 form takes precedence over the column-agnostic `<index-type>.<option>` for that column. Use the
-stored table column name exactly as `<field-name>`:
+stored table column name exactly as `<field-name>`. Field-level vector options do not include the
+index-type prefix; for example, use `fields.image_embedding.nlist` to override the shared
+`ivf-pq.nlist` option for `image_embedding`:
 
 ```sql
 CREATE TABLE my_table (
diff --git a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
index 2a3829ca6d69..b0f33d770621 100644
--- a/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
+++ b/paimon-vector/paimon-vector-index/src/test/java/org/apache/paimon/vector/index/VectorGlobalIndexerFactoryTest.java
@@ -198,4 +198,23 @@ public void testFieldLevelOptionsWithoutIndexTypeOption() {
 
         assertThat(nativeOptions).containsEntry("metric", "cosine");
     }
+
+    @Test
+    public void testFieldLevelVectorOptionsCoexistWithCoreFieldOptions() {
+        Options options = new Options();
+        options.setString("ivf-flat.nlist", "128");
+        options.setString("fields.vec.nlist", "256");
+        options.setString("fields.vec.aggregate-function", "sum");
+
+        Map<String, String> nativeOptions =
+                VectorGlobalIndexerFactory.nativeOptions(
+                        new ArrayType(new FloatType()),
+                        options,
+                        IvfFlatVectorGlobalIndexerFactory.IDENTIFIER,
+                        "vec");
+
+        assertThat(nativeOptions)
+                .containsEntry("nlist", "256")
+                .doesNotContainKey("aggregate-function");
+    }
 }