Taxonomies

Taxonomies let you attach structured metadata to documents by matching them against a reference collection. They are implemented as retriever-powered joins and can run on demand or be materialized into collections. Taxonomies are warehouse-native enrichment: the multimodal equivalent of a SQL JOIN, linking documents to canonical entities via embedding similarity rather than key equality.

From clusters to taxonomies: documents are embedded into a shared vector space, unsupervised clustering discovers natural structure, an LLM labels each cluster (product reviews, technical docs, legal contracts, support tickets), and stable clusters are promoted into reusable hierarchical taxonomy nodes. The taxonomy then auto-classifies new documents at ingest, becomes search filters at query time, and reclassifies existing documents retroactively when the hierarchy changes. — From clusters to taxonomies: embed, cluster, label, promote — then the taxonomy classifies new documents at ingest, powers filters at query time, and reclassifies retroactively when nodes change.

Taxonomy Types

Type	Structure	When to Use
Flat	Single-level reference collection	Face enrollment, entity linking, simple lookups
Hierarchical	Parent/child nodes with inheritance	Org charts, product categories, multi-level labeling

Each node references a collection, retriever, and list of enrichment fields. Child nodes inherit parent properties automatically.

Flat Taxonomy: Product Catalog Recognition

Flat taxonomy showing multimodal documents matched against a product catalog reference collection

In a flat taxonomy, documents from any modality (video, image, audio, text) are matched against a single reference collection. Each document uses its appropriate feature embedding (CLIP for visual, text embeddings for audio transcripts) to find the best match. Enrichment fields (SKU, category, price) are attached when similarity exceeds the threshold.

Hierarchical Taxonomy: Media Content Classification

In a hierarchical taxonomy, documents traverse multiple levels of progressive refinement. Starting from a broad brand classification (1 node), through content category (2 nodes), sport/style type (4 nodes), audience segmentation (5 nodes), to specific campaigns (6 nodes). Each level narrows the classification using different multimodal features—CLIP for brand detection, scene classification for categories, activity detection for sport types, demographic models for audiences, and campaign-specific patterns at the final level. Documents inherit all properties from parent nodes as they traverse down the tree.

Execution Modes

A taxonomy runs one of three ways, each through its own surface, not a shared mode field:

Mode	Description	Configured via	Use Case
On-demand	Enrich documents at query time inside a retriever	A `taxonomy_enrich` stage on a retriever	Exploratory workflows, testing, dynamic reference data
Materialized	Batch enrichment after extraction; results persisted in the collection	`taxonomy_applications[].execution_mode: "materialize"` on the collection	Production search, low-latency retrieval, analytics
Retroactive	Apply taxonomy to existing documents in a collection	`POST /v1/collections/{id}/apply-taxonomy`	Backfilling, taxonomy updates, schema migrations

taxonomy_applications[].execution_mode only accepts materialize; the other two modes are not values of this field. See Application Methods below for each mode’s request shape.

How Hierarchical Taxonomies Execute

Hierarchical taxonomies are executed like Common Table Expressions (CTEs) in SQL—each level builds on the results of the previous level, creating a recursive evaluation chain from root to leaf nodes.

Level 1 (Root)     →  Match against brand collection
    ↓ passes matched docs
Level 2            →  Match against category collection (filtered by L1 result)
    ↓ passes matched docs
Level 3            →  Match against subcategory collection (filtered by L2 result)
    ↓ passes matched docs
Level N (Leaf)     →  Final enrichment fields attached

At each level:

Documents that matched the parent node are passed down
The child node’s retriever executes against its reference collection
Enrichment fields from matching nodes are accumulated
Only documents exceeding the similarity threshold continue to child nodes

This CTE-style execution ensures that a document classified as “Nike → Athletic → Running” inherits enrichment fields from all three levels, not just the leaf node.

Application Methods

Hierarchical taxonomies can be applied through three methods:

Method	When It Runs	Use Case
On-demand	Query time, as a retriever stage	Dynamic classification, A/B testing taxonomy versions, low-volume queries
Materialized	During collection processing (post-extraction)	Production search requiring low latency, analytics dashboards
Retroactive	Manually triggered via API	Backfilling existing documents, applying updated taxonomy versions

