You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hbase.apache.org by "shubham-roy (via GitHub)" <gi...@apache.org> on 2026/07/10 08:55:18 UTC
[PR] HBASE-29974: Persist filter hints across scan circuit breaks [hbase]
shubham-roy opened a new pull request, #8464:
URL: https://github.com/apache/hbase/pull/8464
Backport of HBASE-29974 to branch-2.5 (cherry-picked from master 21d3fdfbca6, PR #7882). Adapted for branch-2.5: ExtendedCell → Cell (branch-2.5 predates the ExtendedCell migration), and the nextRowViaHint fast path drops the ScannerContext.setSkippingRow calls (that API — HBASE-27558 — is not on branch-2.5). Tests unchanged (JUnit 5, delete-marker tests retained since HBASE-29039 is present); HBaseTestingUtil → HBaseTestingUtility for the pre-rename branch. No-op by default.
Generated-by: Claude Opus 4.6 (1M context) <no...@anthropic.com>
(cherry picked from commit 21d3fdfbca653e8effb32a4ccb44ca2ba5f5d1e1)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hbase.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] HBASE-29974: Persist filter hints across scan circuit breaks [hbase]
Posted by "virajjasani (via GitHub)" <gi...@apache.org>.
virajjasani commented on code in PR #8464:
URL: https://github.com/apache/hbase/pull/8464#discussion_r3615964098
##########
hbase-client/src/main/java/org/apache/hadoop/hbase/filter/Filter.java:
##########
@@ -219,6 +223,85 @@ public enum ReturnCode {
*/
abstract public Cell getNextCellHint(final Cell currentCell) throws IOException;
+ /**
+ * Provides a seek hint to bypass row-by-row scanning after {@link #filterRowKey(Cell)} rejects a
+ * row. When {@code filterRowKey} returns {@code true} the scan pipeline would normally iterate
+ * through every remaining cell in the rejected row one-by-one (via {@code nextRow()}) before
+ * moving on. If the filter can determine a better forward position — for example, the next range
+ * boundary in a {@code MultiRowRangeFilter} — it should return that target cell here, allowing
+ * the scanner to seek directly past the unwanted rows.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>Only called after {@link #filterRowKey(Cell)} has returned {@code true} for the same
+ * {@code firstRowCell}.</li>
+ * <li>Implementations may use state that was set during {@link #filterRowKey(Cell)} (e.g. an
+ * updated range pointer), but <strong>must not</strong> invoke {@link #filterCell(Cell)} logic —
+ * the caller guarantees that {@code filterCell} has not been called for this row.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
+ * side.</li>
+ * <li>Returning {@code null} (the default) falls through to the existing {@code nextRow()}
+ * behaviour, preserving full backward compatibility.</li>
+ * <li>For reversed scans ({@link org.apache.hadoop.hbase.client.Scan#isReversed()}), the hint
+ * must point to a <em>smaller</em> row key (earlier in reverse-scan direction). The scanner
+ * validates hint direction and falls back to {@code nextRow()} if the hint does not advance in
+ * the scan direction.</li>
+ * <li><strong>Composite filter limitation:</strong> {@code FilterList}, {@code SkipFilter}, and
+ * {@code WhileMatchFilter} do not currently delegate this method to wrapped sub-filters. Hints
+ * from filters used inside these wrappers will be silently ignored.</li>
+ * </ul>
+ * @param firstRowCell the first cell encountered in the rejected row; contains the row key that
+ * was passed to {@code filterRowKey}
+ * @return a {@link Cell} representing the earliest position the scanner should seek to, or
+ * {@code null} if this filter cannot provide a better position than a sequential skip
+ * @throws IOException in case an I/O or filter-specific failure needs to be signaled
+ * @see #filterRowKey(Cell)
+ */
+ public Cell getHintForRejectedRow(final Cell firstRowCell) throws IOException {
+ return null;
+ }
+
+ /**
+ * Provides a seek hint for cells that are structurally skipped by the scan pipeline
+ * <em>before</em> {@link #filterCell(Cell)} is ever reached. The pipeline short-circuits on
+ * several criteria — time-range mismatch, column-set exclusion, and version-limit exhaustion —
+ * and in each case the filter is bypassed entirely. When an implementation can compute a
+ * meaningful forward position purely from the cell's coordinates (without needing the
+ * {@code filterCell} call sequence), it should return that position here so the scanner can seek
+ * ahead instead of advancing one cell at a time.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>May be called for cells that have <strong>never</strong> been passed to
+ * {@link #filterCell(Cell)}.</li>
+ * <li>Implementations <strong>must not</strong> modify any filter state; this method is treated
+ * as logically stateless. Only filters whose hint computation is based solely on immutable
+ * configuration (e.g. a fixed column range or a fuzzy-row pattern) should override this.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
Review Comment:
I think it's fine to keep for backport PR if master and branch-2 already has this comment. We can update them all later as addendum PR if needed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hbase.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] HBASE-29974: Persist filter hints across scan circuit breaks [hbase]
Posted by "Umeshkumar9414 (via GitHub)" <gi...@apache.org>.
Umeshkumar9414 commented on code in PR #8464:
URL: https://github.com/apache/hbase/pull/8464#discussion_r3612821894
##########
hbase-client/src/main/java/org/apache/hadoop/hbase/filter/Filter.java:
##########
@@ -219,6 +223,85 @@ public enum ReturnCode {
*/
abstract public Cell getNextCellHint(final Cell currentCell) throws IOException;
+ /**
+ * Provides a seek hint to bypass row-by-row scanning after {@link #filterRowKey(Cell)} rejects a
+ * row. When {@code filterRowKey} returns {@code true} the scan pipeline would normally iterate
+ * through every remaining cell in the rejected row one-by-one (via {@code nextRow()}) before
+ * moving on. If the filter can determine a better forward position — for example, the next range
+ * boundary in a {@code MultiRowRangeFilter} — it should return that target cell here, allowing
+ * the scanner to seek directly past the unwanted rows.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>Only called after {@link #filterRowKey(Cell)} has returned {@code true} for the same
+ * {@code firstRowCell}.</li>
+ * <li>Implementations may use state that was set during {@link #filterRowKey(Cell)} (e.g. an
+ * updated range pointer), but <strong>must not</strong> invoke {@link #filterCell(Cell)} logic —
+ * the caller guarantees that {@code filterCell} has not been called for this row.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
+ * side.</li>
+ * <li>Returning {@code null} (the default) falls through to the existing {@code nextRow()}
+ * behaviour, preserving full backward compatibility.</li>
+ * <li>For reversed scans ({@link org.apache.hadoop.hbase.client.Scan#isReversed()}), the hint
+ * must point to a <em>smaller</em> row key (earlier in reverse-scan direction). The scanner
+ * validates hint direction and falls back to {@code nextRow()} if the hint does not advance in
+ * the scan direction.</li>
+ * <li><strong>Composite filter limitation:</strong> {@code FilterList}, {@code SkipFilter}, and
+ * {@code WhileMatchFilter} do not currently delegate this method to wrapped sub-filters. Hints
+ * from filters used inside these wrappers will be silently ignored.</li>
+ * </ul>
+ * @param firstRowCell the first cell encountered in the rejected row; contains the row key that
+ * was passed to {@code filterRowKey}
+ * @return a {@link Cell} representing the earliest position the scanner should seek to, or
+ * {@code null} if this filter cannot provide a better position than a sequential skip
+ * @throws IOException in case an I/O or filter-specific failure needs to be signaled
+ * @see #filterRowKey(Cell)
+ */
+ public Cell getHintForRejectedRow(final Cell firstRowCell) throws IOException {
+ return null;
+ }
+
+ /**
+ * Provides a seek hint for cells that are structurally skipped by the scan pipeline
+ * <em>before</em> {@link #filterCell(Cell)} is ever reached. The pipeline short-circuits on
+ * several criteria — time-range mismatch, column-set exclusion, and version-limit exhaustion —
+ * and in each case the filter is bypassed entirely. When an implementation can compute a
+ * meaningful forward position purely from the cell's coordinates (without needing the
+ * {@code filterCell} call sequence), it should return that position here so the scanner can seek
+ * ahead instead of advancing one cell at a time.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>May be called for cells that have <strong>never</strong> been passed to
+ * {@link #filterCell(Cell)}.</li>
+ * <li>Implementations <strong>must not</strong> modify any filter state; this method is treated
+ * as logically stateless. Only filters whose hint computation is based solely on immutable
+ * configuration (e.g. a fixed column range or a fuzzy-row pattern) should override this.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
Review Comment:
does this comment still apply ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hbase.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] HBASE-29974: Persist filter hints across scan circuit breaks [hbase]
Posted by "virajjasani (via GitHub)" <gi...@apache.org>.
virajjasani merged PR #8464:
URL: https://github.com/apache/hbase/pull/8464
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hbase.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] HBASE-29974: Persist filter hints across scan circuit breaks [hbase]
Posted by "Umeshkumar9414 (via GitHub)" <gi...@apache.org>.
Umeshkumar9414 commented on code in PR #8464:
URL: https://github.com/apache/hbase/pull/8464#discussion_r3612821894
##########
hbase-client/src/main/java/org/apache/hadoop/hbase/filter/Filter.java:
##########
@@ -219,6 +223,85 @@ public enum ReturnCode {
*/
abstract public Cell getNextCellHint(final Cell currentCell) throws IOException;
+ /**
+ * Provides a seek hint to bypass row-by-row scanning after {@link #filterRowKey(Cell)} rejects a
+ * row. When {@code filterRowKey} returns {@code true} the scan pipeline would normally iterate
+ * through every remaining cell in the rejected row one-by-one (via {@code nextRow()}) before
+ * moving on. If the filter can determine a better forward position — for example, the next range
+ * boundary in a {@code MultiRowRangeFilter} — it should return that target cell here, allowing
+ * the scanner to seek directly past the unwanted rows.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>Only called after {@link #filterRowKey(Cell)} has returned {@code true} for the same
+ * {@code firstRowCell}.</li>
+ * <li>Implementations may use state that was set during {@link #filterRowKey(Cell)} (e.g. an
+ * updated range pointer), but <strong>must not</strong> invoke {@link #filterCell(Cell)} logic —
+ * the caller guarantees that {@code filterCell} has not been called for this row.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
+ * side.</li>
+ * <li>Returning {@code null} (the default) falls through to the existing {@code nextRow()}
+ * behaviour, preserving full backward compatibility.</li>
+ * <li>For reversed scans ({@link org.apache.hadoop.hbase.client.Scan#isReversed()}), the hint
+ * must point to a <em>smaller</em> row key (earlier in reverse-scan direction). The scanner
+ * validates hint direction and falls back to {@code nextRow()} if the hint does not advance in
+ * the scan direction.</li>
+ * <li><strong>Composite filter limitation:</strong> {@code FilterList}, {@code SkipFilter}, and
+ * {@code WhileMatchFilter} do not currently delegate this method to wrapped sub-filters. Hints
+ * from filters used inside these wrappers will be silently ignored.</li>
+ * </ul>
+ * @param firstRowCell the first cell encountered in the rejected row; contains the row key that
+ * was passed to {@code filterRowKey}
+ * @return a {@link Cell} representing the earliest position the scanner should seek to, or
+ * {@code null} if this filter cannot provide a better position than a sequential skip
+ * @throws IOException in case an I/O or filter-specific failure needs to be signaled
+ * @see #filterRowKey(Cell)
+ */
+ public Cell getHintForRejectedRow(final Cell firstRowCell) throws IOException {
+ return null;
+ }
+
+ /**
+ * Provides a seek hint for cells that are structurally skipped by the scan pipeline
+ * <em>before</em> {@link #filterCell(Cell)} is ever reached. The pipeline short-circuits on
+ * several criteria — time-range mismatch, column-set exclusion, and version-limit exhaustion —
+ * and in each case the filter is bypassed entirely. When an implementation can compute a
+ * meaningful forward position purely from the cell's coordinates (without needing the
+ * {@code filterCell} call sequence), it should return that position here so the scanner can seek
+ * ahead instead of advancing one cell at a time.
+ * <p>
+ * Contract:
+ * <ul>
+ * <li>May be called for cells that have <strong>never</strong> been passed to
+ * {@link #filterCell(Cell)}.</li>
+ * <li>Implementations <strong>must not</strong> modify any filter state; this method is treated
+ * as logically stateless. Only filters whose hint computation is based solely on immutable
+ * configuration (e.g. a fixed column range or a fuzzy-row pattern) should override this.</li>
+ * <li>The returned {@link Cell}, if non-null, must be an
+ * {@link org.apache.hadoop.hbase.ExtendedCell} because filters are evaluated on the server
Review Comment:
does this comment related to ExtendedCell still apply ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hbase.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org