[core] Update row-count defaults and rename global index file option

docs/docs/multimodal-table/global-index/manage-indexes.mdx

@@ -453,7 +453,7 @@ These table options affect global index build and read behavior:
 | `global-index.column-update-action` | `THROW_ERROR` | Update policy: `THROW_ERROR`, `DROP_PARTITION_INDEX`, or `IGNORE`. See [Update Indexed Columns](#update-indexed-columns) for refresh requirements and engine differences. |
 | `sorted-index.records-per-range` | `10000000` | Expected number of records per sorted global index file for BTree, Bitmap, and Multivalue builds. |
 | `sorted-index.build.max-parallelism` | `4096` | Maximum Flink or Spark parallelism for building sorted global indexes. |
-| `global-index.row-count-per-shard` | `100000` | Target row count per shard for non-sorted global index builds such as vector and full-text indexes. |
+| `global-index.row-count-per-file` | `25000000` | Target row count per file for non-sorted global index builds such as vector and full-text indexes. Falls back to `global-index.row-count-per-shard` when the new key is not set. |
 | `global-index.build.parallelism` | `1` | Number of shards built concurrently by the local PyPaimon builder. Each shard may use native worker threads, so increase this value conservatively. |
 | `global-index.build.max-shard` | `32` | Preferred maximum shard count for global index builds. |
 | `global-index.build.max-parallelism` | `4096` | Maximum Flink or Spark parallelism for building non-sorted global indexes. |

docs/docs/multimodal-table/global-index/vector.mdx

@@ -120,7 +120,7 @@ added_files = table.create_global_index(
         "ivf-flat.dimension": "3",
         "ivf-flat.distance.metric": "cosine",
         "ivf-flat.nlist": "1",
-        "global-index.row-count-per-shard": "100000",
+        "global-index.row-count-per-file": "100000",
     },
 )
 print(added_files)

docs/generated/core_configuration.html

@@ -556,7 +556,7 @@
         </tr>
         <tr>
             <td><h5>data-evolution.reassign.skip-contiguous-row-count</h5></td>
-            <td style="word-wrap: break-word;">1000000000</td>
+            <td style="word-wrap: break-word;">20000000000</td>
             <td>Long</td>
             <td>Strictly contiguous same-partition logical row-id runs containing more than this number of rows are excluded from row-id reassignment. Set to 0 to disable this filtering.</td>
         </tr>
@@ -852,7 +852,7 @@
             <td><h5>global-index.build.max-shard</h5></td>
             <td style="word-wrap: break-word;">32</td>
             <td>Integer</td>
-            <td>The preferred max number of shards for building global index. If the number of shards calculated by 'global-index.row-count-per-shard' exceeds this value, max-shard will be automatically increased to accommodate the data volume while keeping 'global-index.row-count-per-shard' unchanged.</td>
+            <td>The preferred max number of shards for building global index. If the number of shards calculated by 'global-index.row-count-per-file' exceeds this value, max-shard will be automatically increased to accommodate the data volume while keeping 'global-index.row-count-per-file' unchanged.</td>
         </tr>
         <tr>
             <td><h5>global-index.column-update-action</h5></td>
@@ -879,10 +879,10 @@
             <td>Whether a vector, hybrid or full-text search may read the filter columns of candidate rows to verify a row filter that the scalar global index can only answer with a superset, such as contains, ends-with or like on a BTree index or a conjunction with a member no index can evaluate. When false, such candidates are excluded from the search, which never returns a non-matching row but may return fewer than the requested top-k. When true, the read runs on the caller and may cover every candidate row.</td>
         </tr>
         <tr>
-            <td><h5>global-index.row-count-per-shard</h5></td>
-            <td style="word-wrap: break-word;">100000</td>
+            <td><h5>global-index.row-count-per-file</h5></td>
+            <td style="word-wrap: break-word;">25000000</td>
             <td>Long</td>
-            <td>Row count per shard for global index.</td>
+            <td>Row count per file for global index.</td>
         </tr>
         <tr>
             <td><h5>global-index.search-mode</h5></td>