On-demand enrichment adds a taxonomy_enrich stage to your retriever pipeline:

{
  "stage_name": "taxonomy_enrich",
  "stage_type": "enrich",
  "config": {
    "stage_id": "taxonomy_enrich",
    "parameters": {
      "taxonomy_id": "tax_org_roles",
      "min_score": 0.4
    }
  }
}

Materialized enrichment runs automatically after document extraction completes. Configure it in the collection’s taxonomy_applications:

{
  "taxonomy_applications": [
    {
      "taxonomy_id": "tax_product_hierarchy",
      "execution_mode": "materialize"
    }
  ]
}

Retroactive enrichment applies a taxonomy to documents already in the collection:

curl -sS -X POST "$MP_API_URL/v1/collections/<collection_id>/apply-taxonomy" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_id": "tax_product_hierarchy",
    "scroll_filters": {
      "field": "metadata.needs_reclassification",
      "operator": "eq",
      "value": true
    }
  }'

Use retroactive application when:

You’ve updated a taxonomy and need to reclassify existing documents
You’re migrating from a flat taxonomy to a hierarchical one
You’ve added new reference data to taxonomy collections

Internals: JOIN Stage

Taxonomies reuse the join@v1 stage under the hood:

Direct join – key-based match (join_type: "direct").
Retriever join – similarity match using a nested retriever (join_type: "retriever").
Join strategies – replace, enrich, left, or append control how fields merge.

Parallel execution (asyncio.gather) makes retrieval joins 10–50× faster than sequential lookups.

Create a Flat Taxonomy

Only taxonomy_name and config are required at the top level. Everything that describes the taxonomy goes inside config.

curl -sS -X POST "$MP_API_URL/v1/taxonomies" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_name": "employee_faces",
    "config": {
      "taxonomy_type": "flat",
      "retriever_id": "ret_face_matcher",
      "input_mappings": [
        { "input_key": "query", "source_type": "payload", "path": "text" }
      ],
      "source_collection": {
        "collection_id": "col_employee_embeddings",
        "enrichment_fields": [
          { "field_path": "name", "merge_mode": "replace" },
          { "field_path": "department", "merge_mode": "replace" }
        ]
      }
    }
  }'

retriever_id and input_mappings are required for a flat taxonomy.

input_mappings maps a retriever input key to where the value comes from. Each entry is { input_key, source_type, path }. input_key must be a key the retriever’s own input_schema declares. Use path as a dot-path for payload and vector sources, and override to pass a static value for literal.It does not take a feature URI. A feature_uri identifies a vector index, not an input source.

A collection’s retriever_enrichments[].input_mappings is a different shape with a different vocabulary, despite the identical field name. Reaching for the wrong one produces a body that is accepted and ignored.

	Taxonomy `config.input_mappings`	Collection `retriever_enrichments[].input_mappings`
Entry	`{ input_key, source_type, path, override }`	`{ input_key, source: { source_type, path, value } }`
`source_type`	`payload`, `literal`, `vector`, `blob`	`document_field`, `constant`, `source_blob`

The taxonomy form is flat; the enrichment form nests everything but input_key under source. The two source_type vocabularies share no values, so a wrong guess is rejected rather than silently misread. A wrong shape is not: an entry sent flat to an enrichment fails its source requirement.

Every enrichment_fields[].field_path must already exist in the source collection’s output schema. These fields are copied from the source, so a path that is not there returns a 422 listing the fields that are.merge_mode is replace or append.

Create a Hierarchical Taxonomy

curl -sS -X POST "$MP_API_URL/v1/taxonomies" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "taxonomy_name": "org_roles",
    "config": {
      "taxonomy_type": "hierarchical",
      "retriever_id": "ret_face_matcher",
      "input_mappings": [
        { "input_key": "query", "source_type": "payload", "path": "text" }
      ],
      "hierarchical_nodes": [
        {
          "collection_id": "col_employee_embeddings",
          "parent_collection_id": null
        },
        {
          "collection_id": "col_executives",
          "parent_collection_id": "col_employee_embeddings",
          "retriever_id": "ret_executive_face"
        }
      ]
    }
  }'

