Skip to content

feat: add array_avg scalar function#23168

Open
crm26 wants to merge 1 commit into
apache:mainfrom
crm26:feat/array-avg
Open

feat: add array_avg scalar function#23168
crm26 wants to merge 1 commit into
apache:mainfrom
crm26:feat/array-avg

Conversation

@crm26

@crm26 crm26 commented Jun 24, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds array_avg, the last function from the split-PR pipeline tracked in #21536.

Computes the arithmetic mean (sum divided by count) of the elements of a numeric array, returned as Float64. Templated from the merged array_sum (#22542) with the same SQL aggregate NULL conventions; sibling of array_sum, array_product, array_subtract, array_add, array_scale, and array_normalize.

Semantics

NULL semantics — SQL aggregate convention (deliberate divergence from binary-op siblings):

  • NULL row → NULL row out
  • NULL elements are skipped from BOTH the sum and the count, matching PostgreSQL AVG, DuckDB list_avg, Spark aggregate. So array_avg([1, NULL, 3]) = (1+3) / 2 = 2, not (1+3) / 3.
  • All-NULL row → NULL out (matches AVG(...) over an all-NULL column)
  • Empty array → NULL (matches sibling array_sum feat: add array_sum scalar function #22542 and array_product Add array_product UDF #22703, PostgreSQL, DuckDB list_avg, SQL Standard AVG-of-empty-set)

Type coercion:

  • Inner numeric types (Float32, Int*, UInt*) coerced to Float64. Integer-arg literals are coerced too.
  • Return type is always Float64 (since avg of integers can be non-integer).

List shapes supported: List, LargeList, FixedSizeList.

Alias: list_avg (matches the list_sum / list_product pattern).

Test coverage

SLT (array_avg.slt) covers:

  • Happy paths (basic, single element, negative values, cancelling positive/negative, non-integer mean [1,2] → 1.5)
  • All NULL shapes: bare NULL row, NULL elements skipped, single non-NULL among NULLs, all-NULL array
  • Empty array → NULL
  • All 3 list shapes (List, LargeList, FixedSizeList)
  • Float32, Int64 inner types, integer literals, integer mean that is non-integer
  • Multi-row mix
  • Error paths (non-list input, zero args, two args)
  • Return type assertion (Float64)
  • list_avg alias

Closes

The last open slot in #21536 — completes the 8-function split-PR pipeline from the originally-too-big PRs #21371 / #21376.

Adds array_avg, the final function from the split-PR pipeline
in apache#21536. Computes the arithmetic mean of the elements of a
numeric array, returned as Float64. Templated from the merged
array_sum (apache#22542) with the same SQL aggregate NULL conventions.

Semantics:
- NULL elements are skipped (per SQL aggregate convention). Both
  the sum AND the count exclude NULL elements. So
  array_avg([1, NULL, 3]) = (1 + 3) / 2 = 2 — not (1 + 3) / 3.
- NULL row → NULL row out.
- All-NULL array → NULL.
- Empty array → NULL (matches PostgreSQL AVG, DuckDB list_avg, and
  the SQL Standard SUM/AVG-of-empty-set rule. Same behaviour as the
  merged array_sum, array_product siblings).
- Return type is always Float64.
- Inner numeric types (Float32, Int*, UInt*) are coerced to Float64.
- Supported list shapes: List, LargeList, FixedSizeList.
- Alias: list_avg (matches the list_sum / list_product naming).

SLT coverage: basic positive/negative/cancel cases, single element,
non-integer mean, empty array, bare NULL, NULL elements skipped,
single non-NULL among NULL, all-NULL row, all 3 list shapes, float
and integer inner types, integer mean that is non-integer, multi-row
mix, error paths (non-list input, zero args, two args), return type
assertion, and the list_avg alias.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@github-actions github-actions Bot added documentation Improvements or additions to documentation sqllogictest SQL Logic Tests (.slt) functions Changes to functions implementation labels Jun 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation functions Changes to functions implementation sqllogictest SQL Logic Tests (.slt)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants