Bound Expressions Serde

Author: sfc-gh-prsingh

api/src/main/java/org/apache/iceberg/expressions/Expressions.java

@@ -102,6 +102,38 @@ public static <T> UnboundTerm<T> truncate(String name, int width) {
     return new UnboundTransform<>(ref(name), Transforms.truncate(width));
   }
 
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> bucket(NamedReference<S> ref, int numBuckets) {
+    Transform<S, T> transform = (Transform<S, T>) Transforms.bucket(numBuckets);
+    return new UnboundTransform<>(ref, transform);
+  }
+
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> year(NamedReference<S> ref) {
+    return new UnboundTransform<>(ref, (Transform<S, T>) Transforms.year());
+  }
+
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> month(NamedReference<S> ref) {
+    return new UnboundTransform<>(ref, (Transform<S, T>) Transforms.month());
+  }
+
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> day(NamedReference<S> ref) {
+    return new UnboundTransform<>(ref, (Transform<S, T>) Transforms.day());
+  }
+
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> hour(NamedReference<S> ref) {
+    return new UnboundTransform<>(ref, (Transform<S, T>) Transforms.hour());
+  }
+
+  @SuppressWarnings("unchecked")
+  public static <S, T> UnboundTerm<T> truncate(NamedReference<S> ref, int width) {
+    Transform<S, T> transform = (Transform<S, T>) Transforms.truncate(width);
+    return new UnboundTransform<>(ref, transform);
+  }
+
   public static <T> UnboundTerm<T> extract(String name, String path, String type) {
     return new UnboundExtract<>(ref(name), path, type);
   }
@@ -305,6 +337,21 @@ public static <T> NamedReference<T> ref(String name) {
     return new NamedReference<>(name);
   }
 
+  /**
+   * Constructs a resolved reference for a given column.
+   *
+   * <p>The following are equivalent: equals("a", 5) and if a fieldId is 1 and equals(ref("a", 1),
+   * 5).
+   *
+   * @param name a column name
+   * @param fieldId the field ID of the column
+   * @param <T> the Java type of this reference
+   * @return a named reference
+   */
+  static <T> IDReference<T> ref(String name, int fieldId) {
+    return new IDReference<>(name, fieldId);
+  }
+
   /**
    * Constructs a transform expression for a given column.
    *

api/src/main/java/org/apache/iceberg/expressions/IDReference.java

@@ -0,0 +1,56 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.expressions;
+
+import org.apache.iceberg.Schema;
+import org.apache.iceberg.exceptions.ValidationException;
+import org.apache.iceberg.types.Types;
+
+/**
+ * A reference to a field by ID rather than name. This extends NamedReference because it is a more
+ * specific in that the name has already been resolved to a field ID. Because the name has been
+ * resolved, the name is informational.
+ */
+public class IDReference<T> extends NamedReference<T> {
+  private final int id;
+
+  public IDReference(String name, int id) {
+    super(name);
+    this.id = id;
+  }
+
+  public int id() {
+    return id;
+  }
+
+  @Override
+  public BoundReference<T> bind(Types.StructType struct, boolean caseSensitive) {
+    Schema schema = struct.asSchema();
+    Types.NestedField field = schema.findField(id);
+    ValidationException.check(
+        field != null, "Cannot find field by id %s in struct: %s", id, schema.asStruct());
+
+    return new BoundReference<>(field, schema.accessorForField(field.fieldId()), name());
+  }
+
+  @Override
+  public String toString() {
+    return String.format("ref(name=\"%s\", id=\"%s\")", name(), id);
+  }
+}

api/src/main/java/org/apache/iceberg/expressions/UnboundTransform.java

@@ -50,11 +50,10 @@ public BoundTransform<S, T> bind(Types.StructType struct, boolean caseSensitive)
           "Cannot bind: %s cannot transform %s values from '%s'",
           transform,
           boundRef.type(),
-          ref.name());
+          ref);
     } catch (IllegalArgumentException e) {
       throw new ValidationException(
-          "Cannot bind: %s cannot transform %s values from '%s'",
-          transform, boundRef.type(), ref.name());
+          "Cannot bind: %s cannot transform %s values from '%s'", transform, boundRef.type(), ref);
     }
 
     return new BoundTransform<>(boundRef, transform);

api/src/test/java/org/apache/iceberg/expressions/TestExpressionSerialization.java

