Documents & Search

Upsert vectors, search with dense/sparse/BM25/hybrid, and manage documents

Upsert Documents

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

Python

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"]}

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

Large Imports

Repeat the upsert call in batches of up to 1,000 documents. There is no separate bulk-import endpoint.

Search

Querying is unified through retrievers — Mixpeek has one query path, so there is no direct POST /v1/namespaces/{ns}/documents/search REST endpoint. The client.search(...) helper below is SDK sugar that authors and runs a retriever for you. From raw HTTP/curl, create a one-stage feature_search retriever and execute it — the verified BYO example immediately below does exactly that in three calls.

Query BYO vectors from raw HTTP (verified)

Bring your own vectors and query them with a raw query vector — no extractor, no re-processing. The query is an object ({"input_mode": "vector", "value": "{{INPUT.qv}}"}), and the retriever’s input_schema declares the input variable your execute call fills in.

cURL

# 1. Create a feature_search retriever over your BYO vector index ("my_vec").
#    Note: stage_type is "filter"; the operation is stage_id "feature_search".
curl -X POST "https://api.mixpeek.com/v1/retrievers" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" -H "X-Namespace: $NS" -H "Content-Type: application/json" \
  -d '{
    "retriever_name": "byo-knn",
    "input_schema": {"qv": {"type": "array", "required": true}},
    "stages": [{
      "stage_name": "knn", "stage_type": "filter",
      "config": {"stage_id": "feature_search", "parameters": {
        "searches": [{
          "feature_uri": "my_vec",
          "query": {"input_mode": "vector", "value": "{{INPUT.qv}}"}
        }],
        "final_top_k": 10
      }}
    }]
  }'
# → {"retriever_id": "ret_...", ...}

# 2. Execute it with your query vector. pagination.method is required.
curl -X POST "https://api.mixpeek.com/v1/retrievers/$RETRIEVER_ID/execute" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" -H "X-Namespace: $NS" -H "Content-Type: application/json" \
  -d '{"inputs": {"qv": [1,0,0,0,0,0,0,0]}, "pagination": {"method": "offset", "page_size": 10, "page_number": 1}}'
# → {"documents": [{"document_id": "d1", "score": 1.0, ...}, ...]}

The execute cache is invalidated by upserts — a query re-run after an upsert returns fresh results (cache_hit: false), so the write-then-verify loop is safe.

Dense (Vector) — SDK

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}
Read many by ID	POST	/v1/documents/batch-get
List and paginate	POST	/v1/documents/list
Update payload	PATCH	/v1/documents/{doc_id}
Delete	DELETE	/v1/collections/{collection_id}/documents/{doc_id}

Only upsert and get-by-ID carry the namespace in the path. The rest read it from the X-Namespace header. Delete is collection-scoped, so a document you reach by namespace is deleted through its collection.

Read Many by ID

Resolve up to 1,000 documents in one call. The namespace comes from the X-Namespace header here, not from the path.

curl -X POST "https://api.mixpeek.com/v1/documents/batch-get" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $MIXPEEK_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["prod-001", "prod-002", "prod-404"]}'
# → {"documents": [...], "not_found": ["prod-404"]}

Field	Meaning
document_ids	1 to 1,000 ids. Required.
return_presigned_urls	Accepted and ignored on this endpoint. Batch-get always presigns.
documents	The documents that resolved.
not_found	Each id that did not resolve, listed individually.

Match returned documents by document_id rather than by position. The response order does not track the order you sent.

An id that does not resolve does not fail the call. It lands in not_found and every other id still returns, so read not_found rather than comparing lengths.

Media URLs

Stored media fields hold a raw storage URI: gs:// on Mixpeek Cloud, s3:// on S3-backed deployments. Whether you get a fetchable https:// URL back depends on the endpoint you called, not on the field name.

Surface	Presigns
Retriever execute	Always. return_presigned_urls is not read on this path.
POST /v1/documents/batch-get	Always. The flag is accepted and ignored.
POST /v1/documents/list	Only with "return_presigned_urls": true in the body.
GET /v1/documents/{doc_id}	Only with the flag, and these URLs last 1 hour.

POST /v1/documents/list reads that flag from the request body only. A ?return_presigned_urls=true query string is ignored, and you get raw gs:// values back, which most HTTP clients reject with unknown url type: gs.

Selection works on the value, not the name. Any field whose value starts with gs:// or s3:// gets signed, whatever the field is called. These stay raw:

• anything under metadata
• values nested inside dicts or lists, on documents carrying a collection_id
• original_url, source_blobs, and presigned_urls
• any URI whose signing call fails

Signed URLs last 24 hours everywhere except the single-document GET above.

Update Vectors

Re-upsert the document through POST /v1/namespaces/{ns}/documents/upsert. Sending an existing document_id overwrites that document, vectors and payload together, so send the payload you want to keep alongside the new vectors.

No endpoint replaces vectors while leaving the payload untouched.

Related

• Namespace Configuration
• Promote to Managed