[platinumhamburg]

Purpose

Fixes #4945.

The aggregation documentation and AggFunctions.FIRST_VALUE() Javadoc promise that an initial NULL is retained, but the implementation treats NULL as unset and keeps the first non-null value. For example, NULL -> 10 -> 20 produces 10.

Document this existing behavior so that fields omitted from an initial partial update can still receive their first non-null value in a later update. An unset field and an explicitly written NULL share the same null accumulator.

Brief change log

• Describe FIRST_VALUE as retaining the first non-null value in the user documentation and API Javadoc.
• State that its behavior matches FIRST_VALUE_IGNORE_NULLS.
• Explain the NULL sequence and partial-update behavior in the user documentation.

Tests

Passed on JDK 11:

./mvnw -pl fluss-server -am verify -Dtest=FieldAggregatorParameterizedTest,AggregateRowMergerTest,AggregationContextTest -Dsurefire.failIfNoSpecifiedTests=false

Includes the existing aggregation tests, Spotless, Checkstyle, and license checks. The complete repository test suite was not run.

API and Format

No runtime behavior, API signature, or storage format changes. The Javadoc now describes the existing NULL handling.

Documentation

Update the aggregation merge engine's first_value section and AggFunctions.FIRST_VALUE() Javadoc.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.

[polyzos]

@platinumhamburg, I think this breaks a more common case: with partial updates, a column that wasn't written yet also reaches agg() with a null accumulator. With this change it then stays null forever.

I used a test: a partial write of (id, other) followed by a partial write of (id, value=10) gives value = 10 on main and null with this PR.

Since "first value was null" and "not written yet" can't be told apart without extra state per field, should we keep the current behavior and update the docs to say FIRST_VALUE treats null as not set? WDYT?

[platinumhamburg]

@polyzos Thanks for catching this. You’re right: I overlooked the distinction between the first write to a row and the first write to an individual field. The added partial-update tests always included the value column, so they missed the case you described.

Given that both “not written yet” and “explicitly written as NULL” are represented by a null accumulator, preserving the existing partial-update behavior is the better tradeoff. I agree we should keep the current implementation and document that FIRST_VALUE treats NULL as unset, effectively matching FIRST_VALUE_IGNORE_NULLS.

This means accepting a semantic difference from Paimon until we have a practical way to preserve that distinction across writes and recovery. I’ll update the issue and rework this PR as a documentation correction.