> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Search

> Build search with vector embeddings and hybrid ranking

> [card] [Create your free workspace](https://studio.mixpeek.com/namespaces/create?mode=managed\&utm_source=docs\&utm_medium=tutorial\&utm_campaign=managed_onramp\&utm_content=semantic_search_tutorial)
>
> Follow this tutorial on your own data — create a free workspace, upload your documents, and run your first semantic search in minutes.

> [!TIP]
>
> Semantic search is one stage in the warehouse's Reassemble layer. This tutorial covers the basics; see [Multi-Stage Retrieval](https://docs.mixpeek.com/docs/retrieval/multi-stage-deep-dive.md) for composing it with other stages.

## 1. Create a Bucket

```bash theme={null}
POST /v1/buckets
{
  "bucket_name": "knowledge-base",
  "bucket_schema": {
    "properties": {
      "title": { "type": "text", "required": true },
      "content": { "type": "text", "required": true },
      "category": { "type": "text" },
      "tags": { "type": "array" }
    }
  }
}
```

## 2. Create a Collection

```bash theme={null}
POST /v1/collections
{
  "collection_name": "docs-search",
  "source": { "type": "bucket", "bucket_ids": ["bkt_kb"] },
  "feature_extractor": {
    "feature_extractor_name": "text_extractor",
    "version": "v1",
    "input_mappings": { "text": "content" },
    "parameters": {
      "model": "multilingual-e5-large-instruct",
      "chunk_strategy": "sentence",
      "chunk_size": 512,
      "chunk_overlap": 50
    },
    "field_passthrough": [
      { "source_path": "title" },
      { "source_path": "category" },
      { "source_path": "tags" }
    ]
  }
}
```

**Chunking strategies:**

* `sentence` – Best for Q\&A
* `paragraph` – Best for long-form content
* `fixed` – Predictable token windows

## 3. Ingest Documents

```bash theme={null}
POST /v1/buckets/{bucket_id}/objects
{
  "key_prefix": "/docs/api",
  "blobs": [
    { "property": "title", "type": "text", "data": "Authentication Guide" },
    { "property": "content", "type": "text", "data": "Mixpeek uses Bearer token authentication..." },
    { "property": "category", "type": "text", "data": "getting-started" }
  ]
}
```

## 4. Create a Retriever

```bash theme={null}
POST /v1/retrievers
{
  "retriever_name": "docs-search",
  "collection_identifiers": ["col_docs"],
  "input_schema": {
    "query": { "type": "text", "required": true }
  },
  "stages": [
    {
      "stage_name": "knn_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
        }
      }
    }
  ]
}
```

## 5. Search

```bash theme={null}
POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": { "query": "how do I authenticate API requests?" }
}
```

## Hybrid Search (Vector + BM25)

Combine semantic (vector) and keyword (BM25) matching in one stage. BM25 is **not** a separate feature — set `lexical: true` on a search to match the query against the namespace's full-text index instead of embedding it. Use `rrf` fusion so the score-scale mismatch between cosine similarity and BM25 doesn't matter.

```bash theme={null}
{
  "stages": [
    {
      "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
            },
            {
              "feature_uri": "mixpeek://text_extractor@v1/multilingual_e5_large_instruct_v1",
              "query": { "input_mode": "text", "value": "{{INPUT.query}}" },
              "lexical": true,
              "top_k": 100
            }
          ],
          "fusion": "rrf",
          "final_top_k": 50
        }
      }
    }
  ]
}
```

> [!NOTE]
>
> Lexical search requires a `text` payload index on the field. See [Text Indexes (BM25)](https://docs.mixpeek.com/docs/vector-store/namespaces.md#text-indexes-bm25) and the [Feature Search](https://docs.mixpeek.com/docs/retrieval/stages/feature-search.md#lexical-bm25-search) reference.

## Pre-Filter by Metadata

Filter before vector search for efficiency:

```bash theme={null}
{
  "stages": [
    {
      "stage_name": "category_filter",
      "stage_type": "filter",
      "config": {
        "stage_id": "attribute_filter",
        "parameters": {
          "field": "category",
          "operator": "eq",
          "value": "getting-started"
        }
      }
    },
    {
      "stage_name": "knn_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
        }
      }
    }
  ]
}
```

## Reranking

Use a cross-encoder for better accuracy:

```bash theme={null}
{
  "stages": [
    {
      "stage_name": "knn_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": "rerank",
      "stage_type": "sort",
      "config": {
        "stage_id": "rerank",
        "parameters": {
          "inference_name": "BAAI__bge_reranker_v2_m3",
          "top_k": 20
        }
      }
    }
  ]
}
```

See the [Rerank stage](https://docs.mixpeek.com/docs/retrieval/stages/rerank.md) reference for available models and parameters.

## Model Options

| Model | Speed | Use Case |
| - | - | - |
| `multilingual-e5-base` | Fast | High-volume |
| `multilingual-e5-large-instruct` | Medium | General-purpose |
| `bge-large-en-v1.5` | Medium | English-only |
| `openai/text-embedding-3-large` | Slow | Premium |

## Next steps

> [card] [Classify documents](https://docs.mixpeek.com/docs/enrichment/taxonomies.md)
>
> Auto-categorize documents against a taxonomy of reference categories.

> [card] [Discover topics](https://docs.mixpeek.com/docs/enrichment/clusters.md)
>
> Cluster document embeddings to surface topic groups without predefined categories.

> [card] [Get notified](https://docs.mixpeek.com/docs/enrichment/alerts.md)
>
> Trigger alerts when new documents match a condition.

> [card] [Schedule jobs](https://docs.mixpeek.com/docs/platform/triggers.md)
>
> Re-cluster or re-enrich on a cron or interval as new content lands.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.