Add named OpenXML table queries with .NET

Author: shps951023

.github/workflows/rust.yml

@@ -101,6 +101,37 @@ jobs:
           --filter "FullyQualifiedName~RustParityContractTests"
           --verbosity minimal
 
+  named-table-parity:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Checkout MiniExcel .NET
+        uses: actions/checkout@v4
+        with:
+          repository: mini-software/MiniExcel
+          ref: b9a76d7af62142e0e38545b6905b01a06e8d160e
+          path: dotnet-source
+      - name: Install Rust 1.85.0
+        uses: dtolnay/rust-toolchain@1.85.0
+      - uses: Swatinem/rust-cache@v2
+        with:
+          key: named-table-parity-${{ matrix.os }}
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+      - name: Run Rust named-table tests
+        run: cargo +1.85.0 test -p miniexcel --test query_table --locked
+      - name: Run MiniExcel .NET named-table tests
+        run: >-
+          dotnet test dotnet-source/tests/MiniExcel.OpenXml.Tests/MiniExcel.OpenXml.Tests.csproj
+          --framework net10.0
+          --filter "FullyQualifiedName~MiniExcelOpenXmlTableTests"
+          --verbosity minimal
+
   msrv:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -206,6 +206,22 @@ Without headers, dynamic keys use the actual Excel column names such as `A`, `B`
 
 Merged cells retain only their physical top-left value by default. Use `ReadOptions::with_fill_merged_cells(true)` to project that value across the merged range for dynamic, typed, and byte queries. Structured queries remain sparse and expose only physically stored cells.
 
+### Named Table Query
+
+Query an OpenXML table by its metadata name without reading cells outside its declared range:
+
+```rust
+let rows = MiniExcel::query_table("book.xlsx", "SalesTable", Some("Data"))?
+    .collect::<miniexcel::Result<Vec<_>>>()?;
+```
+
+`query_table_as::<T>()` provides Serde mapping, `query_table_bytes()` supports in-memory XLSX data,
+and `visit_table_rows*_from_reader()` keeps borrowed readers open. Table names are matched
+case-insensitively against the table `name` (not `displayName`). When no sheet is provided, only
+the first worksheet is searched. Column names come from table metadata, the physical header row is
+skipped unless `headerRowCount="0"`, and the complete declared range is returned, including totals
+rows. Path queries retain the existing bounded-memory two-pass worksheet pipeline.
+
 ## Typed Reading
 
 ```rust

README.zh-CN.md

@@ -206,6 +206,21 @@ for row in MiniExcel::query_with_options("book.xlsx", &options)? {
 
 合并单元格默认只保留物理存储的左上角值。使用 `ReadOptions::with_fill_merged_cells(true)` 可在动态、类型化和 byte query 中将该值投影到整个合并范围。Structured query 仍保持稀疏，只暴露物理存储的 cell。
 
+### 命名 Table Query
+
+可按 OpenXML table metadata name 查询，并且不会读取声明 range 外的 cell：
+
+```rust
+let rows = MiniExcel::query_table("book.xlsx", "SalesTable", Some("Data"))?
+    .collect::<miniexcel::Result<Vec<_>>>()?;
+```
+
+`query_table_as::<T>()` 提供 Serde mapping，`query_table_bytes()` 支持内存 XLSX，
+`visit_table_rows*_from_reader()` 会保持 borrowed reader open。Table name 会按 table
+`name`（不是 `displayName`）进行大小写不敏感匹配。未指定 sheet 时只搜索第一张 worksheet。
+Column name 来自 table metadata；除非 `headerRowCount="0"`，否则会跳过物理 header row；
+返回完整声明 range，包括 totals row。Path query 继续使用既有有界内存两遍 worksheet pipeline。
+
 ## 类型化读取
 
 ```rust

docs/compatibility.md

@@ -42,6 +42,7 @@ The latest `calamine 0.36` and `rust_xlsxwriter 0.97` require Rust 1.88. The MVP
 | `GetSheetInformations` | `MiniExcel::get_sheet_info()` | Includes OOXML ID, order, name, type, visibility, and active state |
 | `GetSheetDimensions` | `MiniExcel::get_sheet_dimensions()` | Returns used ranges in workbook order with 1-based indices |
 | `GetColumns` | `MiniExcel::get_columns()` | Returns selected dynamic keys or an empty vector |
