Two Clustering Types
Mixpeek supports two fundamentally different ways to cluster documents:Vector (Semantic)
Groups documents by embedding similarity — what they mean, not what metadata they have. Uses vector embeddings from any extractor (text, image, multimodal) and supports 8 algorithms.Best for: topic discovery, content deduplication, visual similarity, finding themes across modalities.
Attribute (Metadata)
Groups documents by metadata field values — like a
GROUP BY on structured columns. No embeddings needed; operates directly on payload fields.Best for: categorical grouping, hierarchical organization by brand/category/status, faceted analytics.Vector Clustering
Attribute Clustering
hierarchical_grouping: true, this creates nested groups: “Electronics” containing “Apple”, “Samsung”, etc. Without it, you get flat groups like “Electronics_Apple”, “Electronics_Samsung”.
Algorithms
Vector clustering supports 8 algorithms. Pick based on whether you know how many clusters to expect:Multi-Feature Strategy
When clustering on multiple embeddings (e.g., text + image), choose how to combine them:Visualization Dimensions
In Studio, the cluster scatter plot encodes three visual dimensions so you can explore cluster structure at a glance:
To enable the size dimension, set 3 components in your dimensionality reduction config:
Without the third component, all dots render at the same size. With it, the Z value is linearly mapped to dot radius (10px–50px), so visually prominent points sit “closer” in the third principal axis.
Centroid Methods
Control how cluster centers are calculated:Preprocessing
High-dimensional embeddings (1408d, 3072d) benefit from preprocessing before density-based algorithms. Thepreprocessing_steps field accepts an ordered list:
Whitening (ZCA)
Whitening (ZCA)
Decorrelates embedding dimensions, removing redundant structure that causes density-based algorithms to over-fragment.
UMAP reduction
UMAP reduction
Reduces dimensionality while preserving neighborhood structure. Critical for HDBSCAN on high-dimensional data.
Chained (recommended for high-dim)
Chained (recommended for high-dim)
Whitening + UMAP together typically improves HDBSCAN cluster purity by 15–30% on embeddings above 1000 dimensions.
Execution Modes
Incremental Assignment
assignment_threshold cosine similarity are marked as noise (cluster_id = -1).
Composite Clustering
Clusters centroids from prior runs to reveal higher-order patterns. A run with 10,000 documents and 50 clusters contributes only 50 vectors, so composite execution is fast. Map your library along multiple dimensions at once. A common analyst question — “how do my visual-style groups relate to my messaging-theme groups?” — is expressed with exactly this machinery, no tagging required:- Run several independent clusterings on the same collection (one per dimension — e.g. one over visual embeddings, one over transcript embeddings). Each is its own cluster resource; a collection can have as many as you need.
- Composite them: pass the runs as
source_execution_idswithmode: "composite". The composite groups the centroids from every input run, so groups that land together across dimensions surface as one higher-order pattern (e.g. a “street-interview format” centroid clustering next to a “risk-reversal claim” centroid = a combination worth briefing). - Read the result on the cluster’s visualization map in Studio (lasso a region to search inside it, or create a retriever scoped to a group directly from the map).
Hierarchical Sub-Clustering
Enable recursive sub-clustering when top-level clusters are too broad. Each cluster with enough members is further divided using UMAP + HDBSCAN.cl_0_sub_1_sub_0. Each centroid includes parent_cluster_id, child_cluster_ids, and hierarchy_level. Example: “sports” → “basketball” → “NBA highlights”.
Quality Metrics
Every execution returns metrics that tell you whether your clusters are meaningful:
Per-member similarity is also tracked:
LLM Labeling
Generate human-readable names, summaries, and keywords for each cluster. Control which document fields the LLM sees using input mappings.Text-Only Labeling
Multimodal Labeling
Send images or video alongside text for richer labels. Use a vision-capable model:Input Mapping Reference
Without
labeling_inputs, the full document payload is serialized as JSON. Input mappings let you send only the fields that matter.Custom Prompts and Response Shapes
Override the default prompt for domain-specific labels:Labeling Settings
Enrichment
Write cluster membership back into your source collections:cluster_id and labels into document payloads, enabling cluster-based filters and facets in retrievers.
Execution & Triggers
- Manual:
POST /v1/clusters/{id}/execute - Async job:
POST /v1/clusters/{id}/execute/submit - Automated: create cron, interval, or event-based triggers under
/v1/clusters/triggers - Every run yields a
run_idand exposes status viaGET /v1/clusters/{id}/executions
Artifacts
Management
Best Practices
- Start with HDBSCAN + whitening + UMAP for vector clustering on high-dimensional embeddings.
- Prototype on samples — tune parameters with a small
sample_sizebefore running at scale. - Use incremental assignment for streaming data —
fullperiodically,assignfor new documents in between. - Monitor quality metrics — check
silhouette_scoreandnoise_ratioafter each run. Recluster whenshould_reclusterfires. - Use attribute clustering for categorical grouping — don’t force embeddings when metadata fields already capture the structure.
- Try multi-feature
weightedstrategy when combining modalities — let Bayesian optimization find the right blend. - Enable 3-component dimensionality reduction to get the depth (size) dimension in Studio visualizations.