Stage Category: ENRICH (Enriches documents with classifications)Transformation: N documents → N documents (with taxonomy labels added)
When to Use
| Use Case | Description |
|---|---|
| Content categorization | Auto-classify documents into topics |
| Faceted search | Add filterable category facets |
| Compliance tagging | Apply regulatory classifications |
| Product taxonomy | Classify into product hierarchies |
When NOT to Use
| Scenario | Recommended Alternative |
|---|---|
| Free-form tagging | llm_enrich |
| Pre-classified content | Skip this stage |
| Custom classification logic | api_call to custom service |
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
taxonomy_id | string | Required | ID of the taxonomy to use |
content_field | string | content | Field to classify |
result_field | string | taxonomy | Field for classification results |
max_depth | integer | null | Maximum hierarchy depth |
top_k | integer | 3 | Number of top classifications |
min_score | float | 0.5 | Minimum confidence threshold |
include_ancestors | boolean | true | Include parent categories |
Configuration Examples
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "product_categories"
}
}
}
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "topics",
"top_k": 1,
"min_score": 0.8
}
}
}
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "industry_taxonomy",
"top_k": 3
}
}
}
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "content_types",
"top_k": 5,
"min_score": 0.3
}
}
}
Output Schema
Basic Classification
{
"document_id": "doc_123",
"content": "Latest smartphone with 5G connectivity...",
"categories": {
"primary": {
"id": "electronics.mobile.smartphones",
"name": "Smartphones",
"confidence": 0.95
},
"all": [
{"id": "electronics.mobile.smartphones", "name": "Smartphones", "confidence": 0.95},
{"id": "electronics.mobile", "name": "Mobile Devices", "confidence": 0.82},
{"id": "electronics", "name": "Electronics", "confidence": 0.78}
]
}
}
With Ancestors
{
"document_id": "doc_456",
"content": "Investment banking services...",
"industry": {
"primary": {
"id": "finance.banking.investment",
"name": "Investment Banking",
"confidence": 0.91
},
"ancestors": [
{"id": "finance.banking", "name": "Banking", "level": 2},
{"id": "finance", "name": "Finance", "level": 1}
],
"path": "Finance > Banking > Investment Banking"
}
}
Low Confidence (No Match)
{
"document_id": "doc_789",
"content": "Random unrelated content...",
"categories": {
"primary": null,
"all": [],
"message": "No classifications above confidence threshold"
}
}
Taxonomy Structure
Taxonomies are hierarchical classification systems:Electronics
├── Mobile Devices
│ ├── Smartphones
│ ├── Tablets
│ └── Wearables
├── Computers
│ ├── Laptops
│ ├── Desktops
│ └── Components
└── Audio
├── Headphones
└── Speakers
- ID: Dot-notation path (e.g.,
electronics.mobile.smartphones) - Name: Human-readable label
- Level: Depth in hierarchy (1 = root)
Performance
| Metric | Value |
|---|---|
| Latency | 10-50ms per document |
| Batch processing | Automatic |
| Model type | Embedding-based classification |
| Parallel execution | Up to 20 concurrent |
Pre-compute taxonomy embeddings for faster classification. Use
top_k: 1 and higher min_score when you only need the best match.Common Pipeline Patterns
Search + Classify + Filter
[
{
"stage_name": "semantic_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 100 }
],
"final_top_k": 100
}
}
},
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "product_categories",
"top_k": 1,
"min_score": 0.7
}
}
},
{
"stage_name": "structured_filter",
"stage_type": "filter",
"config": {
"stage_id": "attribute_filter",
"parameters": {
"conditions": {
"field": "category.primary.id",
"operator": "starts_with",
"value": "{{INPUT.category_filter}}"
}
}
}
}
]
Multi-Taxonomy Classification
[
{
"stage_name": "semantic_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 50 }
],
"final_top_k": 50
}
}
},
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "topics"
}
}
},
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "sentiment"
}
}
}
]
Faceted Search Results
[
{
"stage_name": "hybrid_search",
"stage_type": "filter",
"config": {
"stage_id": "feature_search",
"parameters": {
"searches": [
{ "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1", "query": { "input_mode": "text", "value": "{{INPUT.query}}" }, "top_k": 100 }
],
"final_top_k": 100
}
}
},
{
"stage_name": "taxonomy_enrich",
"stage_type": "enrich",
"config": {
"stage_id": "taxonomy_enrich",
"parameters": {
"taxonomy_id": "categories",
"top_k": 3
}
}
}
]
Error Handling
| Error | Behavior |
|---|---|
| Unknown taxonomy_id | Stage fails |
| No match found | Empty classification, continues |
| Invalid content_field | Stage fails |
| Low confidence | Filtered by min_score |
Related
- LLM Enrich - Free-form extraction
- Document Enrich - Collection joins
- Attribute Filter - Filter by categories