+| `QueryTable` | `query_table()` / `query_table_as()` / byte and borrowed-reader variants | Case-insensitive table-name lookup, metadata headers, and inclusive table bounds |
 | `startCell` | `ReadOptions::with_start_cell()` | A1 start coordinate |
 | `IgnoreEmptyRows` | `ReadOptions::with_ignore_empty_rows()` | Defaults to `false` for MiniExcel compatibility |
 | `FillMergedCells` | `ReadOptions::with_fill_merged_cells()` | Defaults to `false`; applies to dynamic, typed, and byte queries |
@@ -170,6 +171,7 @@ The contract covers only the current common surface: dynamic/typed path queries,
 | `GetSheetNames` and `GetColumns` | Implemented | Yes |
 | `GetSheetInformations` ID/index/name/type/visibility/active | Implemented | Rust tests against .NET fixtures |
 | `GetSheetDimensions` | Implemented | Rust tests against .NET fixtures |
+| Named OpenXML `QueryTable` | Implemented | Rust and .NET focused tests against `TestQueryTable.xlsx` |
 | New-workbook `SaveAs`, including multiple sheets | Implemented and roundtrip-tested | Not yet |
 | Basic `SaveAsTemplate` scalar/list fill | Implemented and roundtrip-tested | Not yet |
 | Byte-array query/write for WASM | Implemented | Rust/browser tests |

docs/compatibility.zh-CN.md

@@ -42,6 +42,7 @@ Rust MVP 在统一的 `MiniExcel` facade 后实现最小但实用的 MiniExcel 
 | `GetSheetInformations` | `MiniExcel::get_sheet_info()` | 包含 OOXML ID、顺序、名称、类型、visibility 和 active 状态 |
 | `GetSheetDimensions` | `MiniExcel::get_sheet_dimensions()` | 按 workbook 顺序返回使用范围，index 从 1 开始 |
 | `GetColumns` | `MiniExcel::get_columns()` | 返回选中的动态 key，或空 vector |
+| `QueryTable` | `query_table()` / `query_table_as()` / byte 和 borrowed-reader variants | 大小写不敏感 table-name lookup、metadata header 与包含端点的 table bounds |
 | `startCell` | `ReadOptions::with_start_cell()` | A1 起始坐标 |
 | `IgnoreEmptyRows` | `ReadOptions::with_ignore_empty_rows()` | 为兼容 MiniExcel，默认值为 `false` |
 | `FillMergedCells` | `ReadOptions::with_fill_merged_cells()` | 默认 `false`；适用于动态、类型化和 byte query |
@@ -170,6 +171,7 @@ Rust workflow 会在 Linux 和 Windows 上运行 Rust 契约。其 .NET parity j
 | `GetSheetNames` 和 `GetColumns` | 已实现 | 是 |
 | `GetSheetInformations` ID/index/name/type/visibility/active | 已实现 | Rust 使用 .NET fixture 测试 |
 | `GetSheetDimensions` | 已实现 | Rust 使用 .NET fixture 测试 |
+| 命名 OpenXML `QueryTable` | 已实现 | Rust/.NET 使用 `TestQueryTable.xlsx` 的 focused test |
 | 新 workbook `SaveAs`（含多工作表） | 已实现并完成 roundtrip 测试 | 尚未 |
 | 基础 `SaveAsTemplate` 标量/列表填充 | 已实现并完成 roundtrip 测试 | 尚未 |
 | 用于 WASM 的字节数组 query/write | 已实现 | Rust/browser 测试 |

docs/dotnet-feature-gaps.md

@@ -8,13 +8,14 @@ This report compares observable public capabilities in the local checkouts below
 
 | Project | Revision |
 | --- | --- |
-| MiniExcel-Rust | `8a76d1af50c039967875511e2e3ca7c746241e51` (`0.3.0`) |
+| MiniExcel-Rust | `1e3167222142a86710e05269f9fcbbba11185d22` (`0.3.0`) |
 | MiniExcel .NET | `b9a76d7af62142e0e38545b6905b01a06e8d160e` |
 
 The comparison uses the .NET public APIs, their controlling implementations, and focused tests under the sibling `../MiniExcel` checkout. Rust status is based on the public `MiniExcel` facade, options, integration tests, and [compatibility boundary](compatibility.md).
 
 Status meanings:
 
+- **Implemented**: the useful observable XLSX behavior is covered by a Rust-native API and focused cross-project evidence.
 - **Partial**: Rust covers the core scenario but not the full observable .NET behavior.
 - **Missing**: no equivalent public Rust capability exists.
 - **Different by design**: Rust provides a native alternative, but it is not API or behavior parity.
