KMeans

SQL function: cuvs_kmeans

K-means clustering assignments for dense vector rows.

Signature

cuvs_kmeans((input relation subquery), options_json)

Quickstart

SELECT id, cluster_id
FROM cuvs_kmeans(
  (SELECT item_id, d0, d1 FROM input_vectors),
  '{"input":{"id":"item_id","vector":{"columns":["d0","d1"]}},"n_clusters":8}'
)
ORDER BY row_ordinal;

Relation inputs

Every execution relation argument is a parenthesized SELECT subquery. The planner retains that relation as a real logical and physical child; a bare table identifier or quoted table-name string is rejected. Metadata validation instead uses a registered named table or view in its relation envelope.

Role	Required	Validation reference	Description
input	yes	table	Dense-vector rows consumed by the fit-and-transform operation.

See Vector Inputs for the ID and dense-vector type, null, finite-value, and runtime-dimension contract.

Scalar arguments & JSON options

Scalar SQL arguments

Argument	Type	Required	Description
options_json	JSON string literal	yes	cuVS operation options and relation-column bindings

JSON options

Option	Required	JSON shape	Default	Constraints	Description
init	no	string	"kmeans++"	one of "kmeans++", "random"	Centroid initialization strategy for this fitted model.
input	yes	object			Names the input ID column and one dense-vector binding shape.
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.
n_clusters	yes	integer		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

id: Non-null logical row ID column. IDs may repeat; result ordinals disambiguate physical rows.

Shape	JSON	Contract
Wide Float32 columns	{"vector":{"columns":["d0","d1"]}}	Ordered, unique non-null Float32 feature columns; order defines vector dimensions.
List column	{"vector":{"column":"embedding"}}	One non-null FixedSizeList<Float32, D>, List<Float32>, or LargeList<Float32> column.

Choose exactly one dense-vector binding shape.

Output schema

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.

Limitations & lifecycle

• Validation resolves named tables or views and reads schemas only; it does not execute relation scans or GPU work.
• Bounded cuVS execution is unavailable until the lower-level peak-memory preflight contract exists.
• 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.

Validate before running

Validation checks registered relation metadata, bindings, dtypes, and options without scanning rows or touching the GPU:

SELECT * FROM gpu_validate_call(
  'cuvs_kmeans',
  '{"options":{"input":{"id":"item_id","vector":{"columns":["d0","d1"]}},"n_clusters":8},"relations":{"input":{"table":"input_vectors"}},"schema_version":1}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.