Skip to content

Commit b125cf8

Browse files
committed
feat: add read-optimized system table
1 parent ffbda4f commit b125cf8

14 files changed

Lines changed: 552 additions & 12 deletions

docs/source/user_guide.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ User Guide
3030
user_guide/data_types
3131
user_guide/primary_key_table
3232
user_guide/append_only_table
33+
user_guide/system_tables
3334
user_guide/write
3435
user_guide/commit
3536
user_guide/compaction
Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
.. Copyright 2026-present Alibaba Inc.
2+
3+
.. Licensed under the Apache License, Version 2.0 (the "License");
4+
.. you may not use this file except in compliance with the License.
5+
.. You may obtain a copy of the License at
6+
7+
.. http://www.apache.org/licenses/LICENSE-2.0
8+
9+
.. Unless required by applicable law or agreed to in writing, software
10+
.. distributed under the License is distributed on an "AS IS" BASIS,
11+
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
.. See the License for the specific language governing permissions and
13+
.. limitations under the License.
14+
15+
System Tables
16+
=============
17+
18+
Paimon C++ supports reading system tables by appending a system table suffix to
19+
the data table path. For example, ``/warehouse/db.db/orders$snapshots`` reads
20+
the snapshots system table for ``orders``.
21+
22+
Branch-qualified paths are also supported. For example,
23+
``/warehouse/db.db/orders$branch_audit$files`` reads the files system table from
24+
the ``audit`` branch.
25+
26+
Read-Optimized System Table
27+
---------------------------
28+
29+
The read-optimized system table is addressed by the ``$ro`` suffix:
30+
31+
.. code-block:: text
32+
33+
/warehouse/db.db/orders$ro
34+
35+
For primary-key tables, ``$ro`` only plans data files from the highest LSM
36+
level, which is the level produced by full compaction. This avoids merging data
37+
from multiple LSM levels during query planning and reading. The tradeoff is that
38+
the result may lag behind the latest committed data until a full compaction
39+
publishes the newest records into the highest level.
40+
41+
For primary-key tables, ``$ro`` also enables value-stats filtering, so file-level
42+
pruning of the reader predicate can be more aggressive than the base table.
43+
44+
For append-only tables, ``$ro`` has the same read behavior as the base table,
45+
including streaming reads.
46+
47+
Limitations
48+
~~~~~~~~~~~
49+
50+
- Primary-key ``$ro`` scans are batch-only. Streaming scans are not supported.
51+
- Freshness depends on full compaction frequency.
52+
- Primary-key tables in bucket-unaware mode are not supported by the current C++
53+
scan path.
54+
55+
Typical Usage
56+
~~~~~~~~~~~~~
57+
58+
Use ``$ro`` for OLAP or batch workloads that can tolerate stale results and
59+
prefer reading compacted files directly. Use the base table path when the query
60+
must see the latest committed data.