@@ -27,8 +28,8 @@ Rust already implements dynamic and Serde-typed XLSX path queries, inclusive A1
 
 | Area | Status | Capability available in .NET but not fully implemented in Rust |
 | --- | --- | --- |
-| Named tables | Missing | Query an OpenXML table by table name (`QueryTable`), including table-specific headers and bounds. |
-| DataReader and DataTable | Missing | `IDataReader`/async reader access, schema tables, typed getters, `NextResult` sheet traversal, and `DataTable` materialization. |
+| Named tables | Implemented | Dynamic/typed path queries, byte queries, and borrowed-reader visitors use table metadata headers and bounds with case-insensitive table-name matching. |
+| DataReader and DataTable | Different by design | Rust exposes iterators and borrowed visitors instead of .NET tabular interfaces. A Rust-native Arrow/record-batch adapter is deferred until a concrete integration requires it and does not block parity completion. |
 | Caller-owned streams | Partial | Borrowed synchronous dynamic/typed/structured visitors, metadata reads, dynamic/schema/typed/multi-sheet writers, and separate reader-to-writer Insert are implemented with leave-open semantics. Borrowed lazy iterators, async streams, and template streams remain unsupported. |
 | Async and cancellation | Partial | Optional runtime-neutral async row production and cancellation are implemented for explicit-schema path Insert. Async query/export/template operations, typed async sources, and progress callbacks remain unsupported. ZIP and filesystem work remains blocking on a dedicated worker. |
 | General save inputs | Partial | Export from general objects/enumerables, dictionaries, `DataTable`, `IDataReader`, and async enumerables, with progress. Rust accepts dynamic or same-type Serde slices and reports per-sheet row counts. |
@@ -50,8 +51,8 @@ Rust already implements dynamic and Serde-typed XLSX path queries, inclusive A1
 | Area | Rust evidence | .NET evidence in `../MiniExcel` |
 | --- | --- | --- |
 | Public read/write boundary | `miniexcel/src/facade.rs`, `miniexcel/src/options.rs` | `src/MiniExcel.OpenXml/Api/OpenXmlImporter.cs`, `OpenXmlExporter.cs` |
-| Tables | No public table API | `OpenXmlImporter.QueryTableAsync`; `tests/MiniExcel.OpenXml.Tests/Tables/` |
-| DataReader/DataTable | No public tabular adapter | `OpenXmlImporter.GetDataReader`, `GetAsyncDataReader`, `QueryAsDataTableAsync`; `tests/MiniExcel.OpenXml.Tests/DataReader/` |
+| Tables | `MiniExcel::query_table*`; Rust focused tests use the exact `TestQueryTable.xlsx` fixture (SHA-256 `04F719BF9F9E99D9B437A8FB32F8111FD92580A1D29ACAD10B6ED128C0564501`) | `OpenXmlImporter.QueryTableAsync`; `tests/MiniExcel.OpenXml.Tests/Tables/` |
+| DataReader/DataTable | Rust iterators and borrowed visitors are the native abstraction; no literal .NET tabular adapter is planned | `OpenXmlImporter.GetDataReader`, `GetAsyncDataReader`, `QueryAsDataTableAsync`; `tests/MiniExcel.OpenXml.Tests/DataReader/` |
 | Multi-sheet and workbook edits | Writer creates multiple sheets; existing workbooks support append and strict replacement with package preservation and bounded explicit-schema producers | `OpenXmlExporter.InsertSheetAsync`, `CopyAndAddSheetAsync`, `AlterSheetAsync`; `tests/MiniExcel.OpenXml.Tests/MultipleSheets/` and `AlterSheets/` |
 | Templates/pictures/merges | Basic template fill implemented; advanced directives and authoring remain deferred | `src/MiniExcel.OpenXml/Api/OpenXmlTemplater.cs`; `tests/MiniExcel.OpenXml.Tests/Templates/` |
 | CSV/conversion | XLSX-only core | `src/MiniExcel.Csv/Api/`; `src/MiniExcel/MiniExcelConverter.cs`; `tests/MiniExcel.Csv.Tests/` |
@@ -63,13 +64,13 @@ The .NET APIs marked with `Async` also have generated synchronous counterparts t
 
 ## Suggested Implementation Order
 
