Skip to main content

PCA

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

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 an operator child. Metadata validation resolves a registered table or view for the same role. See Vector Inputs for the relation identity rules and the ID, dense-vector type, null, finite-value, and runtime-dimension contract.

RoleRequiredValidation referenceDescription
inputyestableDense-vector rows consumed by this operation.

Vector element types​

Feature values must be Float32.

Arguments and options​

Scalar SQL arguments​

ArgumentTypeRequiredDefaultConstraintsDescription
flip_signs_based_on_ubooleannofalseWhether cuVS applies its U-based component-sign convention.
n_componentsintegeryesNo defaultminimum 1; maximum 2147483647Number of principal-component columns emitted as pc_0 through pc_<n_components - 1>.
n_iterationsintegerno15minimum 1; maximum 2147483647Maximum eigensolver iterations for this invocation.
solverstringno"cov_eig_dq"one of "cov_eig_dq", "cov_eig_jacobi"Covariance eigensolver used for this fit-transform call.
tolnumberno0minimum 0Non-negative eigensolver tolerance.
whitenbooleannofalseWhether the query-local transformed components are whitened.

Vector binding shapes​

Each relation subquery must project an id field followed by either one or more feature fields of a supported element type (Float32) or one list field of a supported element type, under any name.

For wide vectors, the projection order defines the feature dimensions. A list vector relation must contain no feature field beside id and its list field. Nullable field types are accepted. A null ID, feature value, list row, or list element fails the query.

Output​

ColumnTypeNullableDescription
row_ordinalUInt64noZero-based ordinal of the evaluated input row; it disambiguates duplicate IDs. Follows the input's top-level ORDER BY on output columns; unspecified without one.
idsame_as_input.idnoLogical ID copied from the input relation.
pc_<index>Float32noOne 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;.

The output schema depends on the call. Run gpu_validate_call against registered relations to inspect the schema that the validated ID types and literal options produce.

Examples​

This example uses the EMBER2024 demo dataset.

How much histogram variation remains visible in two PCA dimensions?​

The query returns two PCA coordinates for all 3,225 Win32 challenge rows. The first two centered components retain 71.187% of the variance. Labels and family names are joined after PCA for inspection; the PCA input consists only of row IDs and histograms.

A separate centered-Gram comparison against the CPU reference passed with a relative Frobenius error of about 4.7e-7 against a 0.0001 tolerance. The SQL result contains 3,225 rows and recorded native disposition.

For the 16-component reduction followed by HDBSCAN, see the full PCA and HDBSCAN SQL example.

-- Project all Win32 challenge histograms to two principal components, preserving
-- source ID, label, and week for review and comparison with TSVD and UMAP.
SELECT p.id,
p.pc_0,
p.pc_1,
v.label,
m.week_id,
m.sha256,
m.family
FROM cuvs_pca(
input => (
SELECT r.id, r.histogram AS vector
FROM ember_research_vectors_challenge r
JOIN ember_metadata_challenge m ON m.id = r.id
WHERE r.split = 'challenge' AND m.file_type = 'Win32'
ORDER BY r.id
),
n_components => 2
) p
JOIN ember_research_vectors_challenge v ON v.id = p.id AND v.split = 'challenge'
JOIN ember_metadata_challenge m ON m.id = v.id
ORDER BY p.row_ordinal;

Hover or click a dot, or focus the map and press ← / →.

Clusters

3,225 of 3,225 points match

doenerium
EMBER ID
20000000
Week
0
Cluster
5
Membership
1.000
058f63432dd8f679aef17b6fa16dd513273f10d8512f9897fa850585ea1d6d02
All 3,225 saved challenge Win32 rows are included. Projection and cluster values come from saved SQL results. Switching the projection or changing a filter does not rerun SQL. Family is post-fit metadata. HDBSCAN clusters were fitted to PCA-16 coordinates, while this map can display PCA-2, TSVD-2, or UMAP-2. Cluster IDs are local to this capture. Coordinates are visual projections with no calibrated malware-risk interpretation. Noise (-1) records rows left unassigned under these HDBSCAN parameters. That label alone carries no novelty classification. Download the saved capture data.
Saved SQL capture IDs
  • PCA-2: 65e2e2b8-9734-4623-966b-88a7925a0ca4
  • TSVD-2: ba1ddc3c-65cb-43b8-a150-2bef95a41549
  • UMAP-2: da5ef3a6-7158-4d34-8f69-23c12e92bb63
  • PCA-16 plus HDBSCAN: 9cdfba96-0299-4220-861c-fef49bf1a52d

Limits​

  • Fits and transforms the evaluated input in one call; 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.