v0.51.10-SNAPSHOT

Release Note: Data Consistency Enhancement for Struct Handling (v0.51.10-SNAPSHOT)

---

Background

The Tunnel SDK transmits data to the server based on column indices (not column names). This requires users to construct Record objects strictly following the column order defined in the TableSchema bound to the current session. However, this approach introduces complexity when building nested Struct types, as field order mismatches can lead to data inconsistency.

---

Solutions

1. ReorderableStruct for Flexible Struct Construction

Problem: Directly constructing Struct via field names may result in order mismatches with the target schema.

Solution:
Introducing ReorderableStruct (implements Struct interface) with the following features:

• Constructor:

  public ReorderableStruct(StructTypeInfo type)

• Field Setting Methods:

  public void setFieldValue(String fieldName, Object value) // Set by field name (case-insensitive)
  public void setFieldValue(int index, Object value)        // Set by index

• Example:

  ReorderableStruct person = new ReorderableStruct(personStructType);
  person.setFieldValue("money", 1234L); // Field order irrelevant
  person.setFieldValue("age", 25);
  person.setFieldValue("name", "Jason");

• Behavior:
  Ensures internal field order aligns with the schema, even if fields are set out-of-order.

---

2. ReorderableRecord for Automatic Schema Alignment

Problem: Structs constructed outside the SDK may have field orders incompatible with the target schema.

Solution:
Introducing ReorderableRecord (extends ArrayRecord), which automatically reorders Struct fields (including nested types like Array<Struct> or Map<Struct>) to match the schema:

• Usage:

  TableTunnel.StreamUploadSession uploadSession;
  Struct upstreamData;
  Record record = new ReorderableRecord(uploadSession.getSchema()); // Bind to schema
  record.set("struct", upstreamData); // Automatic reordering

• Performance Note:
  Reordering incurs additional computational overhead. Use this approach only when schema alignment is uncertain.

---

Key Constraints

The reorder method enforces strict schema consistency:

• Field names, data types, and nested structures (including maps/arrays) must exactly match between the Struct and target schema (order-independent).
• Exceptions:
  • IllegalArgumentException is thrown for mismatches (e.g., missing fields, type conflicts, or nested schema inconsistencies).