-1. **Named-table query and comments**: focused OpenXML read features with clear fixtures and public result models.
+1. **Comments and notes**: focused OpenXML read features with clear public result models.
 2. **CSV provider**: keep a separate format boundary rather than conditionals inside the XLSX parser.
 3. **Async query/export/template APIs**: extend runtime-neutral producer/cancellation patterns without presenting blocking ZIP work as async I/O.
 4. **Advanced templates and Fluent Mapping**: add grouped/conditional templates, parametrized sheets, and mapping through separate compatibility milestones.
 5. **Remaining workbook edits**: copy/add, rename, reorder, and standalone visibility mutation require their own preservation contracts.
 
-DataReader/DataTable are .NET ecosystem abstractions and should not be ported literally. A Rust-native record-batch or tabular adapter is appropriate only when a concrete integration requires it.
+DataReader/DataTable are .NET ecosystem abstractions and are intentionally not literal Rust parity requirements. A Rust-native record-batch or tabular adapter is appropriate only when a concrete integration requires it.
 
 ## Not Counted as Gaps
 

docs/dotnet-feature-gaps.zh-CN.md

@@ -8,13 +8,14 @@
 
 | 项目 | 版本基线 |
 | --- | --- |
-| MiniExcel-Rust | `8a76d1af50c039967875511e2e3ca7c746241e51`（`0.3.0`） |
+| MiniExcel-Rust | `1e3167222142a86710e05269f9fcbbba11185d22`（`0.3.0`） |
 | MiniExcel .NET | `b9a76d7af62142e0e38545b6905b01a06e8d160e` |
 
 比对依据包括同级目录 `../MiniExcel` 中的 .NET 公开 API、控制实现和聚焦测试，以及 Rust 的公开 `MiniExcel` 门面、选项、集成测试和[兼容性边界](compatibility.zh-CN.md)。
 
 状态定义：
 
+- **已实现**：有实际价值的可观察 XLSX 行为已由 Rust-native API 与跨项目 focused evidence 覆盖。
 - **部分实现**：Rust 已覆盖核心场景，但尚未覆盖 .NET 的完整可观察行为。
 - **未实现**：Rust 当前没有对应的公开能力。
 - **设计不同**：Rust 提供了原生替代方案，但不构成 API 或行为等价。
@@ -27,8 +28,8 @@ Rust 已支持动态及 Serde 强类型 XLSX 路径查询、闭区间 A1 范围
 
 | 领域 | 状态 | .NET 已有而 Rust 尚未完整实现的能力 |
 | --- | --- | --- |
-| 命名表格 | 未实现 | 按表格名称查询 OpenXML Table（`QueryTable`），并遵循表格自身的表头与范围。 |
-| DataReader 与 DataTable | 未实现 | `IDataReader`/异步 reader、架构表、强类型 getter、通过 `NextResult` 遍历工作表，以及物化为 `DataTable`。 |
+| 命名表格 | 已实现 | 动态/类型化 path query、byte query 与 borrowed-reader visitor 使用 table metadata header 和 bounds，并按 table name 大小写不敏感匹配。 |
+| DataReader 与 DataTable | 设计不同 | Rust 使用 iterator 与 borrowed visitor，不复制 .NET tabular interface。只有具体集成需要时才考虑 Rust-native Arrow/record-batch adapter；此项不阻塞 parity 完成。 |
 | 调用方提供的流 | 部分实现 | 已实现借用的同步动态/类型化/structured visitor、metadata 读取、动态/schema/类型化/多表 writer，以及独立 reader-to-writer Insert，并保持 leave-open。借用 lazy iterator、async stream 和 template stream 仍不支持。 |
 | 异步与取消 | 部分实现 | 显式 schema path Insert 已支持可选、runtime-neutral 的 async row producer 与 cancellation。Async query/export/template、类型化 async source 和 progress callback 仍不支持；ZIP 与 filesystem 工作仍在专用 blocking worker 上执行。 |
 | 通用保存输入 | 部分实现 | 从普通对象/可枚举对象、字典、`DataTable`、`IDataReader` 和异步枚举导出，并报告进度。Rust 接受动态行或同类型 Serde 切片，并返回每张工作表的行数。 |
@@ -50,8 +51,8 @@ Rust 已支持动态及 Serde 强类型 XLSX 路径查询、闭区间 A1 范围
 | 领域 | Rust 证据 | `../MiniExcel` 中的 .NET 证据 |
 | --- | --- | --- |
 | 公开读写边界 | `miniexcel/src/facade.rs`、`miniexcel/src/options.rs` | `src/MiniExcel.OpenXml/Api/OpenXmlImporter.cs`、`OpenXmlExporter.cs` |
