From 4832fe94d7e276dc3cf15d148f5740e4004227fb Mon Sep 17 00:00:00 2001 From: Marius S <39998+winding-lines@users.noreply.github.com> Date: Tue, 20 Oct 2026 18:08:36 -0700 Subject: [PATCH] Hold the plan in the bridge instead of replanning every read mlake_plan now takes the column selection with the filter, plans once, and returns a handle to the file scan tasks plus the schema, specs and name mapping a read needs. mlake_plan_read reads one task from it through iceberg.mojo's read_data_file; reads only look at the plan, so DataFusion's threads share one. Rust owns the handle as a Plan and frees it on drop. The bridge used to keep nothing between calls, on the grounds that Mojo could not hold an object with a destructor on the heap. Mojo 1.1 can (unsafe_alloc + unsafe_write). Without that, every read reopened the metadata and replanned the manifests to find its own ticket again, about 3 ms per read. taxibench, 1 thread: 0.63-1.34x iceberg-datafusion (was 0.78-1.62x); 10 threads: 0.16-0.46x (was 0.19-0.47x). All 16 answers agree. About 2.5 ms per task remains, inside read_data_file; the README records what it is not. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KxW5zazz1MvVNCxeZzQBRL --- CHANGELOG.md | 15 ++- README.md | 97 ++++++++-------- bench/src/main.rs | 2 +- mojo/src/bridge.mojo | 271 ++++++++++++++++++++++--------------------- rust/src/bridge.rs | 141 +++++++++++----------- rust/src/lib.rs | 103 +++++++--------- rust/src/main.rs | 2 +- rust/tests/oracle.rs | 16 +-- 8 files changed, 325 insertions(+), 322 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c85e1a..53b4342 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,21 @@ so it is not versioned. ## [Unreleased] +### Changed +- **A plan is now a handle held by the bridge.** `mlake_plan` takes the + column selection with the filter, plans once, and returns a handle to the + file scan tasks and everything a read needs. `mlake_plan_read` reads one + task from it, and any number of threads may read one plan at once. + `mlake_read_split`, `mlake_plan_ticket` and the string tickets are gone. + Every read used to reopen the metadata and replan the manifests to find + its task again, about 3 ms each. Single-threaded, the head-to-head is now + 0.63–1.34× iceberg-datafusion's time (was 0.78–1.62×), and 0.16–0.46× with + 10 threads. + ### Added - **A DataFusion `TableProvider` over the Mojo Iceberg scan.** `MlakeTable` - plans a scan into tickets through `mojo/src/bridge.mojo`, which is built as a - shared library. `MlakeExec` reads one ticket per partition, and the batches + plans a scan into file scan tasks through `mojo/src/bridge.mojo`, which is + built as a shared library. `MlakeExec` reads one task per partition, and the batches cross over the Arrow C Data Interface. - **Projection and filter pushdown.** Only the columns a query uses are decoded. Filters are translated into the Iceberg filter DSL and pushed down diff --git a/README.md b/README.md index 4d7390c..8106814 100644 --- a/README.md +++ b/README.md @@ -40,31 +40,33 @@ DataFusion in place of DuckDB. DataFusion (Rust) ArrowArrayStream Mojo (shared library) ───────────────── ──────────────── ───────────────────── SELECT … WHERE id < 5 - MlakeTable::scan ──filter──▶ mlake_plan iceberg.mojo manifests pruned - ◀─tickets─ into tickets + MlakeTable::scan ──columns, filter──▶ mlake_plan iceberg.mojo manifests pruned + ◀──── plan handle ─── into file scan tasks MlakeExec - partition 0 ──ticket, columns, filter──▶ mlake_read_split parquet.mojo row groups - partition 1 ──ticket, columns, filter──▶ mlake_read_split pruned, decoded - … ◀── batches, in place ── arrow-mlake C Data Interface + partition 0 ──── plan, task 0 ────▶ mlake_plan_read parquet.mojo row groups + partition 1 ──── plan, task 1 ────▶ mlake_plan_read pruned, decoded + … ◀── batches, in place ── arrow-mlake C Data Interface ``` - **`mojo/src/bridge.mojo`** is the C interface, built with `mojo build --emit shared-lib`. It is the Iceberg half of duckdb.extension's bridge, plus the column selection and filter that a query engine pushes down. It takes and returns only integers (addresses and - lengths), and it is stateless. A scan is planned into **tickets**, each one - a snapshot plus a byte range of one data file, and every read is a fresh - scan of one ticket. The module docstring explains why: this Mojo has no - globals and cannot keep a reader alive between two calls from C. + lengths). `mlake_plan` plans the scan once and returns a handle to the + plan, which stays on the Mojo side: its **file scan tasks** (a data file or + a byte range of one, its delete files, the filter's residual) and the + schema, specs and name mapping a read needs. `mlake_plan_read` reads one + task from it, without touching the table metadata again, and any number of + threads may read from one plan at once. - **`rust/src/bridge.rs`** loads the library with `libloading` and wraps each - call. Arrow structures are allocated on the Rust side + call. A `Plan` owns the handle and frees it when dropped. Arrow structures are allocated on the Rust side (`FFI_ArrowSchema::empty()`, `FFI_ArrowArrayStream::empty()`); the bridge moves its export into them, and they are freed by their own `release` callbacks. - **`rust/src/lib.rs`** is the `TableProvider` and its `ExecutionPlan`. - Planning happens in `scan`, so DataFusion sees one partition per ticket - that survived the filter. Each partition reads its ticket on a blocking - thread, asking only for the columns the query uses. + Planning happens in `scan`, with the columns the query uses, so DataFusion + sees one partition per task that survived the filter. Each partition reads + its task on a blocking thread. - **`rust/src/filter.rs`** translates DataFusion expressions into the Iceberg filter DSL the Mojo scan reads (`["and", ["<", "id", 5], ["=", "ok", true]]`). It covers comparisons, `IN`, `IS NULL`, `AND`/`OR`/`NOT`, @@ -84,7 +86,7 @@ drops a row the SQL would keep: ```sh pixi run sql --split-size 4096 --explain test/fixtures/db/taxi "SELECT id FROM taxi WHERE id < 5" -# MlakeExec: tickets=1, filter=["<","id",5] (6 tickets without the filter) +# MlakeExec: tasks=1, filter=["<","id",5] (6 tasks without the filter) ``` ## Running it @@ -121,7 +123,7 @@ The queries cover: - grouped aggregates over nulls and timestamps; - ten pushed-down filters; - filters that cannot be pushed down; -- a check that a filter really reduces the number of tickets. +- a check that a filter really reduces the number of tasks. Swapping `<` for `>` in the translation makes the suite fail, which shows the comparison is not vacuous. @@ -135,7 +137,7 @@ comparison is not vacuous. - **Flat schemas are what the fixture exercises.** Nested columns cross the C Data Interface (iceberg.mojo tests them against pyarrow), but the filter translation only addresses top-level columns. -- **`LIMIT` is not pushed down.** Each ticket is read whole, and DataFusion +- **`LIMIT` is not pushed down.** Each task is read whole, and DataFusion stops pulling once it has enough rows. - **No statistics.** DataFusion plans joins without row counts from the manifests, though they are there to be reported. @@ -167,14 +169,14 @@ iceberg-rust `5b82ab9`. | query | 1 thread: iceberg | 1 thread: mlake | | 10 threads: iceberg | 10 threads: mlake | | |---|---:|---:|---:|---:|---:|---:| -| Q1 count, 1 col, filter | 758 ms | 694 ms | 0.92× | 792 ms | 153 ms | 0.19× | -| Q2 one quarter (3 of 24 files) | 180 | 168 | 0.93× | 184 | 39 | 0.21× | -| Q3 cash fares, 2 cols | 517 | 840 | 1.62× | 531 | 158 | 0.30× | -| Q4 tip ratio, 3 cols | 755 | 1101 | 1.46× | 766 | 215 | 0.28× | -| Q5 top zones, group-by | 1128 | 878 | 0.78× | 1025 | 236 | 0.23× | -| Q6 zone revenue 2024 | 842 | 730 | 0.87× | 787 | 166 | 0.21× | -| Q7 one month, all 19 cols | 185 | 200 | 1.08× | 190 | 89 | 0.47× | -| Q8 selective, 4 cols | 741 | 1188 | 1.60× | 750 | 221 | 0.30× | +| Q1 count, 1 col, filter | 776 ms | 532 ms | 0.68× | 789 ms | 126 ms | 0.16× | +| Q2 one quarter (3 of 24 files) | 186 | 160 | 0.86× | 182 | 37 | 0.20× | +| Q3 cash fares, 2 cols | 533 | 677 | 1.27× | 526 | 122 | 0.23× | +| Q4 tip ratio, 3 cols | 781 | 933 | 1.19× | 756 | 185 | 0.24× | +| Q5 top zones, group-by | 1128 | 705 | 0.63× | 1019 | 203 | 0.20× | +| Q6 zone revenue 2024 | 839 | 664 | 0.79× | 779 | 152 | 0.19× | +| Q7 one month, all 19 cols | 184 | 204 | 1.11× | 188 | 86 | 0.46× | +| Q8 selective, 4 cols | 737 | 988 | 1.34× | 737 | 188 | 0.26× | The ratio is mlake ÷ iceberg; below 1 means the Mojo scan is faster. @@ -186,41 +188,40 @@ datafusion-iceberg's `IcebergTableScan` reports a single partition data files concurrently inside that one stream, but all of the decoding is polled from it, so it uses about one core whatever DataFusion is given: its times barely move between the two legs. This provider hands DataFusion one -partition per ticket, which is why it scales. So the right reading is not +partition per task, which is why it scales. So the right reading is not "the Mojo decoder is five times faster" but "a scan that DataFusion can parallelise is". ### Reading the 1-thread column Single-threaded, the comparison is between the two scans themselves, and it -is mixed. Unfiltered one-column sums isolate where the time goes: +is mixed. Unfiltered sums isolate where the time goes: -| probe (1 thread) | iceberg | mlake | -|---|---:|---:| -| `sum(trip_distance)` | 171 ms | 670 ms | -| `sum` of 2 columns | 314 | 855 | -| `sum` of 3 columns | 477 | 1047 | -| `sum(trip_distance)`, 24 tickets instead of 87 | — | 346 | +| probe (1 thread) | iceberg | mlake | mlake, before plan handles | +|---|---:|---:|---:| +| `sum(trip_distance)` | 163 ms | 454 ms | 670 ms | +| `sum` of 2 columns | 302 | 638 | 855 | +| `sum` of 3 columns | 458 | 831 | 1047 | +| `sum(trip_distance)`, 24 tasks instead of 87 | — | 275 | 346 | - **Per column, the two decoders cost about the same:** about 150 ms per column for iceberg-rust and about 185 ms for the Mojo scan. -- **The Mojo scan pays a fixed cost per ticket**, about 5 ms each. The bridge - is stateless, so every `mlake_read_split` re-reads the table metadata and - re-plans the manifests to find its own file. On this table that is 87 - replans per query. Planning whole files (`--split-size 1000000000`, 24 - tickets) halves the one-column probe. What remains is still roughly double - iceberg's time. I expect most of it is the same replanning, done 24 times, - but I haven't separated it out. +- **The Mojo scan pays a fixed cost per task**, about 2.5 ms each. It used to + be about 5 ms. The bridge used to keep nothing between calls, so every read + reopened the table metadata and replanned the manifests to find its own + task, which cost about 3 ms. The plan now stays on the Mojo side and a read + goes straight to its file, which took 160–220 ms off every query that reads + the whole table. +- **What is left is inside the read itself.** It is not the Parquet footer: + reading and parsing the footers for all 87 tasks takes 12 ms. It is not + the byte range either: a task fetches only the row groups it owns. Reading + the 87 tasks straight through `read_data_file`, with no DataFusion and no + bridge, takes 433 ms against 275 ms for the same rows as 24 whole files, + so the cost is per call somewhere in iceberg.mojo or parquet.mojo. I + haven't found it yet. - **iceberg-rust's row filter is expensive.** Q1 is the probe above plus - `trip_distance > 0`, and it costs iceberg 758 ms against 171 ms without the - filter. That is why the Mojo scan wins Q1, Q5 and Q6 even with its fixed - cost. Turning the Mojo scan's own pushdown off changes its times by only - 3–5%. - -The fixed cost is the obvious thing to remove. One option is a ticket that -carries its file scan task: the data file, its delete files and the -residual. A read could then go straight to the Parquet file without -touching the metadata. + `trip_distance > 0`, and it costs iceberg 776 ms against 163 ms without the + filter. That is why the Mojo scan wins Q1, Q5 and Q6. ## License diff --git a/bench/src/main.rs b/bench/src/main.rs index 2b68e7e..a1d3aa2 100644 --- a/bench/src/main.rs +++ b/bench/src/main.rs @@ -15,7 +15,7 @@ //! and allocators for each other. Prints one JSON line: every run's //! wall-clock time, and the answer as strings for `bench/compare.py`. //! -//! `--split-size` sets the Mojo scan's bytes per ticket (0, the default, is +//! `--split-size` sets the Mojo scan's bytes per task (0, the default, is //! the bridge's 16 MiB); it is ignored by the iceberg scan. use std::sync::Arc; diff --git a/mojo/src/bridge.mojo b/mojo/src/bridge.mojo index 3a8345f..3d0497d 100644 --- a/mojo/src/bridge.mojo +++ b/mojo/src/bridge.mojo @@ -9,23 +9,32 @@ query engine needs and DuckDB's table function did not ask for: a column selection and a filter, both pushed down into the scan so that pruning happens in the manifests and the row groups rather than after decoding. -## Why the API is stateless +## A plan is an object, and reads are against it -The natural design would hand Rust an open scan and let it pull batches. This -Mojo cannot: `alloc` has no placement-init for a type with a destructor, and -there are no module-level globals, so there is no way to keep a `BatchReader` -alive between two calls from C. +`mlake_plan` opens the table, plans it once, and returns a handle to the +result: the file scan tasks, each one a data file (or a byte range of one), +its delete files and its residual filter, together with the schema, column +ids, partition specs and name mapping that a read needs. Each task is one +DataFusion partition, and `mlake_plan_read` reads one task from the handle. -What survives the boundary instead is a **plan** — a list of tickets, each a -string naming a snapshot, a file and a byte range — and every read is a fresh -scan of exactly one ticket. DataFusion gets one partition per ticket, and each -partition is read on its own thread. +An earlier version handed out each task as a string (snapshot, offset, path) +and kept nothing between calls, so every read reopened the metadata and +replanned the manifests to find its own task again. On the 87 tasks of the +taxibench table that cost about 3 ms per read. Holding the plan removes it: +a read goes straight to its Parquet file. + +The handle is only read after `mlake_plan` returns, so any number of threads +may call `mlake_plan_read` on it at once. It is freed by `mlake_plan_free`, +which must not overlap with any read. ## Strings in Every string argument is a (pointer, length) pair of UTF-8. `columns` is a newline-separated list of column names, empty for all of them. `filter` is the -JSON filter DSL `iceberg.expressions.parse_filter` reads, empty for none. +JSON filter DSL `iceberg.expressions.parse_filter` reads, empty for none. Both +are given once, to `mlake_plan`: the column selection decides what a read +decodes, and the filter decides which tasks there are and what each task's +residual is. ## Errors @@ -51,11 +60,14 @@ from iceberg.catalog.filesystem import find_latest_metadata from iceberg.io import FileIO from iceberg.metadata import TableMetadata from iceberg.nested import empty_tree -from iceberg.read import ScanOptions -from iceberg.scan import TableScan +from iceberg.read import NameMapping, ScanOptions, ScanResult, read_data_file +from iceberg.read import is_metadata_column +from iceberg.scan import FileScanTask, TableScan +from iceberg.schema import Schema +from iceberg.transforms import PartitionSpec comptime DEFAULT_SPLIT_SIZE = 16 * 1024 * 1024 -"""Target bytes per ticket when the caller does not choose. +"""Target bytes per task when the caller does not choose. Without splitting the unit of work is a whole data file, so one large file is one DataFusion partition no matter how many threads are free. @@ -107,8 +119,7 @@ def _out(s: String) -> Int: def _fail(err: Int, message: String) -> Int: - """Park a message on the caller's two words and return the failure value. - """ + """Park a message on the caller's two words and return the failure value.""" if err != 0: var slot = Pointer[Int, MutUntrackedOrigin](unsafe_from_address=err) slot[unsafe_offset=0] = _out(message) @@ -143,7 +154,9 @@ def _move_into(src: Int, dst: Int, words: Int, free_shell: Bool): def mlake_free(ptr: Int) abi("C") -> None: """Free one string this library returned. Not for plans or streams.""" if ptr != 0: - Pointer[UInt8, MutUntrackedOrigin](unsafe_from_address=ptr).unsafe_free() + Pointer[UInt8, MutUntrackedOrigin]( + unsafe_from_address=ptr + ).unsafe_free() # ── opening a table ───────────────────────────────────────────────────────── @@ -190,89 +203,106 @@ def _schema_into(scan: TableScan, out_ptr: Int) raises: # ── the plan ──────────────────────────────────────────────────────────────── -# Layout, all 8-byte words: [n, (ptr, len) * n]. A plain array rather than a -# Mojo collection because it has to stay valid between two calls from C, and -# nothing with a destructor can. +struct _Plan(Movable): + """Everything a read needs, resolved once from the metadata. + + These are the arguments `TableScan` would otherwise work out again on + every read: `read_data_file` takes them loose, which is what lets a task + be read without its scan. + """ + + var io: FileIO + var tasks: List[FileScanTask] + var specs: List[PartitionSpec] + """One per task: the spec that task's data file was written with.""" + var schema: Schema + """The snapshot's whole schema; `ids` picks the columns out of it.""" + var ids: List[Int] + var meta_columns: List[String] + var mapping: NameMapping + var case_sensitive: Bool + + def __init__(out self, scan: TableScan) raises: + self.io = scan.io.copy() + self.tasks = scan.plan_files() + self.specs = List[PartitionSpec]() + for k in range(len(self.tasks)): + var id = self.tasks[k].spec_id + if scan.metadata.has_spec(id): + self.specs.append(scan.metadata.spec_by_id(id)) + else: + self.specs.append(PartitionSpec.unpartitioned(id)) + self.schema = scan.current_schema() + self.ids = List[Int]() + self.meta_columns = List[String]() + if len(scan.selected) == 0: + var cols = self.schema.columns() + for k in range(len(cols)): + self.ids.append(cols[k].id) + else: + for k in range(len(scan.selected)): + ref name = scan.selected[k] + if is_metadata_column(name): + self.meta_columns.append(name) + else: + self.ids.append(self.schema.find_by_name(name).id) + self.mapping = scan.name_mapping() + self.case_sensitive = scan.case_sensitive + + +def _plan_at(plan: Int) raises -> Pointer[_Plan, MutUntrackedOrigin]: + if plan == 0: + raise Error("mlake: no plan") + return Pointer[_Plan, MutUntrackedOrigin](unsafe_from_address=plan) @export("mlake_plan") def mlake_plan( dir_ptr: Int, dir_len: Int, + columns_ptr: Int, + columns_len: Int, filter_ptr: Int, filter_len: Int, split_size: Int, err: Int, ) abi("C") -> Int: - """Plan a scan; returns a handle whose tickets are the units of work. + """Plan a scan; returns a handle whose tasks are the units of work. Planning reads manifests, not data files: with a filter, partitions and files whose column bounds cannot match are dropped here, before any - partition is created on the Rust side. + partition is created on the Rust side. An empty table is a plan with no + tasks, not an error. """ try: - var table_dir = _in(dir_ptr, dir_len) var scan = _configure( - _open(table_dir), String(), _in(filter_ptr, filter_len) + _open(_in(dir_ptr, dir_len)), + _in(columns_ptr, columns_len), + _in(filter_ptr, filter_len), ).with_split_size(_split_size(split_size)) - if not scan.has_any_snapshot(): - # An empty table is not an error: zero tickets is a complete plan. - var empty = unsafe_alloc[Int](1) - empty[unsafe_offset=0] = 0 - return Int(empty) - - var snapshot_id = scan.snapshot().snapshot_id - var tasks = scan.plan_files() - var words = unsafe_alloc[Int](1 + 2 * len(tasks)) - words[unsafe_offset=0] = len(tasks) - for i in range(len(tasks)): - ref t = tasks[i] - var ticket = ( - String(snapshot_id) - + String("|") - + String(t.start) - + String("|") - + String(t.length) - + String("|") - + t.data_file.file_path - ) - words[unsafe_offset=1 + 2 * i] = _out(ticket) - words[unsafe_offset=2 + 2 * i] = ticket.byte_length() - return Int(words) + var p = unsafe_alloc[_Plan](1) + p.unsafe_write(_Plan(scan)) + return Int(p) except e: return _fail(err, String(e)) @export("mlake_plan_count") def mlake_plan_count(plan: Int) abi("C") -> Int: - if plan == 0: - return 0 - return Pointer[Int, MutUntrackedOrigin](unsafe_from_address=plan)[] - - -@export("mlake_plan_ticket") -def mlake_plan_ticket(plan: Int, i: Int, len_out: Int) abi("C") -> Int: - """The `i`th ticket. The plan owns it; do not free it separately.""" - if plan == 0: - return 0 - var words = Pointer[Int, MutUntrackedOrigin](unsafe_from_address=plan) - if i < 0 or i >= words[unsafe_offset=0]: + """How many tasks the plan has: one DataFusion partition each.""" + try: + return len(_plan_at(plan)[].tasks) + except: return 0 - if len_out != 0: - Pointer[Int, MutUntrackedOrigin](unsafe_from_address=len_out)[] = words[ - unsafe_offset=2 + 2 * i - ] - return words[unsafe_offset=1 + 2 * i] @export("mlake_plan_free") def mlake_plan_free(plan: Int) abi("C") -> None: if plan == 0: return - var words = Pointer[Int, MutUntrackedOrigin](unsafe_from_address=plan) - for i in range(words[unsafe_offset=0]): - mlake_free(words[unsafe_offset=1 + 2 * i]) - words.unsafe_free() + var p = Pointer[_Plan, MutUntrackedOrigin](unsafe_from_address=plan) + p.unsafe_deinit_pointee() + p.unsafe_free() # ── the schema ────────────────────────────────────────────────────────────── @@ -289,76 +319,51 @@ def mlake_schema( return _fail(err, String(e)) -# ── reading one ticket ────────────────────────────────────────────────────── -def _decode_ticket(ticket: String) raises -> Tuple[Int64, Int64, Int64, String]: - """Split on the first three bars; the rest is the path, which may contain - one of its own.""" - var bytes = ticket.as_bytes() - var cuts = List[Int]() - for i in range(len(bytes)): - if bytes[i] == UInt8(124): # "|" - cuts.append(i) - if len(cuts) == 3: - break - if len(cuts) < 3: - raise Error( - "mlake: malformed ticket, expected" - " '|||'" - ) - var snap = Int64(atol(String(unsafe_from_utf8=bytes[: cuts[0]]))) - var start = Int64( - atol(String(unsafe_from_utf8=bytes[cuts[0] + 1 : cuts[1]])) - ) - var length = Int64( - atol(String(unsafe_from_utf8=bytes[cuts[1] + 1 : cuts[2]])) - ) - var path = String(unsafe_from_utf8=bytes[cuts[2] + 1 :]) - return (snap, start, length, path^) - - -@export("mlake_read_split") -def mlake_read_split( - dir_ptr: Int, - dir_len: Int, - ticket_ptr: Int, - ticket_len: Int, - columns_ptr: Int, - columns_len: Int, - filter_ptr: Int, - filter_len: Int, - split_size: Int, - out_ptr: Int, - err: Int, +# ── reading one task ──────────────────────────────────────────────────────── +@export("mlake_plan_read") +def mlake_plan_read( + plan: Int, index: Int, out_ptr: Int, err: Int ) abi("C") -> Int: - """Fill the caller's `ArrowArrayStream` with one ticket's rows; 1 on + """Fill the caller's `ArrowArrayStream` with task `index`'s rows; 1 on success. - Planned at the ticket's own snapshot rather than at whatever is current, - so a query that started before a commit keeps reading the table it was - planned against. `split_size` and `filter` must be the ones the plan was - made with: the split decides which byte range the ticket names, and the - filter's residual is what prunes row groups inside it. + Reads the plan and never changes it, so calls for different tasks (or the + same one) may run on different threads at once. """ try: - var table_dir = _in(dir_ptr, dir_len) - var decoded = _decode_ticket(_in(ticket_ptr, ticket_len)) - var paths = List[String]() - paths.append(decoded[3]) - var starts = List[Int64]() - starts.append(decoded[1]) - - var scan = _configure( - _open(table_dir).use_snapshot(decoded[0]), - _in(columns_ptr, columns_len), - _in(filter_ptr, filter_len), - ).with_split_size(_split_size(split_size)) - var batches = scan.to_batches_for_splits( - paths^, starts^, ScanOptions() + ref p = _plan_at(plan)[] + if index < 0 or index >= len(p.tasks): + raise Error( + "mlake: task " + String(index) + " of " + String(len(p.tasks)) + ) + ref t = p.tasks[index] + var parts = read_data_file( + p.io, + t.data_file, + t.delete_files, + t.data_sequence_number, + p.specs[index], + p.schema, + p.ids, + p.meta_columns, + p.mapping, + t.residual, + p.case_sensitive, + ScanOptions(), + t.start, + t.length, ) + # Popped from the back, so reverse first to keep the file's order. + var rev = List[ScanResult]() + for _ in range(len(parts)): + rev.append(parts.pop()) var exported = List[ExportedArray]() - for bi in range(len(batches)): - ref b = batches[bi] + while len(rev) > 0: + var part = rev.pop() + if part.num_rows() == 0: + continue + var b = part^.take_batch() # A record batch is a struct array with one child per column; the # scan hands back the columns loose, so the struct is added here. var row = ArrayData(ArrowType(AT_STRUCT), String("row")) @@ -370,12 +375,12 @@ def mlake_read_split( exported.append(export_c(b.arena, root)) if len(exported) == 0: - # Every row of the split was deleted or filtered away. The stream + # Every row of the task was deleted or filtered away. The stream # still has to carry the schema, so it gets one empty batch. - var schema = scan.schema() + var projected = p.schema.select(p.ids) var arena = ArrayArena() var root = empty_tree( - arena, schema.store, schema.root, String("row"), 0, False + arena, projected.store, projected.root, String("row"), 0, False ) exported.append(export_c(arena, root)) diff --git a/rust/src/bridge.rs b/rust/src/bridge.rs index b9f7b0a..a0d66a5 100644 --- a/rust/src/bridge.rs +++ b/rust/src/bridge.rs @@ -18,25 +18,12 @@ use datafusion::error::{DataFusionError, Result}; use libloading::Library; type FreeFn = unsafe extern "C" fn(isize); -type PlanFn = unsafe extern "C" fn(isize, isize, isize, isize, isize, isize) -> isize; +type PlanFn = unsafe extern "C" fn(isize, isize, isize, isize, isize, isize, isize, isize) -> isize; type PlanCountFn = unsafe extern "C" fn(isize) -> isize; -type PlanTicketFn = unsafe extern "C" fn(isize, isize, isize) -> isize; +type PlanReadFn = unsafe extern "C" fn(isize, isize, isize, isize) -> isize; type SchemaFn = unsafe extern "C" fn(isize, isize, isize, isize) -> isize; -type ReadSplitFn = unsafe extern "C" fn( - isize, - isize, - isize, - isize, - isize, - isize, - isize, - isize, - isize, - isize, - isize, -) -> isize; - -/// The loaded library and the seven entry points it exports. + +/// The loaded library and the six entry points it exports. /// /// The function pointers are copied out of the `Library` once and stay valid /// for as long as it is loaded, which is as long as this struct lives — the @@ -45,10 +32,9 @@ pub struct Bridge { free: FreeFn, plan: PlanFn, plan_count: PlanCountFn, - plan_ticket: PlanTicketFn, + plan_read: PlanReadFn, plan_free: FreeFn, schema: SchemaFn, - read_split: ReadSplitFn, _lib: Library, } @@ -78,11 +64,6 @@ fn ffi_err(what: &str, e: impl std::fmt::Display) -> DataFusionError { DataFusionError::External(format!("mlake bridge: {what}: {e}").into()) } -/// One planned unit of work: a snapshot, a byte range of one data file. -/// Opaque here — only the bridge decodes it. -#[derive(Debug, Clone)] -pub struct Ticket(pub String); - impl Bridge { pub fn load(path: &Path) -> Result> { // SAFETY: loading a library runs its initialisers; this one is the @@ -98,10 +79,9 @@ impl Bridge { free: sym!(b"mlake_free"), plan: sym!(b"mlake_plan"), plan_count: sym!(b"mlake_plan_count"), - plan_ticket: sym!(b"mlake_plan_ticket"), + plan_read: sym!(b"mlake_plan_read"), plan_free: sym!(b"mlake_plan_free"), schema: sym!(b"mlake_schema"), - read_split: sym!(b"mlake_read_split"), _lib: lib, })) } @@ -143,73 +123,93 @@ impl Bridge { Ok(Arc::new(schema)) } - /// Plan a scan into tickets. `filter` is the Iceberg filter DSL, empty - /// for none. - pub fn plan(&self, table_dir: &str, filter: &str, split_size: i64) -> Result> { + /// Plan a scan of `columns` (all of them when empty), pruned by + /// `filter`, the Iceberg filter DSL (empty for none). + /// + /// Blocking: it reads the table's metadata and manifests. + pub fn plan( + self: &Arc, + table_dir: &str, + columns: &[String], + filter: &str, + split_size: i64, + ) -> Result { + let cols = columns.join("\n"); let mut err = [0isize; 2]; // SAFETY: plain integers in; a plan handle or 0 out. - let plan = unsafe { + let handle = unsafe { (self.plan)( table_dir.as_ptr() as isize, table_dir.len() as isize, + cols.as_ptr() as isize, + cols.len() as isize, filter.as_ptr() as isize, filter.len() as isize, split_size as isize, err.as_mut_ptr() as isize, ) }; - if plan == 0 { + if handle == 0 { return Err(self.take_error(&err)); } - // SAFETY: tickets are owned by the plan and copied out before it is - // freed. - unsafe { - let n = (self.plan_count)(plan); - let mut out = Vec::with_capacity(n as usize); - for i in 0..n { - let mut len: isize = 0; - let p = (self.plan_ticket)(plan, i, &mut len as *mut isize as isize); - let bytes = std::slice::from_raw_parts(p as *const u8, len as usize); - out.push(Ticket(String::from_utf8_lossy(bytes).into_owned())); - } - (self.plan_free)(plan); - Ok(out) - } + // SAFETY: a live handle. + let tasks = unsafe { (self.plan_count)(handle) } as usize; + Ok(Plan { + bridge: Arc::clone(self), + handle, + tasks, + }) + } +} + +/// A planned scan, held on the Mojo side: its file scan tasks and what +/// reading them needs. Freed when dropped. +pub struct Plan { + bridge: Arc, + handle: isize, + tasks: usize, +} + +// SAFETY: the bridge only reads a plan after `mlake_plan` returns, so it may +// be read from any number of threads at once. The only write is the free in +// `drop`, which `&mut self` keeps from overlapping a read. +unsafe impl Send for Plan {} +unsafe impl Sync for Plan {} + +impl std::fmt::Debug for Plan { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(f, "Plan({} tasks)", self.tasks) } +} - /// Every batch of one ticket, with only `columns` (all of them when - /// empty) and with `filter` pruning row groups inside the split. +impl Plan { + /// The number of tasks: one DataFusion partition each. + pub fn len(&self) -> usize { + self.tasks + } + + pub fn is_empty(&self) -> bool { + self.tasks == 0 + } + + /// Every batch of task `index`, with the columns and the filter residual + /// the plan was made with. /// /// Blocking: call it from a blocking thread, never from an async task. - pub fn read_split( - &self, - table_dir: &str, - ticket: &Ticket, - columns: &[String], - filter: &str, - split_size: i64, - ) -> Result> { - let cols = columns.join("\n"); + pub fn read(&self, index: usize) -> Result> { let mut stream = FFI_ArrowArrayStream::empty(); let mut err = [0isize; 2]; // SAFETY: the bridge moves an `ArrowArrayStream` into `stream`. let ok = unsafe { - (self.read_split)( - table_dir.as_ptr() as isize, - table_dir.len() as isize, - ticket.0.as_ptr() as isize, - ticket.0.len() as isize, - cols.as_ptr() as isize, - cols.len() as isize, - filter.as_ptr() as isize, - filter.len() as isize, - split_size as isize, + (self.bridge.plan_read)( + self.handle, + index as isize, &mut stream as *mut FFI_ArrowArrayStream as *mut c_void as isize, err.as_mut_ptr() as isize, ) }; if ok == 0 { - return Err(self.take_error(&err)); + return Err(self.bridge.take_error(&err)); } let reader = ArrowArrayStreamReader::try_new(stream).map_err(|e| ffi_err("stream", e))?; reader @@ -217,3 +217,10 @@ impl Bridge { .map_err(|e| ffi_err("batch", e)) } } + +impl Drop for Plan { + fn drop(&mut self) { + // SAFETY: the handle came from `mlake_plan` and is freed once. + unsafe { (self.bridge.plan_free)(self.handle) } + } +} diff --git a/rust/src/lib.rs b/rust/src/lib.rs index ea9e933..273cd46 100644 --- a/rust/src/lib.rs +++ b/rust/src/lib.rs @@ -2,17 +2,17 @@ //! //! ```text //! DataFusion ArrowArrayStream Mojo -//! SELECT … FROM taxi ─▶ MlakeTable ─▶ plan ─▶ tickets iceberg.mojo planning -//! MlakeExec ─▶ one partition per ticket -//! partition i ─▶ read_split(ticket i) ─▶ parquet.mojo decoding +//! SELECT … FROM taxi ─▶ MlakeTable ─▶ plan ─▶ tasks iceberg.mojo planning +//! MlakeExec ─▶ one partition per task +//! partition i ─▶ plan.read(i) ─▶ parquet.mojo decoding //! arrow-mlake C Data Interface //! ``` //! -//! Planning happens in `scan`, so the number of partitions DataFusion sees -//! is the number of tickets left after the filter pruned the manifests. Each -//! partition then reads one ticket on a blocking thread, with the projection -//! and the filter passed down so that only the selected columns are decoded -//! and only row groups that can match are read. +//! Planning happens in `scan`, with the projection and the filter, so the +//! number of partitions DataFusion sees is the number of file scan tasks left +//! after the filter pruned the manifests. The plan stays on the Mojo side, and +//! each partition reads one of its tasks on a blocking thread: only the +//! selected columns are decoded, and only row groups that can match are read. pub mod bridge; pub mod filter; @@ -39,9 +39,9 @@ use datafusion::physical_plan::{ }; use futures::{StreamExt, TryStreamExt}; -use crate::bridge::{Bridge, Ticket}; +use crate::bridge::{Bridge, Plan}; -/// Bytes per ticket when not chosen: the bridge's own default. +/// Bytes per task when not chosen: the bridge's own default. pub const DEFAULT_SPLIT_SIZE: i64 = 0; /// An Iceberg table on the local filesystem, read through the Mojo bridge. @@ -67,7 +67,7 @@ impl MlakeTable { }) } - /// Divide data files into tickets of about `bytes` each, so one large + /// Divide data files into tasks of about `bytes` each, so one large /// file is read by several partitions. pub fn with_split_size(mut self, bytes: i64) -> Self { self.split_size = bytes; @@ -116,49 +116,41 @@ impl TableProvider for MlakeTable { None => Arc::clone(&self.schema), }; let dsl = filter::conjunction(filters); + + // Read only what the query uses. A query that reads no columns at + // all — `count(*)` — still needs row counts, so it asks for one. + let mut columns: Vec = projected + .fields() + .iter() + .map(|f| f.name().clone()) + .collect(); + if columns.is_empty() { + columns.push(self.schema.field(0).name().clone()); + } + let bridge = Arc::clone(&self.bridge); let (dir, f, split) = (self.table_dir.clone(), dsl.clone(), self.split_size); - let tickets = tokio::task::spawn_blocking(move || bridge.plan(&dir, &f, split)) + let plan = tokio::task::spawn_blocking(move || bridge.plan(&dir, &columns, &f, split)) .await .map_err(|e| DataFusionError::External(e.into()))??; - Ok(Arc::new(MlakeExec::new( - Arc::clone(&self.bridge), - self.table_dir.clone(), - projected, - self.schema.field(0).name().clone(), - dsl, - self.split_size, - tickets, - ))) + Ok(Arc::new(MlakeExec::new(projected, dsl, plan))) } } -/// The physical scan: one partition per ticket. +/// The physical scan: one partition per file scan task. #[derive(Debug)] pub struct MlakeExec { - bridge: Arc, - table_dir: String, schema: SchemaRef, - first_column: String, filter: String, - split_size: i64, - tickets: Arc>, + plan: Arc, properties: Arc, } impl MlakeExec { - fn new( - bridge: Arc, - table_dir: String, - schema: SchemaRef, - first_column: String, - filter: String, - split_size: i64, - tickets: Vec, - ) -> Self { - // Zero tickets is still one (empty) partition: DataFusion expects at + fn new(schema: SchemaRef, filter: String, plan: Plan) -> Self { + // Zero tasks is still one (empty) partition: DataFusion expects at // least one to execute. - let partitions = tickets.len().max(1); + let partitions = plan.len().max(1); let properties = Arc::new(PlanProperties::new( EquivalenceProperties::new(Arc::clone(&schema)), Partitioning::UnknownPartitioning(partitions), @@ -166,19 +158,16 @@ impl MlakeExec { Boundedness::Bounded, )); Self { - bridge, - table_dir, schema, - first_column, filter, - split_size, - tickets: Arc::new(tickets), + plan: Arc::new(plan), properties, } } - pub fn tickets(&self) -> usize { - self.tickets.len() + /// The number of file scan tasks, which is the number of partitions. + pub fn tasks(&self) -> usize { + self.plan.len() } } @@ -186,13 +175,13 @@ impl DisplayAs for MlakeExec { fn fmt_as(&self, t: DisplayFormatType, f: &mut fmt::Formatter) -> fmt::Result { match t { DisplayFormatType::Default | DisplayFormatType::Verbose => { - write!(f, "MlakeExec: tickets={}", self.tickets.len())?; + write!(f, "MlakeExec: tasks={}", self.plan.len())?; if !self.filter.is_empty() { write!(f, ", filter={}", self.filter)?; } Ok(()) } - DisplayFormatType::TreeRender => write!(f, "tickets={}", self.tickets.len()), + DisplayFormatType::TreeRender => write!(f, "tasks={}", self.plan.len()), } } } @@ -230,27 +219,17 @@ impl ExecutionPlan for MlakeExec { _context: Arc, ) -> Result { let schema = Arc::clone(&self.schema); - let Some(ticket) = self.tickets.get(partition).cloned() else { + if partition >= self.plan.len() { let empty = futures::stream::empty(); return Ok(Box::pin(RecordBatchStreamAdapter::new(schema, empty))); - }; - - // Read only what the query uses. A query that reads no columns at - // all — `count(*)` — still needs row counts, so it asks for one. - let mut columns: Vec = schema.fields().iter().map(|f| f.name().clone()).collect(); - if columns.is_empty() { - columns.push(self.first_column.clone()); } - let bridge = Arc::clone(&self.bridge); - let (dir, f, split) = (self.table_dir.clone(), self.filter.clone(), self.split_size); + let plan = Arc::clone(&self.plan); let out_schema = Arc::clone(&schema); let batches = futures::stream::once(async move { - let batches = tokio::task::spawn_blocking(move || { - bridge.read_split(&dir, &ticket, &columns, &f, split) - }) - .await - .map_err(|e| DataFusionError::External(e.into()))??; + let batches = tokio::task::spawn_blocking(move || plan.read(partition)) + .await + .map_err(|e| DataFusionError::External(e.into()))??; let shaped = batches .into_iter() .map(|b| conform(&b, &out_schema)) diff --git a/rust/src/main.rs b/rust/src/main.rs index 3e41068..4880b57 100644 --- a/rust/src/main.rs +++ b/rust/src/main.rs @@ -6,7 +6,7 @@ //! //! The table is registered under its directory's name (`.../db/taxi` → //! `taxi`); `--name` overrides it, `--split-size` divides files into smaller -//! tickets, and `--explain` prints the physical plan instead of running it. +//! tasks, and `--explain` prints the physical plan instead of running it. use std::sync::Arc; diff --git a/rust/tests/oracle.rs b/rust/tests/oracle.rs index aa792f2..4f4148c 100644 --- a/rust/tests/oracle.rs +++ b/rust/tests/oracle.rs @@ -127,22 +127,22 @@ async fn filters_it_cannot_push_down_are_still_applied() { } #[tokio::test] -async fn filters_prune_tickets() { +async fn filters_prune_tasks() { let ctx = context().await; - let tickets = |plan: String| -> usize { + let tasks = |plan: String| -> usize { let at = plan - .find("MlakeExec: tickets=") + .find("MlakeExec: tasks=") .expect("an MlakeExec in the plan"); - let rest = &plan[at + "MlakeExec: tickets=".len()..]; + let rest = &plan[at + "MlakeExec: tasks=".len()..]; rest[..rest.find(|c: char| !c.is_ascii_digit()).unwrap()] .parse() .unwrap() }; - let all = tickets(rows(&ctx, "EXPLAIN SELECT id FROM taxi").await); - let few = tickets(rows(&ctx, "EXPLAIN SELECT id FROM taxi WHERE id < 5").await); + let all = tasks(rows(&ctx, "EXPLAIN SELECT id FROM taxi").await); + let few = tasks(rows(&ctx, "EXPLAIN SELECT id FROM taxi WHERE id < 5").await); assert!( all > 1, - "split planning should divide the fixture, got {all} tickets" + "split planning should divide the fixture, got {all} tasks" ); - assert!(few < all, "id < 5 should prune tickets: {few} of {all}"); + assert!(few < all, "id < 5 should prune tasks: {few} of {all}"); }