@@ -61,7 +61,17 @@ public void testExpressions() throws Exception {
           Expressions.notIn("s", "abc", "xyz").bind(schema.asStruct()),
           Expressions.isNull("a").bind(schema.asStruct()),
           Expressions.startsWith("s", "abc").bind(schema.asStruct()),
-          Expressions.notStartsWith("s", "xyz").bind(schema.asStruct())
+          Expressions.notStartsWith("s", "xyz").bind(schema.asStruct()),
+          // IDReference tests
+          Expressions.equal(Expressions.ref("a", 34), 5),
+          Expressions.in(Expressions.ref("s", 35), "abc", "xyz"),
+          Expressions.notNull(Expressions.ref("a", 34)),
+          Expressions.isNull(Expressions.ref("a", 34)),
+          Expressions.startsWith(Expressions.ref("s", 35), "test"),
+          // IDReference bound tests
+          Expressions.equal(Expressions.ref("a", 34), 5).bind(schema.asStruct()),
+          Expressions.in(Expressions.ref("s", 35), "abc", "xyz").bind(schema.asStruct()),
+          Expressions.notNull(Expressions.ref("a", 34)).bind(schema.asStruct())
         };
 
     for (Expression expression : expressions) {
@@ -196,6 +206,15 @@ private static boolean equals(Reference<?> left, Reference<?> right) {
       NamedReference rref = (NamedReference) right;
 
       return lref.name().equals(rref.name());
+    } else if (left instanceof IDReference) {
+      if (!(right instanceof IDReference)) {
+        return false;
+      }
+
+      IDReference lref = (IDReference) left;
+      IDReference rref = (IDReference) right;
+
+      return lref.id() == rref.id() && lref.name().equals(rref.name());
     } else if (left instanceof BoundReference) {
       if (!(right instanceof BoundReference)) {
         return false;

api/src/test/java/org/apache/iceberg/expressions/TestIDReference.java

@@ -0,0 +1,132 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.iceberg.expressions;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.apache.iceberg.Schema;
+import org.apache.iceberg.exceptions.ValidationException;
+import org.apache.iceberg.types.Types;
+import org.junit.jupiter.api.Test;
+
+public class TestIDReference {
+  private static final Schema SCHEMA =
+      new Schema(
+          Types.NestedField.optional(34, "a", Types.IntegerType.get()),
+          Types.NestedField.required(35, "s", Types.StringType.get()));
+
+  @Test
+  public void testIDReferenceEquality() {
+    IDReference<Integer> ref1 = new IDReference<>("a", 34);
+    IDReference<Integer> ref2 = new IDReference<>("a", 34);
+    IDReference<Integer> ref3 = new IDReference<>("b", 34);
+    IDReference<Integer> ref4 = new IDReference<>("a", 35);
+
+    // Equal references
+    assertThat(ref1.id()).isEqualTo(ref2.id());
+    assertThat(ref1.name()).isEqualTo(ref2.name());
+
+    // Different names, same fieldId
+    assertThat(ref1.id()).isEqualTo(ref3.id());
+    assertThat(ref1.name()).isNotEqualTo(ref3.name());
+
+    // Same name, different fieldId
+    assertThat(ref1).isNotEqualTo(ref4);
+  }
+
+  @Test
+  public void testIDReferenceBind() {
+    IDReference<Integer> ref = new IDReference<>("a", 34);
+    BoundReference<Integer> bound = ref.bind(SCHEMA.asStruct(), true);
+
+    assertThat(bound).isInstanceOf(BoundReference.class);
+    assertThat(bound.fieldId()).isEqualTo(34);
+    assertThat(bound.name()).isEqualTo("a");
+    assertThat(bound.type()).isEqualTo(Types.IntegerType.get());
+  }
+
+  @Test
+  public void testIDReferenceBindIgnoresCaseSensitivity() {
+    IDReference<Integer> ref = new IDReference<>("A", 34);
+
+    // Should work regardless of case sensitivity since we use fieldId
+    BoundReference<Integer> bound1 = ref.bind(SCHEMA.asStruct(), true);
+    BoundReference<Integer> bound2 = ref.bind(SCHEMA.asStruct(), false);
+
+    assertThat(bound1).isInstanceOf(BoundReference.class);
+    assertThat(bound2).isInstanceOf(BoundReference.class);
+    assertThat(bound1.fieldId()).isEqualTo(34);
+    assertThat(bound2.fieldId()).isEqualTo(34);
+  }
+
+  @Test
+  public void testIDReferenceBindWithInvalidId() {
+    IDReference<Integer> ref = new IDReference<>("invalid", 999);
+
+    assertThatThrownBy(() -> ref.bind(SCHEMA.asStruct(), true))
+        .isInstanceOf(ValidationException.class)
+        .hasMessageContaining(
+            "Cannot find field by id 999 in struct: struct<34: a: optional int, 35: s: required string>");
+  }
+
+  @Test
+  public void testIDReferenceRef() {
+    IDReference<Integer> ref = new IDReference<>("a", 34);
+    NamedReference<?> namedRef = ref.ref();
+
+    assertThat(namedRef.name()).isEqualTo("a");
+  }
+
+  @Test
+  public void testResolvedReferenceToString() {
+    IDReference<Integer> ref = new IDReference<>("a", 34);
+
+    assertThat(ref.toString()).isEqualTo("ref(name=\"a\", id=\"34\")");
+  }
+
+  @Test
+  public void testIDReferenceExpressionIntegration() {
+    // Test that IDReference works in expression predicates
+    UnboundPredicate<?> expr = Expressions.equal(Expressions.ref("a", 34), 5);
+    assertThat(expr).isInstanceOf(UnboundPredicate.class);
+
+    assertThat(expr.term()).isInstanceOf(IDReference.class);
+
+    IDReference<?> resolvedRef = (IDReference<?>) expr.term();
+    assertThat(resolvedRef.name()).isEqualTo("a");
+    assertThat(resolvedRef.id()).isEqualTo(34);
+  }
+
+  @Test
+  public void testIDReferenceUnbind() {
+    // Test that unbinding a bound reference returns a NamedReference for compatibility
+    Expression expr = Expressions.equal(Expressions.ref("a", 34), 5);
+    Expression boundExpr = Binder.bind(SCHEMA.asStruct(), expr, true);
+
+    assertThat(boundExpr).isInstanceOf(BoundPredicate.class);
+    BoundPredicate<?> boundPred = (BoundPredicate<?>) boundExpr;
+
+    UnboundTerm<?> unbound = ExpressionUtil.unbind(boundPred.term());
+    assertThat(unbound).isInstanceOf(NamedReference.class);
+
+    NamedReference<?> namedRef = (NamedReference<?>) unbound;
+    assertThat(namedRef.name()).isEqualTo("a");
+  }
+}