From 28c834c76fdeefc0335bc146aef89e8e6d7c63d8 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Sat, 25 Apr 2026 01:21:11 -0700
Subject: [PATCH] docs(parquet-design): specify predicate wire format and enum
 metrics

Replace opaque Predicate []byte with a tagged (PredicateKind, bytes)
pair, naming Substrait as the canonical v1 format and Iceberg
Expression JSON as a convenience. Replace the free-form Metric string
on VectorQuery with a VectorMetric enum.
---
 PARQUET_PUSHDOWN_DESIGN.md | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/PARQUET_PUSHDOWN_DESIGN.md b/PARQUET_PUSHDOWN_DESIGN.md
index 0f591243b..aa1bd3841 100644
--- a/PARQUET_PUSHDOWN_DESIGN.md
+++ b/PARQUET_PUSHDOWN_DESIGN.md
@@ -399,24 +399,43 @@ Execution:
 
 ```go
 type ParquetPushdownRequest struct {
-    Table       string
-    SnapshotId  int64
-    Files       []string
-    Columns     []string
-    Predicate   []byte
-    VectorQuery *VectorQuery
-    Limit       int
+    Table          string
+    SnapshotId     int64
+    Files          []string
+    Columns        []string
+    PredicateKind  PredicateKind // SUBSTRAIT or ICEBERG_EXPRESSION
+    Predicate      []byte        // serialized per PredicateKind
+    VectorQuery    *VectorQuery
+    Limit          int
 }
 
+type PredicateKind int32
+
+const (
+    PredicateUnspecified PredicateKind = 0
+    PredicateSubstrait   PredicateKind = 1 // Substrait ExtendedExpression protobuf
+    PredicateIceberg     PredicateKind = 2 // Iceberg Expression JSON
+)
+
+type VectorMetric int32
+
+const (
+    MetricL2     VectorMetric = 0
+    MetricCosine VectorMetric = 1
+    MetricDot    VectorMetric = 2
+)
+
 type VectorQuery struct {
     Column string
     Vector []float32
-    Metric string // l2, cosine, dot
+    Metric VectorMetric
     TopK   int
     NProbe int
 }
 ```
 
+v1 implementations should accept Substrait as the canonical wire format. Iceberg Expression JSON is supported as a convenience for connectors that already produce it.
+
 ### Pushdown Response
 
 ```go