Skip to main content
umap_embedding takes the curated Parquet for a dataset, projects every row into two dimensions using UMAP, and emits the coordinates. The result drives the cluster scatter plot on the dataset page and grounds Summand’s “show me similar rows” answers. UMAP is unsupervised — it doesn’t need a target column. It looks at the geometry of the rows in feature space and finds a 2-D layout that preserves local neighborhoods.

​
What it’s good for

  • Cluster discovery — see at a glance whether your data has natural groupings, and how many.
  • Outlier visualization — outliers tend to land far from the dense regions of the projection.
  • Sanity-checking labels — if you have a categorical column you suspect is meaningful, color the scatter plot by it and see whether the colors form coherent regions.
UMAP is not a tool for measuring distances quantitatively in 2-D. The projection compresses high-dimensional structure; absolute distance numbers don’t carry the meaning they have in feature space. Use it for shape, not for numerics.

​
Inputs

None. The component runs on the full curated dataset.

​
Output shape

One [x, y] pair per projected row. The artifact also carries the same points as {x, y} objects under points. The artifact is umap_embedding.json. For datasets with more than 50,000 rows, the component projects a random sample of 50,000 rows to keep the projection tractable.

​
Display

The UMAP component ships with a bespoke React viewer (UMAPVisualization):
  • Scatter plot with zoom and pan.
  • Color-by-column — pick any column from the schema to color points; categorical columns get a discrete legend, numeric columns a gradient.
  • Hover for row preview — a tooltip shows the nearest point’s actual row values.
  • Lasso select — drag-select a region; the panel below shows the selected rows in a table.

​
Filtering from chat

UMAP isn’t directly queryable from chat — the raw coordinates aren’t useful in a text response. Summand can reference the artifact existing (“there are three visible clusters in this dataset’s UMAP”), but the actual visualization lives on the dataset page. The component’s agent_config is enabled: false for this reason — analyze({ component: "umap_embedding", ... }) is intentionally a no-op.

​
Compute profile

UMAP fitting is the most compute-intensive component in the catalog after EBM model fitting. For datasets under 10k rows it finishes in a minute or two; larger datasets benefit noticeably from the subsample cap.

​
Common gotchas

Most often this means your dataset has one dominant cluster — common for filtered or single-segment datasets. Color by a categorical column (region, plan tier, product category) to see whether structure exists within the blob; if not, try running UMAP on a view that includes more diverse rows.
UMAP groups by all features at once, not by your color column. If the color column isn’t strongly correlated with the rest of the feature space, the colors won’t form coherent regions. That’s a finding, not a bug — it means the color column doesn’t drive the broader structure.
UMAP layouts aren’t stable across changes to the data or the sample. A new run can produce the same cluster structure mirrored, rotated, or reflected. Compare clusters, not absolute axes.
No. The 50,000-row cap is a fixed cost ceiling.