KMeans

SQL function: cuvs_kmeans

Official cuVS reference: C API

K-means clustering assignments for dense vector rows.

Quickstart

The call below expects the registered relation input_vectors (the input role), passed as a parenthesized SELECT subquery. Substitute your own relations and column names.

SELECT id, cluster_id
FROM cuvs_kmeans(
  input => (SELECT id, d0, d1 FROM input_vectors),
  n_clusters => 8
)
ORDER BY row_ordinal;

Inputs

Each relation argument is a parenthesized SELECT subquery that the planner keeps as a real child; metadata validation resolves a registered table or view for the same role instead. See Vector Inputs for the relation identity rules and the ID, dense-vector type, null, finite-value, and runtime-dimension contract.

Role	Required	Validation reference	Description
input	yes	table	Dense-vector rows consumed by this operation.

Vector element types

Element type	Valid metrics
Float32	l2_expanded, l2_sqrt_expanded
Float64	l2_expanded, l2_sqrt_expanded

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
n_clusters	integer	yes	Number of clusters fitted for this one statement.
metric	enum ("l2_expanded", "l2_sqrt_expanded")	no	L2 distance form used while fitting and assigning the current input relation.
max_iter	integer	no	Maximum fitting iterations for this invocation.
tol	number	no	Non-negative convergence tolerance used by the fitted model.
n_init	integer	no	Number of initialization attempts performed within this call.
init	enum ("kmeans++", "random")	no	Centroid initialization strategy for this fitted model.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
init	no	string	"kmeans++"	one of "kmeans++", "random"	Centroid initialization strategy for this fitted model.
max_iter	no	integer	100	minimum 1; maximum 2147483647	Maximum fitting iterations for this invocation.
metric	no	string	"l2_expanded"	one of "l2_expanded", "l2_sqrt_expanded"	L2 distance form used while fitting and assigning the current input relation. Supported element/metric combinations: Float32: l2_expanded, l2_sqrt_expanded; Float64: l2_expanded, l2_sqrt_expanded.
n_clusters	yes	integer	No default	minimum 1; maximum 2147483647	Number of clusters fitted for this one statement.
n_init	no	integer	1	minimum 1; maximum 2147483647	Number of initialization attempts performed within this call.
tol	no	number	0.0001	minimum 0	Non-negative convergence tolerance used by the fitted model.

Vector binding shapes

Each relation subquery must project a non-null id field followed by either one or more non-null feature fields of a supported element type (Float32, Float64) or one non-null list vector field named vector.

For wide vectors, the projection order defines the feature dimensions. A list vector relation must contain no feature field beside id and vector.

Output

Column	Type	Nullable	Description
row_ordinal	UInt64	no	Zero-based ordinal of the evaluated input row; it disambiguates duplicate IDs.
id	same_as_input.id	no	Logical ID copied from the input relation.
cluster_id	Int32	no	Query-local numeric assignment label, not a stable business or topic identifier.

Concrete schemas are call-specific. Run gpu_validate_call against registered relations to inspect the output schema after the actual ID types and literal options are validated.

Limits

• Validation resolves named tables or views and reads schemas only; it does not execute relation scans or GPU work.
• Execution relation arguments require parenthesized subqueries; dry-run validation accepts registered named relations only.
• Fits a model and returns assignments within one statement; it does not return a reusable model, centroids, or inertia.
• The evaluated input must be non-empty and n_clusters must not exceed its row count.
• cluster_id values are query-local labels. Do not attach permanent business meaning to their numeric values.

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.