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.
Vector element types
Feature values must be Float32.
Arguments and options
Scalar SQL arguments
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
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 ← / →.
3,225 of 3,225 points match
- EMBER ID
- 20000000
- Week
- 0
- Cluster
- 5
- Membership
- 1.000
058f63432dd8f679aef17b6fa16dd513273f10d8512f9897fa850585ea1d6d02Saved 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.