hierarchicalKMeans

Introduced in: v26.8.0

Trains up to k cluster centroids from the aggregated vectors using hierarchical k-means and returns them as Array(Array(Float32)). Fewer than k are returned only when the input has fewer than k rows, since a row can yield at most one centroid; repeated points still yield k. Distance is squared L2; pass cosine_distance = 1 to renormalize the centroids to unit length after each iteration, which makes the same centroids an exact cosine/inner-product quantizer.

Syntax

hierarchicalKMeans(k[, branching[, max_iter[, sample_cap[, seed[, cosine_distance]]]]])(vec)

Arguments

• vec — Vectors to cluster. Every row must have the same dimension, and every coordinate must be finite. Widths other than Float32 are converted to Float32, which is what the training kernels use. Array(Float32) or Array(Float64) or Array(BFloat16)

Returned value

An array of up to k centroids, capped by the number of input rows. Array(Array(Float32))

Examples

Basic usage

SELECT length(hierarchicalKMeans(4)(vec)) FROM (SELECT [toFloat32(number % 4), toFloat32(number % 4)] AS vec FROM numbers(100))

4

Well-separated clusters

SELECT arraySort(hierarchicalKMeans(4)(vec)) FROM (SELECT [toFloat32(intDiv(number, 25)) * 100, toFloat32(0)] AS vec FROM numbers(100))

[[0,0],[100,0],[200,0],[300,0]]