UMAP

UDTF: cuml_umap

Official cuML reference: Python API

cuML UMAP fits a deterministic, query-local manifold embedding for Float32 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, Float32 feature, null, finite-value, and runtime-dimension contract.

Role	Required	Validation reference	Description
input	yes	table	Dense Float32 rows fitted and transformed in this statement.

Vector element types

Element type	Valid metrics
Float32	Not applicable

Arguments and options

Scalar SQL arguments

Argument	Type	Required	Description
n_components	integer	no	Number of embedding dimensions.
n_neighbors	integer	no	Number of neighbors used to construct the manifold.
n_epochs	integer	no	Optimization epochs; zero selects the native default.
learning_rate	number	no	Positive embedding optimization rate.
min_dist	number	no	Minimum distance between embedded points; at most spread.
spread	number	no	Positive scale for embedded point distances.
set_op_mix_ratio	number	no	Fuzzy-set intersection/union mix in [0, 1].
local_connectivity	number	no	Local connectivity adjustment.
repulsion_strength	number	no	Repulsive force applied during optimization.
negative_sample_rate	integer	no	Negative samples per positive edge.
init	enum ("spectral", "random")	no	Embedding initialization method.
random_state	integer	no	Seed for reproducible initialization.

SQL value argument schemas

Argument	Required	Literal shape	Default	Constraints	Description
init	no	string	"spectral"	one of "spectral", "random"	Embedding initialization method.
learning_rate	no	number	1	greater than 0	Positive embedding optimization rate.
local_connectivity	no	number	1	minimum 0	Local connectivity adjustment.
min_dist	no	number	0.1	minimum 0	Minimum distance between embedded points; at most spread.
n_components	no	integer	2	minimum 1; maximum 2147483647	Number of embedding dimensions.
n_epochs	no	integer	0	minimum 0; maximum 2147483647	Optimization epochs; zero selects the native default.
n_neighbors	no	integer	15	minimum 1; maximum 2147483647	Number of neighbors used to construct the manifold.
negative_sample_rate	no	integer	5	minimum 1; maximum 2147483647	Negative samples per positive edge.
random_state	no	integer	0	minimum 0; maximum 18446744073709551615	Seed for reproducible initialization.
repulsion_strength	no	number	1	minimum 0	Repulsive force applied during optimization.
set_op_mix_ratio	no	number	1	minimum 0; maximum 1	Fuzzy-set intersection/union mix in [0, 1].
spread	no	number	1	greater than 0	Positive scale for embedded point distances.

Vector binding shapes

Each relation subquery projects a non-null id and either non-null Float32 feature columns in dimension order or one non-null vector list column of non-null Float32 values. For classification, training also projects non-null Int32 label; regression requires non-null finite Float32 label. The predict relation omits it.

The list-column shape excludes other feature columns. See ML Inputs for the allowed list containers and runtime checks.

Output

Column	Type	Nullable	Description
row_ordinal	UInt64	no	Evaluated input row position, including when IDs repeat. Follows the input's top-level ORDER BY on output columns; unspecified without one.
id	same_as_input.id	no	Logical input ID.
dim_<index>	Float32	no	Embedded dimension value, repeated n_components times. The output contains n_components such columns, dim_0 through dim_&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.

Examples

Amazon Reviews

This example uses the Amazon Reviews demo dataset.

Which nearby reviews should a support analyst read together?

A review list sorted by date separates reports that use different words for a similar problem. This query selects 9,967 sampled low-rating headphone reviews, projects their 1,024-dimensional BGE-M3 vectors into two dimensions, and joins the coordinates back to product names and review text.

The cohort is defined inside the algorithm's input subquery. Removing accessories or changing the sample changes the fitted map. The displayed snapshot lets a reader inspect the original text at a point before treating its neighborhood as a useful review group.

Find words in reviews or product namesReview year2021 and 202220212022

202120221,200 of 1,200 displayed reviews match

Otium Bluetooth Earbuds Wireless Headphones Bluetooth Headphones, Sports Earbuds, IPX7 Waterproof Stereo Earphones for Gym Running 15 Hours Playtime Sound Isolation Headsets

