yihua commented on code in PR #18276:
URL: https://github.com/apache/hudi/pull/18276#discussion_r3040232447
##########
rfc/rfc-98/rfc-98.md:
##########
@@ -52,25 +49,293 @@ The current implementation of Spark Datasource V2
integration is presented in th
## Implementation
-<!-- -->
+Hudi's write path is mature, and involves indexing, precombining,
upsert/insert routing, file sizing, and table services
(compaction/clustering/cleaning).
+Also `HoodieSparkSqlWriter::write` handles schema evolution, partition
encoding, metadata updates, and multi-writer concurrency.
+DSv2's `WriteBuilder` >> `BatchWrite` >> DataWriter API is too simplistic for
this, and moving to this entirely would be a non-starter. Also, due to the
flexibility of the V1 API in terms of allowing the writes to shuffle data after
the `df.write.format....save` is invoked, Hudi supports a streaming DF write
for its upsert operation. A good majority of Hudi jobs work this way today, and
we cannot break all of these at once
+
+The proposed approach is hybrid: DSv2 for reads, with a DSv1 fallback for
writes (`V2TableWithV1Fallback`) in the current state.
+Later, if a DSv2 write path can be implemented without loss of performance or
functionality, it may become possible to move to full DSv2 support.
+However, this migration should still be incremental, please check the "Future
Work" chapter for details.
+
+Overall proposed architecture for the hybrid approach is shown in the
following schema:
+
+
+
+### DataFrame API
+
+A new SPI short name, `"hudi_v2"`, activates the DSv2 read path when using the
Spark DataFrame API.
+The existing `"hudi"` path remains unchanged.
+This is done to unblock incremental development of the DSv2 path and will be
removed in the long term, please check the "Future Work" chapter for details.
+It also allows switching later from the current DSv1 fallback to a DSv2 write
path, if an implementation without performance degradation is found.
+The DSv2 write path is currently under research.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+df.write.format("hudi").mode(...).save(path)
+ v
+BaseDefaultSource (V1) -> DefaultSource
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+<td>
+<pre>
+df.write.format("hudi_v2").mode(...).save(path)
+ v
+HoodieDataSourceV2 (TableProvider + DataSourceRegister +
CreatableRelationProvider)
+ v
+Spark treats as V1 source for writes
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+spark.read.format("hudi").load(path)
+ v
+V1 DataSource resolution (via ServiceLoader + DataSourceRegister)
+ v
+BaseDefaultSource found
+(extends DefaultSource with DataSourceRegister)
+(not a TableProvider)
+ v
+Spark treats as V1 DataSource
+ v
+DefaultSource.createRelation(...)
+ v
+MergeOnReadSnapshotRelation / BaseRelation
+ v
+LogicalRelation -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+spark.read.format("hudi_v2").load(path)
+ v
+DataSourceV2Utils.lookupProvider("hudi_v2")
+ v
+HoodieDataSourceV2 found
+(extends TableProvider with DataSourceRegister)
+(does not extend SupportsCatalogOptions)
+ v
+Spark uses TableProvider.getTable() directly
+(no catalog routing since no SupportsCatalogOptions)
+ v
+HoodieDataSourceV2.getTable(...)
+ v
+HoodieSparkV2Table(...)
+(no catalogTable, no tableIdentifier)
+ v
+HoodieScanBuilder -> HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
+
+### SQL Queries
+
+Spark SQL API is managed by new configuration parameter
`hoodie.datasource.read.use.v2`, which controls the returned table type.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = false, schemaEvol = false
+ v
+RETURNS: V1Table(catalogTable) via v1TableWrapper
+ v
+Spark V1 write path -> InsertIntoHoodieTableCommand (analysis rule)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsWrite.newWriteBuilder() -> HoodieV1WriteBuilder
+ v
+V1Write -> InsertableRelation.insert(data, overwrite)
+ v
+Align columns (rename + cast to table's user schema)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = false, schemaEvolutionEnabled = false (defaults)
+ v
+RETURNS: HoodieInternalV2Table(...).v1TableWrapper = V1Table(catalogTable)
+ v
+Spark uses V1 fallback -> DefaultSource.createRelation()
+ v
+HoodieFileIndex -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = conf("hoodie.datasource.read.use.v2") = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsRead.newScanBuilder() -> HoodieScanBuilder
+ v
+HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
### Read
-<!-- main part -->
+All new classes go into package `org.apache.spark.sql.hudi.v2` inside
`hudi-spark-common`.
+
+| Class | Spark Interface
| Responsibility
|
+|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `HoodieDataSourceV2` | `TableProvider`, `DataSourceRegister`,
`CreatableRelationProvider`
| SPI entry point for `format("hudi_v2")`.
`CreatableRelationProvider` enables DataFrame API writes via
`df.write.format("hudi_v2")`.
|
+| `HoodieSparkV2Table` | `Table`, `SupportsRead`, `SupportsWrite`,
`V2TableWithV1Fallback`
| Routes reads to DSv2, writes to DSv1 fallback via
`HoodieV1WriteBuilder`.
|
+| `HoodieScanBuilder` | `ScanBuilder`, `SupportsPushDownFilters`,
`SupportsPushDownRequiredColumns`, `PartialLimitPushDown`,
`SupportsPushDownAggregates` | Collects filter, column pruning, limit, and
aggregate pushdowns.
|
+| `HoodieBatchScan` | `Scan`, `Batch`
| Plans input partitions using existing `HoodieFileIndex`.
|
Review Comment:
_⚠️ Potential issue_ | _🟡 Minor_
<details>
<summary>🧩 Analysis chain</summary>
🌐 Web query:
`For Apache Spark 3.5.x DataSource V2, what are the exact interface names
for limit and TopN pushdown (e.g., SupportsPushDownLimit, SupportsPushDownTopN,
PartialLimitPushDown)?`
💡 Result:
In Spark **3.5.x** DataSource V2 (read path), the pushdown *interfaces* are:
- **LIMIT pushdown:**
`org.apache.spark.sql.connector.read.SupportsPushDownLimit` (a `ScanBuilder`
mix-in) [1]
- Partial-limit behavior is indicated via the **method**
`isPartiallyPushed()` on the same interface (there is **no** separate
`PartialLimitPushDown` interface in 3.5.x) [1].
- **Top-N (ORDER BY … LIMIT n) pushdown:**
`org.apache.spark.sql.connector.read.SupportsPushDownTopN` (a `ScanBuilder`
mix-in) [2]
- Partial-TopN behavior is indicated via the **method**
`isPartiallyPushed()` on the same interface (there is **no** separate
`PartialTopNPushDown` interface in 3.5.x) [2].
**Sources:** Spark 3.5.x JavaDoc for `SupportsPushDownLimit` and
`SupportsPushDownTopN`. [1] [2]
---
</details>
**Replace `PartialLimitPushDown` with `SupportsPushDownLimit` on line 264.**
In Spark 3.5.x DataSource V2, `PartialLimitPushDown` is not a valid
interface. The actual limit pushdown interface is `SupportsPushDownLimit`
(partial behavior is indicated via the `isPartiallyPushed()` method on that
same interface). Update line 264 in the `HoodieScanBuilder` row to list
`SupportsPushDownLimit` instead of `PartialLimitPushDown` to match the Spark
interfaces referenced at line 289 and in the abstract.
<details>
<summary>🤖 Prompt for AI Agents</summary>
```
Verify each finding against the current code and only fix it if needed.
In `@rfc/rfc-98/rfc-98.md` around lines 260 - 265, Update the
HoodieScanBuilder
row in the table to replace the incorrect interface name PartialLimitPushDown
with the correct Spark 3.5.x interface SupportsPushDownLimit; ensure the
HoodieScanBuilder entry lists SupportsPushDownFilters,
SupportsPushDownRequiredColumns, SupportsPushDownLimit, and
SupportsPushDownAggregates so it matches the interfaces referenced elsewhere
(e.g., the abstract and the HoodieScanBuilder description).
```
</details>
<!-- fingerprinting:phantom:triton:hawk:52734f43-4871-4109-afbe-ca6d73447841
-->
<!-- This is an auto-generated comment by CodeRabbit -->
— *CodeRabbit*
([original](https://github.com/yihua/hudi/pull/22#discussion_r3040231411))
(source:comment#3040231411)
##########
rfc/rfc-98/rfc-98.md:
##########
@@ -52,25 +49,293 @@ The current implementation of Spark Datasource V2
integration is presented in th
## Implementation
-<!-- -->
+Hudi's write path is mature, and involves indexing, precombining,
upsert/insert routing, file sizing, and table services
(compaction/clustering/cleaning).
+Also `HoodieSparkSqlWriter::write` handles schema evolution, partition
encoding, metadata updates, and multi-writer concurrency.
+DSv2's `WriteBuilder` >> `BatchWrite` >> DataWriter API is too simplistic for
this, and moving to this entirely would be a non-starter. Also, due to the
flexibility of the V1 API in terms of allowing the writes to shuffle data after
the `df.write.format....save` is invoked, Hudi supports a streaming DF write
for its upsert operation. A good majority of Hudi jobs work this way today, and
we cannot break all of these at once
+
+The proposed approach is hybrid: DSv2 for reads, with a DSv1 fallback for
writes (`V2TableWithV1Fallback`) in the current state.
+Later, if a DSv2 write path can be implemented without loss of performance or
functionality, it may become possible to move to full DSv2 support.
+However, this migration should still be incremental, please check the "Future
Work" chapter for details.
+
+Overall proposed architecture for the hybrid approach is shown in the
following schema:
+
+
+
+### DataFrame API
+
+A new SPI short name, `"hudi_v2"`, activates the DSv2 read path when using the
Spark DataFrame API.
+The existing `"hudi"` path remains unchanged.
+This is done to unblock incremental development of the DSv2 path and will be
removed in the long term, please check the "Future Work" chapter for details.
+It also allows switching later from the current DSv1 fallback to a DSv2 write
path, if an implementation without performance degradation is found.
+The DSv2 write path is currently under research.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+df.write.format("hudi").mode(...).save(path)
+ v
+BaseDefaultSource (V1) -> DefaultSource
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+<td>
+<pre>
+df.write.format("hudi_v2").mode(...).save(path)
+ v
+HoodieDataSourceV2 (TableProvider + DataSourceRegister +
CreatableRelationProvider)
+ v
+Spark treats as V1 source for writes
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+spark.read.format("hudi").load(path)
+ v
+V1 DataSource resolution (via ServiceLoader + DataSourceRegister)
+ v
+BaseDefaultSource found
+(extends DefaultSource with DataSourceRegister)
+(not a TableProvider)
+ v
+Spark treats as V1 DataSource
+ v
+DefaultSource.createRelation(...)
+ v
+MergeOnReadSnapshotRelation / BaseRelation
+ v
+LogicalRelation -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+spark.read.format("hudi_v2").load(path)
+ v
+DataSourceV2Utils.lookupProvider("hudi_v2")
+ v
+HoodieDataSourceV2 found
+(extends TableProvider with DataSourceRegister)
+(does not extend SupportsCatalogOptions)
+ v
+Spark uses TableProvider.getTable() directly
+(no catalog routing since no SupportsCatalogOptions)
+ v
+HoodieDataSourceV2.getTable(...)
+ v
+HoodieSparkV2Table(...)
+(no catalogTable, no tableIdentifier)
+ v
+HoodieScanBuilder -> HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
+
+### SQL Queries
+
+Spark SQL API is managed by new configuration parameter
`hoodie.datasource.read.use.v2`, which controls the returned table type.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = false, schemaEvol = false
+ v
+RETURNS: V1Table(catalogTable) via v1TableWrapper
+ v
+Spark V1 write path -> InsertIntoHoodieTableCommand (analysis rule)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsWrite.newWriteBuilder() -> HoodieV1WriteBuilder
+ v
+V1Write -> InsertableRelation.insert(data, overwrite)
+ v
+Align columns (rename + cast to table's user schema)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = false, schemaEvolutionEnabled = false (defaults)
+ v
+RETURNS: HoodieInternalV2Table(...).v1TableWrapper = V1Table(catalogTable)
+ v
+Spark uses V1 fallback -> DefaultSource.createRelation()
+ v
+HoodieFileIndex -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = conf("hoodie.datasource.read.use.v2") = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsRead.newScanBuilder() -> HoodieScanBuilder
+ v
+HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
### Read
-<!-- main part -->
+All new classes go into package `org.apache.spark.sql.hudi.v2` inside
`hudi-spark-common`.
+
+| Class | Spark Interface
| Responsibility
|
+|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `HoodieDataSourceV2` | `TableProvider`, `DataSourceRegister`,
`CreatableRelationProvider`
| SPI entry point for `format("hudi_v2")`.
`CreatableRelationProvider` enables DataFrame API writes via
`df.write.format("hudi_v2")`.
|
+| `HoodieSparkV2Table` | `Table`, `SupportsRead`, `SupportsWrite`,
`V2TableWithV1Fallback`
| Routes reads to DSv2, writes to DSv1 fallback via
`HoodieV1WriteBuilder`.
|
+| `HoodieScanBuilder` | `ScanBuilder`, `SupportsPushDownFilters`,
`SupportsPushDownRequiredColumns`, `PartialLimitPushDown`,
`SupportsPushDownAggregates` | Collects filter, column pruning, limit, and
aggregate pushdowns.
|
+| `HoodieBatchScan` | `Scan`, `Batch`
| Plans input partitions using existing `HoodieFileIndex`.
|
+| `HoodieInputPartition` | `InputPartition`
| Serializable descriptor for file slices.
|
+| `HoodiePartitionReaderFactory` | `PartitionReaderFactory`
| Creates readers on executors. Overrides `supportColumnarReads()` and
`createColumnarReader()` for COW vectorized reads.
|
+| `HoodiePartitionReader` | `PartitionReader[InternalRow]`
| Row-based reader for MOR, incremental, CDC, and COW fallback
(unsupported schema).
|
+| `HoodieColumnarPartitionReader` | `PartitionReader[ColumnarBatch]`
| Columnar reader for COW base files. Returns vectorized Parquet batches
directly to Spark.
|
+| `HoodieV1WriteBuilder` (reused) | `SupportsTruncate`, `SupportsOverwrite`,
`ProvidesHoodieConfig`
| Existing V1 write fallback builder, defined as `private[hudi]` in
`HoodieInternalV2Table.scala`. `HoodieSparkV2Table` directly instantiates it
(sibling class, not a subclass of `HoodieInternalV2Table`).
`HoodieInternalV2Table` is retained for the schema-evolution code path. |
### Table services
-<!-- with read substages -->
+Table services (compaction, clustering, cleaning) are not affected by this
change.
+They operate via the write client and are triggered independently of the read
path.
+
+### Implementation phases
+
+The phases below describe the logical design ordering.
+In practice, `HoodieScanBuilder` declares all pushdown interfaces from the
outset with working implementations, and the PRs may ship multiple phases
together.
+
+1. **Coexistence POC.** All new classes return empty read results, SPI
registration, reuse of `HoodieV1WriteBuilder` for V1 write fallback,
`hoodie.datasource.read.use.v2` config,
+`HoodieV1OrV2Table` extractor update in `HoodieSparkBaseAnalysis` to recognize
`HoodieSparkV2Table` for DDL operations.
+2. **COW snapshot read.** Wire `HoodieBatchScan.planInputPartitions()` to
`HoodieFileIndex`, implement base file reading in `HoodiePartitionReader`.
Column pruning support.
+3. **Filter pushdown.** Implement `HoodieScanBuilder.pushFilters()` for
partition pruning and data skipping via `HoodieFileIndex`.
+4. **Vectorized COW reads.** Enable columnar batch output for COW snapshot
reads to match V1 performance.
+5. **MOR snapshot read.** Extend `HoodiePartitionReader` with base + log merge
logic, reusing `HoodieFileGroupReader`.
+6. **Incremental and CDC queries.** Route based on query type option in
`HoodieScanBuilder`.
+7. **Advanced pushdowns.** `SupportsPushDownAggregates`,
`SupportsPushDownLimit`, `SupportsPushDownTopN`.
## Rollout/Adoption Plan
-<!--
- - rollback of some changes in HUDI-4178
- - check performance before and after, find what actually degrade when we
use V1 workaround
- - implement absent V2 API functionality for read
- - benchmark again
--->
+- The existing `format("hudi")` path is completely untouched, so there is no
regression risk.
Review Comment:
_⚠️ Potential issue_ | _🟡 Minor_
**Avoid absolute “no regression risk” wording**
Line 293 is too absolute for a rollout statement. Even with opt-in paths,
shared code/config paths can still regress. Recommend “minimized risk” or “low
risk with rollback path.”
<details>
<summary>🤖 Prompt for AI Agents</summary>
```
Verify each finding against the current code and only fix it if needed.
In `@rfc/rfc-98/rfc-98.md` at line 293, Update the rollout sentence that
references the existing `format("hudi")` path to avoid absolute wording;
replace
"completely untouched, so there is no regression risk." with a tempered
phrase
such as "minimized risk" or "low risk with a rollback path" (e.g., "left
unchanged, so risk is minimized with an available rollback path") to reflect
potential shared-code/config regression possibilities.
```
</details>
<!-- fingerprinting:phantom:triton:hawk:52734f43-4871-4109-afbe-ca6d73447841
-->
<!-- This is an auto-generated comment by CodeRabbit -->
— *CodeRabbit*
([original](https://github.com/yihua/hudi/pull/22#discussion_r3040231417))
(source:comment#3040231417)
##########
rfc/rfc-98/rfc-98.md:
##########
@@ -52,25 +49,293 @@ The current implementation of Spark Datasource V2
integration is presented in th
## Implementation
-<!-- -->
+Hudi's write path is mature, and involves indexing, precombining,
upsert/insert routing, file sizing, and table services
(compaction/clustering/cleaning).
+Also `HoodieSparkSqlWriter::write` handles schema evolution, partition
encoding, metadata updates, and multi-writer concurrency.
+DSv2's `WriteBuilder` >> `BatchWrite` >> DataWriter API is too simplistic for
this, and moving to this entirely would be a non-starter. Also, due to the
flexibility of the V1 API in terms of allowing the writes to shuffle data after
the `df.write.format....save` is invoked, Hudi supports a streaming DF write
for its upsert operation. A good majority of Hudi jobs work this way today, and
we cannot break all of these at once
+
+The proposed approach is hybrid: DSv2 for reads, with a DSv1 fallback for
writes (`V2TableWithV1Fallback`) in the current state.
+Later, if a DSv2 write path can be implemented without loss of performance or
functionality, it may become possible to move to full DSv2 support.
+However, this migration should still be incremental, please check the "Future
Work" chapter for details.
+
+Overall proposed architecture for the hybrid approach is shown in the
following schema:
+
+
+
+### DataFrame API
+
+A new SPI short name, `"hudi_v2"`, activates the DSv2 read path when using the
Spark DataFrame API.
+The existing `"hudi"` path remains unchanged.
+This is done to unblock incremental development of the DSv2 path and will be
removed in the long term, please check the "Future Work" chapter for details.
+It also allows switching later from the current DSv1 fallback to a DSv2 write
path, if an implementation without performance degradation is found.
+The DSv2 write path is currently under research.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+df.write.format("hudi").mode(...).save(path)
+ v
+BaseDefaultSource (V1) -> DefaultSource
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+<td>
+<pre>
+df.write.format("hudi_v2").mode(...).save(path)
+ v
+HoodieDataSourceV2 (TableProvider + DataSourceRegister +
CreatableRelationProvider)
+ v
+Spark treats as V1 source for writes
+ v
+CreatableRelationProvider.createRelation(...)
+ v
+HoodieSparkSqlWriter.write(...)
+ v
+SparkRDDWriteClient -> upsert/insert/bulk_insert
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+spark.read.format("hudi").load(path)
+ v
+V1 DataSource resolution (via ServiceLoader + DataSourceRegister)
+ v
+BaseDefaultSource found
+(extends DefaultSource with DataSourceRegister)
+(not a TableProvider)
+ v
+Spark treats as V1 DataSource
+ v
+DefaultSource.createRelation(...)
+ v
+MergeOnReadSnapshotRelation / BaseRelation
+ v
+LogicalRelation -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+spark.read.format("hudi_v2").load(path)
+ v
+DataSourceV2Utils.lookupProvider("hudi_v2")
+ v
+HoodieDataSourceV2 found
+(extends TableProvider with DataSourceRegister)
+(does not extend SupportsCatalogOptions)
+ v
+Spark uses TableProvider.getTable() directly
+(no catalog routing since no SupportsCatalogOptions)
+ v
+HoodieDataSourceV2.getTable(...)
+ v
+HoodieSparkV2Table(...)
+(no catalogTable, no tableIdentifier)
+ v
+HoodieScanBuilder -> HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
+
+### SQL Queries
+
+Spark SQL API is managed by new configuration parameter
`hoodie.datasource.read.use.v2`, which controls the returned table type.
+
+<table>
+<tr>
+<th>Operation</th>
+<th>Current implementation</th>
+<th>Additional functionality proposed in this RFC</th>
+</tr>
+<tr>
+<td>Write</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = false, schemaEvol = false
+ v
+RETURNS: V1Table(catalogTable) via v1TableWrapper
+ v
+Spark V1 write path -> InsertIntoHoodieTableCommand (analysis rule)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+<td>
+<pre>
+INSERT INTO hudi_table VALUES (...); -- table created with USING hudi
+ v
+Spark Analyzer resolves table via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+isHoodieTable => true, v2ReadEnabled = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsWrite.newWriteBuilder() -> HoodieV1WriteBuilder
+ v
+V1Write -> InsertableRelation.insert(data, overwrite)
+ v
+Align columns (rename + cast to table's user schema)
+ v
+HoodieSparkSqlWriter.write(...)
+</pre>
+</td>
+</tr>
+<tr>
+<td>Read</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = false, schemaEvolutionEnabled = false (defaults)
+ v
+RETURNS: HoodieInternalV2Table(...).v1TableWrapper = V1Table(catalogTable)
+ v
+Spark uses V1 fallback -> DefaultSource.createRelation()
+ v
+HoodieFileIndex -> FileScan -> ...
+</pre>
+</td>
+<td>
+<pre>
+SELECT * FROM hudi_table; -- table created with USING hudi
+ v
+Spark Analyzer resolves table name via catalog
+ v
+HoodieCatalog.loadTable(Identifier("hudi_table"))
+ v
+super.loadTable(ident)
+ v
+V1Table(catalogTable) where catalogTable.provider = "hudi"
+ v
+isHoodieTable(catalogTable) => true
+ v
+v2ReadEnabled = conf("hoodie.datasource.read.use.v2") = true
+ v
+RETURNS: HoodieSparkV2Table(...)
+ v
+SupportsRead.newScanBuilder() -> HoodieScanBuilder
+ v
+HoodieBatchScan -> ...
+</pre>
+</td>
+</tr>
+</table>
### Read
-<!-- main part -->
+All new classes go into package `org.apache.spark.sql.hudi.v2` inside
`hudi-spark-common`.
+
+| Class | Spark Interface
| Responsibility
|
+|---------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `HoodieDataSourceV2` | `TableProvider`, `DataSourceRegister`,
`CreatableRelationProvider`
| SPI entry point for `format("hudi_v2")`.
`CreatableRelationProvider` enables DataFrame API writes via
`df.write.format("hudi_v2")`.
|
+| `HoodieSparkV2Table` | `Table`, `SupportsRead`, `SupportsWrite`,
`V2TableWithV1Fallback`
| Routes reads to DSv2, writes to DSv1 fallback via
`HoodieV1WriteBuilder`.
|
+| `HoodieScanBuilder` | `ScanBuilder`, `SupportsPushDownFilters`,
`SupportsPushDownRequiredColumns`, `PartialLimitPushDown`,
`SupportsPushDownAggregates` | Collects filter, column pruning, limit, and
aggregate pushdowns.
|
+| `HoodieBatchScan` | `Scan`, `Batch`
| Plans input partitions using existing `HoodieFileIndex`.
|
+| `HoodieInputPartition` | `InputPartition`
| Serializable descriptor for file slices.
|
+| `HoodiePartitionReaderFactory` | `PartitionReaderFactory`
| Creates readers on executors. Overrides `supportColumnarReads()` and
`createColumnarReader()` for COW vectorized reads.
|
+| `HoodiePartitionReader` | `PartitionReader[InternalRow]`
| Row-based reader for MOR, incremental, CDC, and COW fallback
(unsupported schema).
|
+| `HoodieColumnarPartitionReader` | `PartitionReader[ColumnarBatch]`
| Columnar reader for COW base files. Returns vectorized Parquet batches
directly to Spark.
|
+| `HoodieV1WriteBuilder` (reused) | `SupportsTruncate`, `SupportsOverwrite`,
`ProvidesHoodieConfig`
| Existing V1 write fallback builder, defined as `private[hudi]` in
`HoodieInternalV2Table.scala`. `HoodieSparkV2Table` directly instantiates it
(sibling class, not a subclass of `HoodieInternalV2Table`).
`HoodieInternalV2Table` is retained for the schema-evolution code path. |
### Table services
-<!-- with read substages -->
+Table services (compaction, clustering, cleaning) are not affected by this
change.
+They operate via the write client and are triggered independently of the read
path.
+
+### Implementation phases
+
+The phases below describe the logical design ordering.
+In practice, `HoodieScanBuilder` declares all pushdown interfaces from the
outset with working implementations, and the PRs may ship multiple phases
together.
+
+1. **Coexistence POC.** All new classes return empty read results, SPI
registration, reuse of `HoodieV1WriteBuilder` for V1 write fallback,
`hoodie.datasource.read.use.v2` config,
+`HoodieV1OrV2Table` extractor update in `HoodieSparkBaseAnalysis` to recognize
`HoodieSparkV2Table` for DDL operations.
+2. **COW snapshot read.** Wire `HoodieBatchScan.planInputPartitions()` to
`HoodieFileIndex`, implement base file reading in `HoodiePartitionReader`.
Column pruning support.
+3. **Filter pushdown.** Implement `HoodieScanBuilder.pushFilters()` for
partition pruning and data skipping via `HoodieFileIndex`.
+4. **Vectorized COW reads.** Enable columnar batch output for COW snapshot
reads to match V1 performance.
+5. **MOR snapshot read.** Extend `HoodiePartitionReader` with base + log merge
logic, reusing `HoodieFileGroupReader`.
+6. **Incremental and CDC queries.** Route based on query type option in
`HoodieScanBuilder`.
+7. **Advanced pushdowns.** `SupportsPushDownAggregates`,
`SupportsPushDownLimit`, `SupportsPushDownTopN`.
## Rollout/Adoption Plan
-<!--
- - rollback of some changes in HUDI-4178
- - check performance before and after, find what actually degrade when we
use V1 workaround
- - implement absent V2 API functionality for read
- - benchmark again
--->
+- The existing `format("hudi")` path is completely untouched, so there is no
regression risk.
+- For DataFrame API, users opt in by using `format("hudi_v2")`. No config
needed.
+- For SQL queries, users set `hoodie.datasource.read.use.v2=true` to route
reads through DSv2.
+- Rollback: switch back to `format("hudi")` or set the config to `false`.
+
+### Config interaction: `hoodie.datasource.read.use.v2` vs
`hoodie.schema.on.read.enable`
+
+In `HoodieCatalog.loadTable()`, `v2ReadEnabled` is evaluated first and takes
strict precedence:
+
+| `hoodie.datasource.read.use.v2` | `hoodie.schema.on.read.enable` | Table
returned |
+|---------------------------------|--------------------------------|----------------------------------------------------------|
+| `true` (Spark ≥ 3.5) | any |
`HoodieSparkV2Table` (DSv2 read) |
+| `false` | `true` |
`HoodieInternalV2Table` (existing schema-evolution path) |
+| `false` | `false` | `V1Table`
wrapper (existing default) |
+
+The two configs are independent. When both are `true`, `v2ReadEnabled` wins.
## Test Plan
-<!-- It's important to agree on consistent benchmarks to evaluate changes step
by step -->
+- Verify that `EXPLAIN` plans show `BatchScanExec` (DSv2) instead of
`FileSourceScanExec` (DSv1) when DSv2 is enabled.
+- Existing unit and functional tests must pass unchanged (no regressions in
DSv1 path).
+- New tests for DSv2 read path: COW snapshot, MOR snapshot, filter pushdown,
column pruning.
+- TPC-H benchmark to compare DSv1 vs DSv2 read performance at each
implementation phase.
+ Success criteria:
+ - DSv2 COW snapshot full data read should show no regression versus DSv1.
+ - DSv2 COW snapshot read with projections and filter pushdowns should show
10% faster wall-clock time.
+ - DSv2 COW snapshot read with limit and aggregate pushdowns should show
20% faster wall-clock time.
+ - MOR benchmarks should show no regression versus DSv1's row-based MOR
path.
+
+## Future Work
+
+1. DSv2 read support using `hudi_v2` for the DataFrame API, and
`hoodie.datasource.read.use.v2` for the SQL API (`false` by default).
+ These means that all stages from "Implementation phases" chapter are
completed.
Review Comment:
_⚠️ Potential issue_ | _🟡 Minor_
**Fix grammar in Future Work item**
Line 325: “These means” → “This means”.
<details>
<summary>🤖 Prompt for AI Agents</summary>
```
Verify each finding against the current code and only fix it if needed.
In `@rfc/rfc-98/rfc-98.md` at line 325, Update the typo in the Future Work
item
where the sentence currently reads "These means that all stages from
\"Implementation phases\" chapter are completed." — change "These means" to
"This means" so the sentence becomes "This means that all stages from
\"Implementation phases\" chapter are completed."; locate the phrase in
rfc-98.md (the Future Work paragraph containing "These means") and make the
single-word replacement.
```
</details>
<!-- fingerprinting:phantom:triton:hawk:52734f43-4871-4109-afbe-ca6d73447841
-->
<!-- This is an auto-generated comment by CodeRabbit -->
— *CodeRabbit*
([original](https://github.com/yihua/hudi/pull/22#discussion_r3040231419))
(source:comment#3040231419)
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
