Skip to content

feat: add inner_product scalar function#21861

Merged
alamb merged 4 commits intoapache:mainfrom
crm26:feat/inner-product
May 3, 2026
Merged

feat: add inner_product scalar function#21861
alamb merged 4 commits intoapache:mainfrom
crm26:feat/inner-product

Conversation

@crm26
Copy link
Copy Markdown
Contributor

@crm26 crm26 commented Apr 26, 2026

Which issue does this PR close?

Part of #21536 — split of #21371 into one-function-per-PR.

Rationale for this change

Adds inner_product(array1, array2) — the dot product of two equal-length numeric arrays, returning Float64. Computed as sum(array1[i] * array2[i]).

What changes are included in this PR?

Mirrors the structural pattern of merged #21542 (cosine_distance):

  • Same coerce_types for List/LargeList/FixedSizeList of any numeric inner type, with widening to LargeList when any input is LargeList (per the fix: array_concat widens container variant for mixed List/LargeList inputs #21704 pattern)
  • Same NULL semantics: bare NULLNULL, NULL row → NULL, NULL element in list → NULL
  • Same Arrow-idiomatic implementation: single as_float64_array(list_array.values()) downcast, slice by value_offsets(), iterate via ScalarBuffer<f64>
  • No alias, no shared module — standalone, inline math

The arithmetic is the only semantic divergence from cosine_distance:

  • dot += a*b (no magnitude or normalization)
  • Empty arrays return 0.0 (sum of empty set), not NULL
  • No zero-magnitude special case (inner_product([0,0], [1,2]) returns 0, which is well-defined for inner product)

Are these changes tested?

Yes. SLT covers:

  • Orthogonal, identical, opposite, general non-trivial vectors
  • Single zero vector, both zero vectors
  • Bare NULL in either or both positions
  • NULL element inside a list (returns NULL for that row)
  • Mismatched lengths (error)
  • LargeList inputs
  • Mixed (List, LargeList) in both orders
  • (FixedSizeList, FixedSizeList) and (FixedSizeList, LargeList)
  • Float32 and Int64 inner type coercion
  • Multi-row query with NULL row propagation
  • Empty arrays (returns 0)
  • No-args error
  • Return-type assertion (Float64)

Are there any user-facing changes?

New scalar function inner_product, documented in docs/source/user-guide/sql/scalar_functions.md.

@github-actions github-actions Bot added documentation Improvements or additions to documentation sqllogictest SQL Logic Tests (.slt) functions Changes to functions implementation labels Apr 26, 2026
)]
#[derive(Debug, PartialEq, Eq, Hash)]
pub struct InnerProduct {
signature: Signature,
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add a dot_product alias?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @Jefffrey — added dot_product as an alias in ef9895005, with SLT coverage for both a constant-args and a multi-row-with-NULL case. Doc regen picked up the alias automatically (#### Aliases block under inner_product, plus a top-level ### dot_product Alias of stub).

@alamb
Copy link
Copy Markdown
Contributor

alamb commented Apr 27, 2026

I had a thought about adding new functions:

@crm26 crm26 force-pushed the feat/inner-product branch from 8c05259 to ef98950 Compare April 29, 2026 21:45
@Jefffrey
Copy link
Copy Markdown
Contributor

Jefffrey commented May 2, 2026

I think once merge conflict is fixed we should be good to merge this

@alamb
Copy link
Copy Markdown
Contributor

alamb commented May 3, 2026

I merged up to resolve a conflict

@alamb alamb enabled auto-merge May 3, 2026 12:00
@alamb
Copy link
Copy Markdown
Contributor

alamb commented May 3, 2026

Thanks @crm26 and @Jefffrey

@alamb alamb added this pull request to the merge queue May 3, 2026
Merged via the queue into apache:main with commit 9a29e33 May 3, 2026
36 checks passed
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.

3 participants