UMAP
UDTF: cuml_umap
Official cuML reference: Python API
cuML UMAP fits a deterministic, query-local manifold embedding for dense feature rows.
Quickstart
Register the relations referenced by the parenthesized SELECT clauses below. For metadata validation, the descriptor names input_vectors.
SELECT id, dim_0, dim_1
FROM cuml_umap(
input => (SELECT id, d0, d1 FROM t),
n_neighbors => 5
)
ORDER BY row_ordinal;
Inputs
Each relation argument is a parenthesized SELECT subquery. Metadata validation resolves a registered table or view for the same role without scanning its rows. See ML Inputs for the ID, feature element, Float64 narrowing, null, finite-value, and runtime-dimension contract.
Vector element types
Feature values must be Float32 or Float64.
Arguments and options
Scalar SQL arguments
Vector binding shapes
Each relation subquery projects an id and either feature columns in dimension order or one list column, with the element types listed under Vector element types. Nullable field types are accepted. A null ID, feature value, list row, or list element fails the query.
The list-column shape excludes other feature columns. See ML Inputs for the allowed list containers and runtime checks.
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
- Amazon Reviews
- EMBER2024
Can projected reviews be connected back to their original text?
This query projects 9,967 sampled low-rating headphone reviews from 1,024 dimensions and joins the output IDs to product names and review text.
SELECT u.id, u.dim_0, u.dim_1, r.product_id,
p.title AS product_title, EXTRACT(YEAR FROM r.review_time) AS review_year,
r.rating, r.title, r.embedding_text
FROM cuml_umap(
input => (SELECT v.id, v.vector
FROM semantic_reviews_vectors v
JOIN semantic_reviews_text r ON r.id = v.id
WHERE r.category_l3 = 'Headphones & Earbuds' AND v.sample_rank < 100000
ORDER BY v.id),
n_components => 2, n_neighbors => 30, min_dist => 0.1, random_state => 42) u
JOIN semantic_reviews_text r ON r.id = u.id
JOIN products p ON p.product_id = r.product_id
ORDER BY u.id
The first three records of the saved projection show the returned coordinates with the rating and year of each review. The saved sample keeps review IDs, coordinates, ratings and years; the review text stays in the source dataset.
UMAP's output is a relation that can be joined to the review records in the same query, allowing reviewers to inspect the underlying review text alongside projection coordinates.
The capture records the query and the fixed 1,200-record website sample drawn from its 9,967 rows.
This example uses the EMBER2024 demo dataset.
Where do the challenge histograms sit in a two-dimensional UMAP view?
This query fits UMAP to all 3,225 Win32 challenge files using their 512-element
normalized histograms, with n_neighbors = 30 and random_state = 42. The SQL
joins labels, weeks, SHA-256 values, and family names after the projection.
These fields support later inspection. They are not UMAP input columns.
SELECT u.id,
u.dim_0,
u.dim_1,
v.label,
m.week_id,
m.sha256,
m.family
FROM cuml_umap(
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,
n_neighbors => 30,
random_state => 42
) u
JOIN ember_research_vectors_challenge v ON v.id = u.id AND v.split = 'challenge'
JOIN ember_metadata_challenge m ON m.id = v.id
ORDER BY u.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
- L2SqrtExpanded distance, brute-force kNN, and deterministic mode are fixed.
- Float64 features, as wide columns or list elements, are narrowed to Float32 on the device before training or inference. Each value rounds to the nearest Float32, which keeps about seven significant digits; a value beyond the Float32 range becomes infinite and fails the query.
- Empty input returns an empty result. Other inputs require n_neighbors < rows, checked at execution.
- min_dist must not exceed spread. The fit and embedding are query-local.
- random_state seeds the spectral initialization, the edge shuffle, and negative sampling.