Hierarchical nodes inherit parent enrichment properties; children can override or extend them.

A hierarchy is a flat list, not nested JSON. Nodes never contain child nodes. Each node names its parent with parent_collection_id, null marks a root, and the tree is rebuilt from those pointers. Order does not matter.collection_id is the only required field on a node, and it identifies the node. There is no separate node id.On a hierarchical taxonomy, retriever_id and input_mappings are optional at the config level and can be set per node. You can also let Mixpeek infer the shape with inference_strategy (schema, cluster, or llm) plus inference_collections, instead of listing nodes by hand.

Attach to a Collection

taxonomy_applications[].execution_mode only accepts materialize. To attach a taxonomy for materialized enrichment:

{
  "taxonomy_applications": [
    {
      "taxonomy_id": "tax_employee_faces",
      "execution_mode": "materialize"
    }
  ]
}

Materialized enrichment updates documents ~30 seconds after ingestion completes (debounced to avoid thrashing). For on-demand classification, add a taxonomy_enrich stage to a retriever instead (see Application Methods above); do not put the taxonomy in taxonomy_applications.

Test On Demand

taxonomy_enrich is an apply-category stage: it enriches documents already flowing through the retriever, so it needs a document-producing stage (for example feature_search) before it in the pipeline, not a standalone call. Add it to a retriever as shown under Application Methods above, then run POST /v1/retrievers/{retriever_id}/execute.

Inference Strategies

Manual – Define nodes explicitly (IDs, collections, retrievers).
Schema-based – Infer nodes from existing collection schemas (planned).
Cluster-based – Create nodes from clustering output.
LLM-based – Generate hierarchical structure from sample documents.

Combining strategies is encouraged: bootstrap via inference, then fine-tune manually.

Monitoring

List taxonomies: POST /v1/taxonomies/list
Inspect hierarchy and node metadata: GET /v1/taxonomies/{id}?expand_nodes=true
Track materialized enrichment progress via webhook events (collection.documents.written)
Use retriever analytics to ensure taxonomy stages don’t dominate latency.

Best Practices

Start flat for quick wins; layer hierarchies once value is proven.
Keep enrichment minimal—copy only fields needed at query time.
Cache taxonomy stages in retrievers when reference collections rarely change.
Version taxonomies (via snapshots) before major structural changes.
Combine with clusters to discover candidate nodes and measure coverage.

Taxonomies let you inject domain knowledge into multimodal search—link documents to canonical entities without relying on brittle key joins.

Get started

Connect your data

Extract features

Build retrievers

Enrich & organize

Integrate & operate

Resources

Taxonomy Types

Flat Taxonomy: Product Catalog Recognition

Hierarchical Taxonomy: Media Content Classification

Execution Modes

How Hierarchical Taxonomies Execute

Application Methods

Internals: JOIN Stage

Create a Flat Taxonomy

Create a Hierarchical Taxonomy

Attach to a Collection

Test On Demand

Inference Strategies

Monitoring

Best Practices

​Taxonomy Types

​Flat Taxonomy: Product Catalog Recognition

​Hierarchical Taxonomy: Media Content Classification

​Execution Modes

​How Hierarchical Taxonomies Execute

​Application Methods

​Internals: JOIN Stage

​Create a Flat Taxonomy

​Create a Hierarchical Taxonomy

​Attach to a Collection

​Test On Demand

​Inference Strategies

​Monitoring

​Best Practices

Taxonomy Types

Flat Taxonomy: Product Catalog Recognition

Hierarchical Taxonomy: Media Content Classification

Execution Modes

How Hierarchical Taxonomies Execute

Application Methods

Internals: JOIN Stage

Create a Flat Taxonomy

Create a Hierarchical Taxonomy

Attach to a Collection

Test On Demand

Inference Strategies

Monitoring

Best Practices