PCA

SQL function: cuvs_pca

Official cuVS reference: C API

Principal-component analysis transform 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, pc_0, pc_1
FROM cuvs_pca(
  input => (SELECT id, d0, d1 FROM input_vectors),
  n_components => 2
)
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	Not applicable

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
n_components	integer	yes	Number of principal-component columns emitted as pc_0 through pc_<n_components - 1>.
whiten	boolean	no	Whether the query-local transformed components are whitened.
solver	enum ("cov_eig_dq", "cov_eig_jacobi")	no	Covariance eigensolver used for this fit-transform call.
tol	number	no	Non-negative eigensolver tolerance.
n_iterations	integer	no	Maximum eigensolver iterations for this invocation.
flip_signs_based_on_u	boolean	no	Whether cuVS applies its U-based component-sign convention.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
flip_signs_based_on_u	no	boolean	false		Whether cuVS applies its U-based component-sign convention.
n_components	yes	integer	No default	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

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) 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.
pc_<index>	Float32	no	One transformed principal-component value; the field count is set by the literal n_components option. The output contains n_components such columns, pc_0 through pc_&lt;n_components - 1&gt;.

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 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.

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