src/paimon/CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -343,6 +343,7 @@ set(PAIMON_CORE_SRCS
343343
core/table/system/binlog_system_table.cpp
344344
core/table/system/in_memory_system_table.cpp
345345
core/table/system/metadata_system_tables.cpp
346+
core/table/system/read_optimized_system_table.cpp
346347
core/table/system/system_table.cpp
347348
core/table/system/system_table_scan.cpp
348349
core/table/system/system_table_schema.cpp

src/paimon/core/table/source/data_table_batch_scan.cpp

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,15 @@ class DataSplit;
3333

3434
DataTableBatchScan::DataTableBatchScan(bool pk_table, const CoreOptions& core_options,
3535
const std::shared_ptr<SnapshotReader>& snapshot_reader,
36-
std::optional<int32_t> push_down_limit)
36+
bool read_optimized, std::optional<int32_t> push_down_limit)
3737
: AbstractTableScan(core_options, snapshot_reader), push_down_limit_(push_down_limit) {
38-
if (pk_table && (core_options.DeletionVectorsEnabled() ||
39-
core_options.GetMergeEngine() == MergeEngine::FIRST_ROW)) {
38+
if (pk_table && read_optimized) {
39+
int32_t top_level = core_options.GetNumLevels() - 1;
40+
snapshot_reader_->WithLevelFilter(
41+
[top_level](int32_t level) -> bool { return level == top_level; });
42+
snapshot_reader_->EnableValueFilter();
43+
} else if (pk_table && (core_options.DeletionVectorsEnabled() ||
44+
core_options.GetMergeEngine() == MergeEngine::FIRST_ROW)) {
4045
auto level_filter = [](int32_t level) -> bool { return level > 0; };
4146
snapshot_reader_->WithLevelFilter(level_filter);
4247
snapshot_reader_->EnableValueFilter();

src/paimon/core/table/source/data_table_batch_scan.h

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ class SnapshotReader;
3232
class DataTableBatchScan : public AbstractTableScan {
3333
public:
3434
DataTableBatchScan(bool pk_table, const CoreOptions& core_options,
35-
const std::shared_ptr<SnapshotReader>& snapshot_reader,
35+
const std::shared_ptr<SnapshotReader>& snapshot_reader, bool read_optimized,
3636
std::optional<int32_t> push_down_limit);
3737

3838
Result<std::shared_ptr<Plan>> CreatePlan() override;
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
/*
2+
* Copyright 2026-present Alibaba Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#pragma once
18+
19+
namespace paimon {
20+
21+
/// Internal scan option used by `T$ro` to request top-level-only planning.
22+
inline constexpr char kReadOptimizedScanOption[] = "__paimon.internal.read-optimized";
23+
24+
} // namespace paimon

src/paimon/core/table/source/table_scan.cpp

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
#include "paimon/core/table/source/data_table_batch_scan.h"
4848
#include "paimon/core/table/source/data_table_stream_scan.h"
4949
#include "paimon/core/table/source/merge_tree_split_generator.h"
50+
#include "paimon/core/table/source/read_optimized_scan_options.h"
5051
#include "paimon/core/table/source/snapshot/snapshot_reader.h"
5152
#include "paimon/core/table/source/split_generator.h"
5253
#include "paimon/core/table/system/system_table.h"
@@ -225,9 +226,15 @@ Result<std::unique_ptr<TableScan>> NewDataTableScan(const std::shared_ptr<ScanCo
225226
}
226227
table_schema = latest_table_schema.value();
227228
}
229+
const auto read_optimized_iter = context->GetOptions().find(kReadOptimizedScanOption);
230+
const bool read_optimized =
231+
read_optimized_iter != context->GetOptions().end() && read_optimized_iter->second == "true";
228232
// merge options
229233
auto options = table_schema->Options();
230234
for (const auto& [key, value] : context->GetOptions()) {
235+
if (key == kReadOptimizedScanOption) {
236+
continue;
237+
}
231238
options[key] = value;
232239
}
233240
PAIMON_ASSIGN_OR_RAISE(CoreOptions core_options,
@@ -280,12 +287,16 @@ Result<std::unique_ptr<TableScan>> NewDataTableScan(const std::shared_ptr<ScanCo
280287
context->GetMemoryPool()));
281288
auto snapshot_reader = std::make_shared<SnapshotReader>(
282289
file_store_scan, path_factory, std::move(split_generator), std::move(index_file_handler));
290+
const bool pk_table = !table_schema->PrimaryKeys().empty();
291+
if (read_optimized && pk_table && context->IsStreamingMode()) {
292+
return Status::NotImplemented(
293+
"read-optimized system table does not support streaming scan for primary key table");
294+
}
283295
if (context->IsStreamingMode()) {
284296
return std::make_unique<DataTableStreamScan>(core_options, snapshot_reader);
285297
}
286-
auto batch_scan =
287-
std::make_unique<DataTableBatchScan>(/*pk_table=*/!table_schema->PrimaryKeys().empty(),
288-
core_options, snapshot_reader, context->GetLimit());
298+
auto batch_scan = std::make_unique<DataTableBatchScan>(
299+
/*pk_table=*/pk_table, core_options, snapshot_reader, read_optimized, context->GetLimit());
289300
if (!core_options.DataEvolutionEnabled()) {
290301
return batch_scan;
291302
}

src/paimon/core/table/source/table_scan_test.cpp

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616

1717
#include "paimon/table/source/table_scan.h"
1818

19+
#include <memory>
1920
#include <string>
2021
#include <utility>
2122
#include <vector>
@@ -59,4 +60,17 @@ TEST(TableScanTest, TestPkSchemaEvolutionScan) {
5960
ASSERT_FALSE(plan->Splits().empty());
6061
}
6162

63+
TEST(TableScanTest, TestReadOptimizedPrimaryKeyStreamingScanUnsupported) {
64+
std::string path = paimon::test::GetDataDir() +
65+
"/orc/pk_table_with_alter_table.db/pk_table_with_alter_table$ro";
66+
ScanContextBuilder builder(path);
67+
builder.AddOption(Options::FILE_FORMAT, "orc");
68+
builder.WithStreamingMode(true);
69+
ASSERT_OK_AND_ASSIGN(std::unique_ptr<ScanContext> context, builder.Finish());
70+
71+
ASSERT_NOK_WITH_MSG(TableScan::Create(std::move(context)),
72+
"read-optimized system table does not support streaming scan for primary "
73+
"key table");
74+
}
75+
6276
} // namespace paimon::test
Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
/*
2+
* Copyright 2026-present Alibaba Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#include "paimon/core/table/system/read_optimized_system_table.h"
18+
19+
#include <memory>
20+
#include <string>
21+
#include <utility>
22+
23+
#include "paimon/common/types/data_field.h"
24+
#include "paimon/core/schema/table_schema.h"
25+
#include "paimon/core/table/source/read_optimized_scan_options.h"
26+
#include "paimon/defs.h"
27+
#include "paimon/read_context.h"
28+
#include "paimon/scan_context.h"
29+
#include "paimon/table/source/table_read.h"
30+
#include "paimon/table/source/table_scan.h"
31+
32+
namespace paimon {
33+
34+
ReadOptimizedSystemTable::ReadOptimizedSystemTable(std::string table_path,
35+
std::shared_ptr<TableSchema> table_schema,
36+
std::map<std::string, std::string> options)
37+
: table_path_(std::move(table_path)),
38+
table_schema_(std::move(table_schema)),
39+
options_(std::move(options)) {}
40+
41+
std::string ReadOptimizedSystemTable::Name() const {
42+
return kName;
43+
}
44+
45+
Result<std::shared_ptr<arrow::Schema>> ReadOptimizedSystemTable::ArrowSchema() const {
46+
return DataField::ConvertDataFieldsToArrowSchema(table_schema_->Fields());
47+
}
48+
49+
std::map<std::string, std::string> ReadOptimizedSystemTable::ReadOptimizedOptions() const {
50+
auto options = options_;
51+
options[kReadOptimizedScanOption] = "true";
52+
return options;
53+
}
54+
55+
Result<std::unique_ptr<TableScan>> ReadOptimizedSystemTable::NewScan(
56+
const std::shared_ptr<ScanContext>& context) const {
57+
auto options = ReadOptimizedOptions();
58+
ScanContextBuilder builder(table_path_);
59+
builder.SetOptions(options)
60+
.WithStreamingMode(context->IsStreamingMode())
61+
.WithMemoryPool(context->GetMemoryPool())
62+
.WithExecutor(context->GetExecutor())
63+
.WithFileSystem(context->GetSpecificFileSystem())
64+
.WithCache(context->GetCache());
65+
if (context->GetLimit().has_value()) {
66+
builder.SetLimit(context->GetLimit().value());
67+
}
68+
if (context->GetScanFilters()) {
69+
if (context->GetScanFilters()->GetBucketFilter().has_value()) {
70+
builder.SetBucketFilter(context->GetScanFilters()->GetBucketFilter().value());
71+
}
72+
builder.SetPartitionFilter(context->GetScanFilters()->GetPartitionFilters());
73+
builder.SetPredicate(context->GetScanFilters()->GetPredicate());
74+
}
75+
if (context->GetGlobalIndexResult()) {
76+
builder.SetGlobalIndexResult(context->GetGlobalIndexResult());
77+
}
78+
if (context->GetSpecificTableSchema().has_value()) {
79+
builder.SetTableSchema(context->GetSpecificTableSchema().value());
80+
}
81+
PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<ScanContext> base_context, builder.Finish());
82+
return TableScan::Create(std::move(base_context));
83+
}
84+
85+
Result<std::unique_ptr<TableRead>> ReadOptimizedSystemTable::NewRead(
86+
const std::shared_ptr<ReadContext>& context) const {
87+
auto options = options_;
88+
std::string branch = context->GetBranch();
89+
// SystemTableLoader injects Options::BRANCH when parsing paths such as `T$branch_dev$ro`.
90+
auto branch_iter = options.find(Options::BRANCH);
91+
if (branch_iter != options.end()) {
92+
branch = branch_iter->second;
93+
}
94+
ReadContextBuilder builder(table_path_);
95+
builder.SetOptions(options)
96+
.WithBranch(branch)
97+
.SetPredicate(context->GetPredicate())
98+
.EnablePredicateFilter(context->EnablePredicateFilter())
99+
.EnablePrefetch(context->EnablePrefetch())
100+
.SetPrefetchBatchCount(context->GetPrefetchBatchCount())
101+
.SetPrefetchMaxParallelNum(context->GetPrefetchMaxParallelNum())
102+
.EnableMultiThreadRowToBatch(context->EnableMultiThreadRowToBatch())
103+
.SetRowToBatchThreadNumber(context->GetRowToBatchThreadNumber())
104+
.WithMemoryPool(context->GetMemoryPool())
105+
.WithExecutor(context->GetExecutor())
106+
.WithFileSystem(context->GetSpecificFileSystem())
107+
.WithFileSystemSchemeToIdentifierMap(context->GetFileSystemSchemeToIdentifierMap())
108+
.SetPrefetchCacheMode(context->GetPrefetchCacheMode())
109+
.WithCacheConfig(context->GetCacheConfig())
110+
.WithCache(context->GetCache());
111+
if (!context->GetReadFieldIds().empty()) {
112+
builder.SetReadFieldIds(context->GetReadFieldIds());
113+
} else {
114+
builder.SetReadFieldNames(context->GetReadFieldNames());
115+
}
116+
if (context->GetSpecificTableSchema().has_value()) {
117+
builder.SetTableSchema(context->GetSpecificTableSchema().value());
118+
}
119+
PAIMON_ASSIGN_OR_RAISE(std::unique_ptr<ReadContext> base_context, builder.Finish());
120+
return TableRead::Create(std::move(base_context));
121+
}
122+
123+
} // namespace paimon
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* Copyright 2026-present Alibaba Inc.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
#pragma once
18+
19+
#include <map>
20+
#include <memory>
21+
#include <string>
22+
23+
#include "paimon/core/table/system/system_table.h"
24+
25+
namespace paimon {
26+
class TableSchema;
27+
28+
/// System table for `T$ro`, exposing read-optimized data.
29+
class ReadOptimizedSystemTable : public SystemTable {
30+
public:
31+
static constexpr const char* kName = "ro";
32+
33+
ReadOptimizedSystemTable(std::string table_path, std::shared_ptr<TableSchema> table_schema,
34+
std::map<std::string, std::string> options);
35+
36+
std::string Name() const override;
37+
Result<std::shared_ptr<arrow::Schema>> ArrowSchema() const override;
38+
Result<std::unique_ptr<TableScan>> NewScan(
39+
const std::shared_ptr<ScanContext>& context) const override;
40+
Result<std::unique_ptr<TableRead>> NewRead(
41+
const std::shared_ptr<ReadContext>& context) const override;
42+
43+
private:
44+
std::map<std::string, std::string> ReadOptimizedOptions() const;
45+
46+
std::string table_path_;
47+
std::shared_ptr<TableSchema> table_schema_;
48+
std::map<std::string, std::string> options_;
49+
};
50+
51+
} // namespace paimon

0 commit comments

Comments
 (0)