Review 2017 · 2021 · Rating 2/5

Nope This isn’t a good quality item. I’m returning

UMAP was fitted to 9,967 sampled low-rating headphone reviews. This view displays 1,200 evenly spaced review IDs from that result, captured 2026-09-28. Filters highlight this saved sample; they do not refit UMAP. Nearby points are candidates for reading together. Map distance is not a defect score.

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;

UMAP coordinates are a view for exploration. Long distances on this map have no calibrated business meaning, and compact regions do not establish product failure categories. Review year is a display color, not an input feature. Changing the filters in the visualization highlights saved points; it does not rerun the query.

EMBER2024

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.

The saved scatter includes all query rows and lets you select a captured projection. Its HDBSCAN filter uses the separate PCA-16 cluster assignments. Changing a projection or filter only selects saved output rows. It does not rerun UMAP or HDBSCAN.

ProjectionUMAPPCATruncated SVDSearch full SHA-256 or familyPCA-16 HDBSCAN clusterAll clustersNoise (-1)Cluster 0Cluster 1Cluster 2Cluster 3Cluster 4Cluster 5Cluster 6

Noise (-1)Cluster 0Cluster 1Cluster 2Cluster 3Cluster 4Cluster 5Cluster 63,225 of 3,225 points match

Focus the plot and use ← / → to navigate, Enter to select.

doenerium

EMBER ID 20000000 · week 0 · capture-local cluster 5 · HDBSCAN membership strength 1.000

058f63432dd8f679aef17b6fa16dd513273f10d8512f9897fa850585ea1d6d02

All 3,225 saved challenge Win32 rows are included. Projection and cluster values come from saved SQL results; changing filters 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

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;

MerRec marketplace

This example uses the MerRec dataset and graph capture page and its ordered category-share definition.

Which captured audiences have concentrated preferences, and which have mixed profiles?

The map joins saved UMAP coordinates, HDBSCAN assignments, and view counts by user ID. Its question is descriptive: whether category preferences form a few concentrated groups among users with at least 20 item_view events in this October capture. The category features use view events before 2023-10-21, expressed in SQL as event_time < TIMESTAMP '2023-10-21'. Repeated views of one item count as separate events. The five assigned groups contain 603 users. HDBSCAN leaves 1,316 of the 1,919 rows as noise, and those rows remain available in the map filter.

UMAP used the 17 square-root-transformed category shares to fit its two display dimensions. HDBSCAN used the same 17 square-root-transformed shares in the original 17-dimensional space. Its labels are local to this fit. The 15-neighbor trustworthiness score against the original 17-dimensional input is 0.96464; that value describes this embedding and is not a business outcome.

HDBSCAN groupAll usersUnassigned noiseCluster 0: Electronics, 65 usersCluster 1: Toys & Collectibles, 230 usersCluster 2: Kids, 68 usersCluster 3: Women, 192 usersCluster 4: Men, 48 usersInclude unassigned users (noise)

Noise1,316Cluster 0, Electronics65Cluster 1, Toys & Collectibles230Cluster 2, Kids68Cluster 3, Women192Cluster 4, Men481,919 of 1,919 users shown

These buttons and the point detail work with keyboard focus.

Anonymous user 2132,879 viewsUnassigned noise

HDBSCAN membership strength: 0.000

Top categories by share of view events

• Women65.3%
• Vintage & collectibles29.9%
• Men1.8%
• Beauty1.3%
• Home0.5%

UMAP used 17 square-root-transformed shares of item_view events to place 1,919 users in two dimensions. HDBSCAN was fit separately to the original 17 dimensions. It marked 1,316 users as noise and assigned 603 users to five capture-local groups. Point distances do not estimate conversion. HDBSCAN probability represents membership strength.

The average squared feature shares within the five assigned groups emphasize Electronics, Toys & Collectibles, Kids, Women, and Men. Squaring restores each category's share of a user's item_view events. The rates below are cluster means from the vector validation capture.