-| 表格 | 无公开表格 API | `OpenXmlImporter.QueryTableAsync`；`tests/MiniExcel.OpenXml.Tests/Tables/` |
-| DataReader/DataTable | 无公开表格适配器 | `OpenXmlImporter.GetDataReader`、`GetAsyncDataReader`、`QueryAsDataTableAsync`；`tests/MiniExcel.OpenXml.Tests/DataReader/` |
+| 表格 | `MiniExcel::query_table*`；Rust focused test 使用完全相同的 `TestQueryTable.xlsx` fixture（SHA-256 `04F719BF9F9E99D9B437A8FB32F8111FD92580A1D29ACAD10B6ED128C0564501`） | `OpenXmlImporter.QueryTableAsync`；`tests/MiniExcel.OpenXml.Tests/Tables/` |
+| DataReader/DataTable | Rust iterator 与 borrowed visitor 是原生抽象；不计划逐字复制 .NET tabular adapter | `OpenXmlImporter.GetDataReader`、`GetAsyncDataReader`、`QueryAsDataTableAsync`；`tests/MiniExcel.OpenXml.Tests/DataReader/` |
 | 多工作表与工作簿修改 | Writer 可创建多个工作表；现有 workbook 支持 append 与严格 replacement，并保留 package，显式 schema producer 采用有界资源处理 | `OpenXmlExporter.InsertSheetAsync`、`CopyAndAddSheetAsync`、`AlterSheetAsync`；`MultipleSheets/` 与 `AlterSheets/` 测试 |
 | 模板/图片/合并 | 已实现基础模板填充；高级指令与 authoring 仍延期 | `src/MiniExcel.OpenXml/Api/OpenXmlTemplater.cs`；`tests/MiniExcel.OpenXml.Tests/Templates/` |
 | CSV/转换 | 核心仅支持 XLSX | `src/MiniExcel.Csv/Api/`；`src/MiniExcel/MiniExcelConverter.cs`；`tests/MiniExcel.Csv.Tests/` |
@@ -63,13 +64,13 @@ Rust 已支持动态及 Serde 强类型 XLSX 路径查询、闭区间 A1 范围
 
 ## 建议实现顺序
 
-1. **命名表格查询与批注读取**：范围聚焦的 OpenXML 读取功能，容易建立明确 fixture 和公开结果模型。
+1. **Comments 与 notes 读取**：范围聚焦的 OpenXML read feature，需要明确 public result model。
 2. **CSV provider**：保持独立格式边界，不在 XLSX parser 内堆叠条件分支。
 3. **Async query/export/template API**：延续 runtime-neutral producer/cancellation 模式，不把 blocking ZIP 工作描述成 async I/O。
 4. **高级模板与 Fluent Mapping**：通过独立兼容里程碑增加分组/条件模板、参数化 sheet 和 mapping。
 5. **剩余 workbook edit**：copy/add、rename、reorder 和独立 visibility mutation 需要各自的 preservation contract。
 
-DataReader/DataTable 属于 .NET 生态抽象，不建议逐字移植。只有出现明确集成需求时，才应设计 Rust 原生的 record-batch 或表格适配器。
+DataReader/DataTable 属于 .NET 生态抽象，明确不作为逐字 Rust parity 要求。只有出现具体集成需求时，才应设计 Rust-native record-batch 或 table adapter。
 
 ## 不计为缺口
 

miniexcel/src/error.rs

@@ -30,6 +30,12 @@ enum ErrorKind {
     #[error("worksheet '{0}' was not found")]
     SheetNotFound(String),
 
+    #[error("table '{0}' was not found")]
+    TableNotFound(String),
+
+    #[error("invalid table '{name}': {reason}")]
+    InvalidTable { name: String, reason: String },
+
     #[error("the workbook does not contain any worksheets")]
     NoWorksheets,
 
@@ -129,6 +135,14 @@ impl Error {
         ErrorKind::SheetNotFound(sheet_name.into()).into()
     }
 
+    pub(crate) fn table_not_found(table_name: impl Into<String>) -> Self {
+        ErrorKind::TableNotFound(table_name.into()).into()
+    }
+
+    pub(crate) fn invalid_table(name: impl Into<String>, reason: impl Into<String>) -> Self {
+        ErrorKind::InvalidTable { name: name.into(), reason: reason.into() }.into()
+    }
+
     pub(crate) fn no_worksheets() -> Self {
         ErrorKind::NoWorksheets.into()
     }