From e31cb80812374c63c636ca7910b3e0b2d193fe4d Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Sat, 25 Apr 2026 01:21:32 -0700
Subject: [PATCH] docs(parquet-design): make row-id response optional and
 bounded

A predicate matching millions of rows would force the server to return
millions of row refs. Default the response to range-oriented data
(file/row-group/page refs), require RequestRowIds opt-in for per-row
output, and cap returned ids via MaxRowIds with a Truncated flag.
---
 PARQUET_PUSHDOWN_DESIGN.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/PARQUET_PUSHDOWN_DESIGN.md b/PARQUET_PUSHDOWN_DESIGN.md
index aa1bd3841..92999ceb5 100644
--- a/PARQUET_PUSHDOWN_DESIGN.md
+++ b/PARQUET_PUSHDOWN_DESIGN.md
@@ -407,6 +407,8 @@ type ParquetPushdownRequest struct {
     Predicate      []byte        // serialized per PredicateKind
     VectorQuery    *VectorQuery
     Limit          int
+    RequestRowIds  bool          // include per-row refs in response (default false)
+    MaxRowIds      int           // cap on returned row refs; server may truncate
 }
 
 type PredicateKind int32
@@ -438,13 +440,16 @@ v1 implementations should accept Substrait as the canonical wire format. Iceberg
 
 ### Pushdown Response
 
+The response is range-oriented. Row-id lists are optional and bounded — they are returned only when the request opts in (e.g. for vector top-K) and the planner can verify the result fits within `MaxRowIds`.
+
 ```go
 type ParquetPushdownResponse struct {
     FileRanges []FileRange
     RowGroups  []RowGroupRef
     Pages      []PageRef
-    RowIds     []RowRef
+    RowIds     []RowRef // optional; empty unless RequestRowIds set and within MaxRowIds
     Scores     []float32
+    Truncated  bool     // true if row-id list was omitted/truncated due to size cap
     Stats      PushdownStats
 }