HDBSCAN cluster	Users	Largest mean category share
0	65	Electronics, 88.8%
1	230	Toys & Collectibles, 86.6%
2	68	Kids, 85.7%
3	192	Women, 92.6%
4	48	Men, 86.6%

Reviewing group sizes and leading categories can guide which category-specific campaign variants to test, while conversion outcomes remain unmeasured.

Point distances on the map have no calibrated conversion meaning. The HDBSCAN probability field is cluster membership strength. These saved groups describe one browsing capture; they do not establish marketing response or uplift. Download the full point capture, including all 1,919 users, category shares, source hashes, and query IDs.

The map's UMAP coordinates came from query bf5b54b8-6b76-4ebd-af66-e0c8c6100544. The assignments came from query 1daad9d5-6b74-41cc-8e27-9cad3fa8f78c.

Saved UMAP SQL

SELECT *
FROM cuml_umap(
  input => (
    SELECT
      id,
      COALESCE(women, CAST(0 AS REAL)) AS women,
      COALESCE(toys, CAST(0 AS REAL)) AS toys,
      COALESCE(kids, CAST(0 AS REAL)) AS kids,
      COALESCE(men, CAST(0 AS REAL)) AS men,
      COALESCE(home, CAST(0 AS REAL)) AS home,
      COALESCE(electronics, CAST(0 AS REAL)) AS electronics,
      COALESCE(beauty, CAST(0 AS REAL)) AS beauty,
      COALESCE(vintage, CAST(0 AS REAL)) AS vintage,
      COALESCE(books, CAST(0 AS REAL)) AS books,
      COALESCE(sports, CAST(0 AS REAL)) AS sports,
      COALESCE(other, CAST(0 AS REAL)) AS other,
      COALESCE(handmade, CAST(0 AS REAL)) AS handmade,
      COALESCE(garden, CAST(0 AS REAL)) AS garden,
      COALESCE(arts, CAST(0 AS REAL)) AS arts,
      COALESCE(pets, CAST(0 AS REAL)) AS pets,
      COALESCE(office, CAST(0 AS REAL)) AS office,
      COALESCE(tools, CAST(0 AS REAL)) AS tools
    FROM mr_tastes
    ORDER BY id
  ),
  n_components => 2,
  n_neighbors => 30,
  min_dist => 0.1,
  random_state => 42
)
ORDER BY id;

Saved HDBSCAN SQL

SELECT *
FROM cuml_hdbscan(
  input => (
    SELECT
      id,
      COALESCE(women, CAST(0 AS REAL)) AS women,
      COALESCE(toys, CAST(0 AS REAL)) AS toys,
      COALESCE(kids, CAST(0 AS REAL)) AS kids,
      COALESCE(men, CAST(0 AS REAL)) AS men,
      COALESCE(home, CAST(0 AS REAL)) AS home,
      COALESCE(electronics, CAST(0 AS REAL)) AS electronics,
      COALESCE(beauty, CAST(0 AS REAL)) AS beauty,
      COALESCE(vintage, CAST(0 AS REAL)) AS vintage,
      COALESCE(books, CAST(0 AS REAL)) AS books,
      COALESCE(sports, CAST(0 AS REAL)) AS sports,
      COALESCE(other, CAST(0 AS REAL)) AS other,
      COALESCE(handmade, CAST(0 AS REAL)) AS handmade,
      COALESCE(garden, CAST(0 AS REAL)) AS garden,
      COALESCE(arts, CAST(0 AS REAL)) AS arts,
      COALESCE(pets, CAST(0 AS REAL)) AS pets,
      COALESCE(office, CAST(0 AS REAL)) AS office,
      COALESCE(tools, CAST(0 AS REAL)) AS tools
    FROM mr_tastes
    ORDER BY id
  ),
  min_cluster_size => 30,
  min_samples => 10
)
ORDER BY id;

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.
• Only Float32 features are supported; L2SqrtExpanded distance, brute-force kNN, and deterministic mode are fixed.
• 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.

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