PCA

SQL function: cuvs_pca

Principal-component analysis transform for dense vector rows.

Signature

cuvs_pca((input relation subquery), options_json)

Quickstart

SELECT id, pc_0, pc_1
FROM cuvs_pca(
  (SELECT item_id, d0, d1 FROM input_vectors),
  '{"input":{"id":"item_id","vector":{"columns":["d0","d1"]}},"n_components":2}'
)
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
flip_signs_based_on_u	no	boolean	false		Whether cuVS applies its U-based component-sign convention.
input	yes	object			Names the input ID column and one dense-vector binding shape.
n_components	yes	integer		minimum 1; maximum 2147483647	Number of principal-component columns emitted as pc_0 through pc_<n_components - 1>.
n_iterations	no	integer	15	minimum 1; maximum 2147483647	Maximum eigensolver iterations for this invocation.
solver	no	string	"cov_eig_dq"	one of "cov_eig_dq", "cov_eig_jacobi"	Covariance eigensolver used for this fit-transform call.
tol	no	number	0	minimum 0	Non-negative eigensolver tolerance.
whiten	no	boolean	false		Whether the query-local transformed components are whitened.

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.
pc_<index>	Float32	no	One transformed principal-component value; the field count is set by the literal n_components option.; repeats: n_components

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 and transforms the evaluated input in one statement; it does not return a reusable transform, components, or explained-variance metadata.
• The evaluated input needs at least two rows and two dimensions, and n_components must not exceed the evaluated dimension.
• Component sign orientation is not a semantic label. The output schema changes with the literal n_components option.

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_pca',
  '{"options":{"input":{"id":"item_id","vector":{"columns":["d0","d1"]}},"n_components":2},"relations":{"input":{"table":"input_vectors"}},"schema_version":1}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.