paimon-api/src/main/java/org/apache/paimon/CoreOptions.java

@@ -2618,7 +2618,7 @@ public String toString() {
     public static final ConfigOption<Long> DATA_EVOLUTION_REASSIGN_SKIP_CONTIGUOUS_ROW_COUNT =
             key("data-evolution.reassign.skip-contiguous-row-count")
                     .longType()
-                    .defaultValue(1_000_000_000L)
+                    .defaultValue(20_000_000_000L)
                     .withDescription(
                             "Strictly contiguous same-partition logical row-id runs containing "
                                     + "more than this number of rows are excluded from row-id "
@@ -2969,22 +2969,23 @@ public String toString() {
                             "Target postpone file size per bucket when estimating the required bucket number from staged or committed postpone files. "
                                     + "This option is ignored when 'postpone.target-row-num-per-bucket' is configured.");
 
-    public static final ConfigOption<Long> GLOBAL_INDEX_ROW_COUNT_PER_SHARD =
-            key("global-index.row-count-per-shard")
+    public static final ConfigOption<Long> GLOBAL_INDEX_ROW_COUNT_PER_FILE =
+            key("global-index.row-count-per-file")
                     .longType()
-                    .defaultValue(100000L)
-                    .withDescription("Row count per shard for global index.");
+                    .defaultValue(25_000_000L)
+                    .withFallbackKeys("global-index.row-count-per-shard")
+                    .withDescription("Row count per file for global index.");
 
     public static final ConfigOption<Integer> GLOBAL_INDEX_BUILD_MAX_SHARD =
             key("global-index.build.max-shard")
                     .intType()
                     .defaultValue(32)
                     .withDescription(
                             "The preferred max number of shards for building global index. "
-                                    + "If the number of shards calculated by 'global-index.row-count-per-shard' "
+                                    + "If the number of shards calculated by 'global-index.row-count-per-file' "
                                     + "exceeds this value, max-shard will be automatically increased "
                                     + "to accommodate the data volume while keeping "
-                                    + "'global-index.row-count-per-shard' unchanged.");
+                                    + "'global-index.row-count-per-file' unchanged.");
 
     public static final ConfigOption<Integer> GLOBAL_INDEX_BUILD_MAX_PARALLELISM =
             key("global-index.build.max-parallelism")
@@ -4813,7 +4814,7 @@ public long postponeTargetSizePerBucket() {
     }
 
     public long globalIndexRowCountPerShard() {
-        return options.get(GLOBAL_INDEX_ROW_COUNT_PER_SHARD);
+        return options.get(GLOBAL_INDEX_ROW_COUNT_PER_FILE);
     }
 
     public boolean globalIndexEnabled() {

paimon-api/src/test/java/org/apache/paimon/GlobalIndexOptionsTest.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.paimon;
+
+import org.apache.paimon.options.Options;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/** Tests for global index configuration compatibility. */
+class GlobalIndexOptionsTest {
+
+    @Test
+    void testRowCountPerFileDefault() {
+        assertThat(new CoreOptions(new Options()).globalIndexRowCountPerShard())
+                .isEqualTo(25_000_000L);
+    }
+
+    @Test
+    void testRowCountPerFileFallsBackToLegacyKey() {
+        Options options = new Options();
+        options.setString("global-index.row-count-per-shard", "100000");
+
+        assertThat(new CoreOptions(options).globalIndexRowCountPerShard()).isEqualTo(100_000L);
+    }
+
+    @Test
+    void testRowCountPerFileTakesPrecedenceOverLegacyKey() {
+        Options options = new Options();
+        options.setString("global-index.row-count-per-file", "2500");
+        CoreOptions coreOptions = new CoreOptions(options);
+        assertThat(coreOptions.globalIndexRowCountPerShard()).isEqualTo(2500L);
+
+        options.setString("global-index.row-count-per-shard", "100000");
+        assertThat(coreOptions.globalIndexRowCountPerShard()).isEqualTo(2500L);
+    }
+}

paimon-core/src/main/java/org/apache/paimon/globalindex/GlobalIndexBuilderUtils.java

@@ -413,7 +413,7 @@ public static List<IndexedSplit> createShardIndexedSplits(
             @Nullable List<Range> rowRangesToBuild) {
         checkArgument(
                 rowsPerShard > 0,
-                "Option 'global-index.row-count-per-shard' must be greater than 0.");
+                "Option 'global-index.row-count-per-file' must be greater than 0.");
         if (rowRangesToBuild != null) {
             rowRangesToBuild = Range.sortAndMergeOverlap(rowRangesToBuild, true);
             if (rowRangesToBuild.isEmpty()) {

paimon-flink/paimon-flink-common/src/main/java/org/apache/paimon/flink/globalindex/GenericIndexTopoBuilder.java

@@ -231,10 +231,10 @@ private static boolean buildTopology(
         byte[] sourceMeta =
                 new DataEvolutionIndexSourceMeta(scanResult.scanSnapshotId()).serialize();
 
-        long rowsPerShard = mergedOptions.get(CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_SHARD);
+        long rowsPerShard = mergedOptions.get(CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_FILE);
         checkArgument(
                 rowsPerShard > 0,
-                "Option 'global-index.row-count-per-shard' must be greater than 0.");
+                "Option 'global-index.row-count-per-file' must be greater than 0.");
 
         List<IndexManifestEntry> deletedIndexEntries = scanResult.deletedIndexEntries();
         List<Range> rowRangesToBuild = scanResult.rowRangeIndex().ranges();

paimon-python/pypaimon/common/options/core_options.py

@@ -975,11 +975,11 @@ class CoreOptions:
         )
     )
 
-    GLOBAL_INDEX_ROW_COUNT_PER_SHARD: ConfigOption[int] = (
-        ConfigOptions.key("global-index.row-count-per-shard")
+    GLOBAL_INDEX_ROW_COUNT_PER_FILE: ConfigOption[int] = (
+        ConfigOptions.key("global-index.row-count-per-file")
         .long_type()
-        .default_value(100000)
-        .with_description("Row count per shard for global index.")
+        .default_value(25_000_000)
+        .with_description("Row count per file for global index.")
     )
 
     GLOBAL_INDEX_BUILD_PARALLELISM: ConfigOption[int] = (
@@ -1755,7 +1755,13 @@ def global_index_filter_refine_from_data(self) -> bool:
         return self.options.get(CoreOptions.GLOBAL_INDEX_FILTER_REFINE_FROM_DATA)
 
     def global_index_row_count_per_shard(self) -> int:
-        return self.options.get(CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_SHARD)
+        option = CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_FILE
+        if self.options.contains(option):
+            return self.options.get(option)
+        legacy_value = self.options.to_map().get("global-index.row-count-per-shard")
+        if legacy_value is not None:
+            return OptionsUtils.convert_to_long(legacy_value)
+        return option.default_value()
 
     def global_index_build_parallelism(self) -> int:
         return self.options.get(CoreOptions.GLOBAL_INDEX_BUILD_PARALLELISM)

paimon-python/pypaimon/globalindex/build_plan.py

@@ -167,7 +167,7 @@ def split_by_global_index_shard(
 ):
     if rows_per_shard <= 0:
         raise ValueError(
-            "Option 'global-index.row-count-per-shard' must be greater than 0."
+            "Option 'global-index.row-count-per-file' must be greater than 0."
         )
     if row_ranges_to_build is not None:
         row_ranges_to_build = Range.sort_and_merge_overlap(

paimon-python/pypaimon/globalindex/create_global_index.py

@@ -295,7 +295,7 @@ def _build_generic_index(
         rows_per_shard = self._core_options.global_index_row_count_per_shard()
         if rows_per_shard <= 0:
             raise ValueError(
-                "Option 'global-index.row-count-per-shard' must be greater than 0."
+                "Option 'global-index.row-count-per-file' must be greater than 0."
             )
 
         parallelism = self._core_options.global_index_build_parallelism()

paimon-python/pypaimon/tests/global_index_options_test.py

@@ -0,0 +1,31 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+import pytest
+
+from pypaimon.common.options.core_options import CoreOptions
+
+
+@pytest.mark.parametrize("options, expected", [
+    ({}, 25_000_000),
+    ({"global-index.row-count-per-file": "2500"}, 2500),
+    ({"global-index.row-count-per-shard": "100000"}, 100_000),
+    ({"global-index.row-count-per-file": "2500",
+      "global-index.row-count-per-shard": "100000"}, 2500),
+])
+def test_row_count_per_file_default_and_fallback(options, expected):
+    assert CoreOptions.from_dict(options).global_index_row_count_per_shard() == expected

paimon-spark/paimon-spark-common/src/main/java/org/apache/paimon/spark/globalindex/DefaultGlobalIndexTopoBuilder.java

@@ -61,7 +61,7 @@
 
 import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_BUILD_MAX_PARALLELISM;
 import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_COLUMN_UPDATE_ACTION;
-import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_SHARD;
+import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_FILE;
 import static org.apache.paimon.CoreOptions.GlobalIndexColumnUpdateAction.IGNORE;
 import static org.apache.paimon.utils.Preconditions.checkArgument;
 
@@ -196,10 +196,10 @@ public List<CommitMessage> buildIndex(
     }
 
     static long rowsPerShard(Options options) {
-        long rowsPerShard = options.get(GLOBAL_INDEX_ROW_COUNT_PER_SHARD);
+        long rowsPerShard = options.get(GLOBAL_INDEX_ROW_COUNT_PER_FILE);
         checkArgument(
                 rowsPerShard > 0,
-                "Option 'global-index.row-count-per-shard' must be greater than 0.");
+                "Option 'global-index.row-count-per-file' must be greater than 0.");
         return rowsPerShard;
     }
 

paimon-spark/paimon-spark-common/src/test/java/org/apache/paimon/spark/globalindex/DefaultGlobalIndexTopoBuilderTest.java

@@ -28,7 +28,7 @@
 import java.util.Map;
 
 import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_BUILD_MAX_PARALLELISM;
-import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_SHARD;
+import static org.apache.paimon.CoreOptions.GLOBAL_INDEX_ROW_COUNT_PER_FILE;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
@@ -50,9 +50,9 @@ void testFMIndexUsesDefaultTopologyBuilder() {
     @Test
     void testRowsPerShardUsesMergedBuildOptions() {
         Map<String, String> tableOptions = new HashMap<>();
-        tableOptions.put(GLOBAL_INDEX_ROW_COUNT_PER_SHARD.key(), "1000");
+        tableOptions.put(GLOBAL_INDEX_ROW_COUNT_PER_FILE.key(), "1000");
         Map<String, String> buildOptions = new HashMap<>();
-        buildOptions.put(GLOBAL_INDEX_ROW_COUNT_PER_SHARD.key(), "25");
+        buildOptions.put(GLOBAL_INDEX_ROW_COUNT_PER_FILE.key(), "25");
 
         assertThat(
                         DefaultGlobalIndexTopoBuilder.rowsPerShard(
@@ -73,12 +73,12 @@ void testParallelismUsesBuildMaxParallelism() {
     @Test
     void testRowsPerShardMustBePositive() {
         Options options =
-                new Options(Collections.singletonMap(GLOBAL_INDEX_ROW_COUNT_PER_SHARD.key(), "0"));
+                new Options(Collections.singletonMap(GLOBAL_INDEX_ROW_COUNT_PER_FILE.key(), "0"));
 
         assertThatThrownBy(() -> DefaultGlobalIndexTopoBuilder.rowsPerShard(options))
                 .isInstanceOf(IllegalArgumentException.class)
                 .hasMessageContaining(
-                        "Option 'global-index.row-count-per-shard' must be greater than 0.");
+                        "Option 'global-index.row-count-per-file' must be greater than 0.");
     }
 
     @Test