Documents & Search

Upsert Documents

Insert or update documents with your pre-computed vectors and JSON payload. Up to 1,000 documents per request.

from mixpeek import Mixpeek

client = Mixpeek(api_key="mxp_sk_...")

result = client.namespaces.documents.upsert(
    namespace_id="product-search",
    documents=[
        {
            "document_id": "prod-001",
            "vectors": {"text_embedding": [0.12, -0.34, 0.56]},  # 1536 floats
            "payload": {"title": "Noise-Canceling Headphones", "price": 149.99, "in_stock": True},
        },
        {
            "document_id": "prod-002",
            "vectors": {"text_embedding": [0.08, 0.22, -0.41]},  # 1536 floats
            "payload": {"title": "Bluetooth Speaker", "price": 59.99, "in_stock": True},
        },
    ],
)
# → {"inserted": 2, "document_ids": ["prod-001", "prod-002"]}

curl -X POST "https://api.mixpeek.com/v1/namespaces/product-search/documents/upsert" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [{
      "document_id": "prod-001",
      "vectors": {"text_embedding": [0.12, -0.34, 0.56]},
      "payload": {"title": "Noise-Canceling Headphones", "price": 149.99}
    }]
  }'

Vector dimensions are validated against namespace config. If a document with the same ID exists, it is overwritten.

Bulk Import

For large datasets, stream NDJSON directly to shard WALs. Returns 202 Accepted with a batch ID to poll.

curl -X POST "https://api.mixpeek.com/v1/namespaces/product-search/bulk-import" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @products.ndjson

products.ndjson

{"document_id": "prod-001", "vectors": {"text_embedding": [0.12, ...]}, "payload": {"title": "..."}}
{"document_id": "prod-002", "vectors": {"text_embedding": [0.08, ...]}, "payload": {"title": "..."}}

Search

Dense (Vector)

results = client.search(
    namespace_id="product-search",
    queries=[{
        "vector_name": "text_embedding",
        "vector": query_embedding,
        "top_k": 10,
        "score_threshold": 0.7,
    }],
)

BM25 (Keyword)

Requires a text index on the target field.

results = client.search(
    namespace_id="product-search",
    queries=[{"text": "wireless noise canceling", "top_k": 10}],
)

Sparse

results = client.search(
    namespace_id="product-search",
    queries=[{"sparse_vector": {42: 0.8, 1337: 0.5, 9001: 0.3}, "top_k": 10}],
)

Hybrid

Combine multiple query types with RRF or DBSF fusion.

results = client.search(
    namespace_id="product-search",
    queries=[
        {"vector_name": "text_embedding", "vector": query_embedding, "top_k": 20},
        {"text": "wireless headphones", "top_k": 20},
    ],
    fusion="rrf",
)

Filtered

Add payload filters to any query type. Filters narrow results before scoring.

results = client.search(
    namespace_id="product-search",
    queries=[{
        "vector_name": "text_embedding",
        "vector": query_embedding,
        "top_k": 10,
        "filters": {
            "must": [
                {"key": "price", "range": {"lte": 100}},
                {"key": "in_stock", "match": {"value": True}}
            ]
        },
    }],
)

Document Operations

Operation	Method	Endpoint
Get by ID	`GET`	`/v1/namespaces/{ns}/documents/{doc_id}`
Update payload	`PATCH`	`/v1/namespaces/{ns}/documents/{doc_id}`
Delete	`DELETE`	`/v1/namespaces/{ns}/documents/{doc_id}`
Scroll (paginate)	`POST`	`/v1/namespaces/{ns}/documents/scroll`

Update Vectors

Operation	Method	Endpoint
Replace vectors (single doc)	`PATCH`	`/v1/namespaces/{ns}/documents/{doc_id}/vectors`
Batch replace vectors	`POST`	`/v1/namespaces/{ns}/documents/update-vectors`
Add new vector index	`POST`	`/v1/namespaces/{ns}/documents/add-vectors`

Payload is untouched when updating vectors.

​Upsert Documents

​Bulk Import

​Search

​Dense (Vector)

​BM25 (Keyword)

​Sparse

​Hybrid

​Filtered

​Document Operations

​Update Vectors

​Related