feat: add incremental read context and scan boundaries

[discord9]

I hereby agree to the terms of the GreptimeDB CLA.

Refer to a related PR or issue link (optional)

What's changed and what's your intention?

Add the foundational query context and scan request fields for
sequence-based incremental reads.

This wires flow incremental extensions, snapshot sequence transport,
and scan boundary fields without bringing in Flow state-machine or
rewrite POC logic yet.

PR Checklist

Please convert it to a draft if some of the following conditions are not met.

• I have written the necessary rustdoc comments.
• I have added the necessary unit tests and integration tests.
• This PR requires documentation updates.
• API changes are backward compatible.
• Schema or data changes are backward compatible.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational components for implementing sequence-based incremental reads within the system. It modifies core data structures like QueryContext and ScanRequest to carry and process information about data sequences and scan boundaries. The changes enable the system to prepare for more granular control over data retrieval, facilitating future development of incremental data processing flows by providing the necessary context and configuration mechanisms.

Highlights

• Enhanced Query Contexts: The QueryContext and FlowQueryContext structs have been extended to include snapshot_seqs and sst_min_sequences for tracking sequence boundaries, crucial for incremental reads.
• Incremental Read Configuration: New types FlowIncrementalMode and FlowQueryExtensions were introduced to manage and validate flow-related incremental read parameters via query context extensions.
• Scan Request Updates: The ScanRequest now includes a snapshot_on_scan flag, allowing explicit control over when snapshot upper bounds are applied during data scans.
• Scanner Interface Extension: The RegionScanner trait and its SinglePartitionScanner implementation were updated to support an optional snapshot_sequence, enabling scanners to report their effective snapshot point.
• Error Handling for Extensions: A new error variant, InvalidQueryContextExtension, was added to handle malformed or invalid query context extension parameters.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively lays the groundwork for sequence-based incremental reads by introducing necessary fields to the query context and scan requests. The changes are well-structured, propagating the new context through different layers of the system, and include comprehensive tests for the new parsing logic. My feedback focuses on improving documentation for public data structures and refining some data conversion implementations for better conciseness and robustness.

[WenyXu]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".