(pulsar) 06/14: [improve][meta] Correct the MetadataStore.scanByIndex javadoc on the fallback filter and bounds (#26886)

[lh...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

lhotari pushed a commit to branch branch-5.0
in repository https://gitbox.apache.org/repos/asf/pulsar.git

commit 5853a1528e013ce7b34913157331aea5c30713de
Author: Matteo Merli <mm...@apache.org>
AuthorDate: Tue Oct 13 13:38:18 2026 -0700

    [improve][meta] Correct the MetadataStore.scanByIndex javadoc on the fallback filter and bounds (#26886)
    
    (cherry picked from commit f01315e10b1233f2cabbae0a2f9a5d0d572ec45f)
---
 .../java/org/apache/pulsar/metadata/api/MetadataStore.java  | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java b/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java
index 00c8e205e0e0..da90e030a216 100644
--- a/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java
+++ b/pulsar-metadata/src/main/java/org/apache/pulsar/metadata/api/MetadataStore.java
@@ -348,9 +348,13 @@ public interface MetadataStore extends AutoCloseable {
      * </ul>
      *
      * <p>On stores that support secondary indexes natively (e.g. Oxia), this is a single store-side
-     * range scan over the index. On stores that don't (e.g. ZooKeeper), it falls back to listing
-     * all children under {@code scanPathPrefix}, fetching each record, and applying
-     * {@code fallbackFilter}; the fallback also enforces the {@code [fromKey, toKey]} bounds.
+     * range scan over the index: the index range decides which records are returned, and
+     * {@code fallbackFilter} is not applied, so callers that need every returned record to pass it
+     * should re-check it on the results. On stores that don't (e.g. ZooKeeper), it falls back to
+     * listing all children under {@code scanPathPrefix}, fetching each record, and returning those
+     * that pass {@code fallbackFilter}. The fallback ignores {@code indexName}, {@code fromKeyInclusive}
+     * and {@code toKeyInclusive}, so {@code fallbackFilter} is its only criterion: it must itself reject
+     * the records whose {@code indexName} key is missing or outside the bounds.
      *
      * <p>Results are streamed to {@code consumer} as they become available — {@link ScanConsumer#onNext}
      * once per match, then exactly one of {@link ScanConsumer#onCompleted} or
@@ -361,7 +365,8 @@ public interface MetadataStore extends AutoCloseable {
      * @param indexName         the secondary-index name
      * @param fromKeyInclusive  lower bound on the secondary-key value, or {@code null} for unbounded
      * @param toKeyInclusive    upper bound on the secondary-key value, or {@code null} for unbounded
-     * @param fallbackFilter    additional predicate applied during fallback scan; ignored by native implementations
+     * @param fallbackFilter    the only criterion of the fallback scan, so it must match the index key and
+     *                          enforce the bounds itself; not applied by native implementations
      * @param consumer          callback receiving records, completion, or an error
      * @param opts              the set of {@link Option options} for this operation
      * @return a future that completes when the scan terminates