examples · vector · 2 / 7

2. Insert with metadata

what this does

Same vector put as Example 1, but with a metadata object. The metadata is stored alongside the embedding and becomes filterable at search time.

when to use it

You'll later want to search "similar shoes only" - filtering by category, brand, region, etc.
The filter applies during search (not after), so highly-selective filters stay fast.
Store the filterable fields you need. Don't dump the whole row - vector search isn't a record retrieval API.

the request

POST /v1/tenants/:t/vector/:table/put

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/vector/shop.products/put" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id":        "sku-9281",
    "embedding": [0.0124, -0.0883, /* ... 768 floats ... */],
    "dim":       768,
    "metric":    "cosine",
    "metadata":  {
      "category":     "running-shoes",
      "price_bucket": "100-200",
      "in_stock":     true
    }
  }'

db.vector.put(
    "shop.products",
    "sku-9281",
    embedding_768d,
    metadata={
        "category":     "running-shoes",
        "price_bucket": "100-200",
        "in_stock":     True,
    },
)

await db.vectorPut("shop.products", {
  id:        "sku-9281",
  embedding: embedding768d,
  dim:       768,
  metric:    "cosine",
  metadata:  {
    category:     "running-shoes",
    price_bucket: "100-200",
    in_stock:     true,
  },
});

err := db.VectorPut(ctx, "shop.products", originchain.VectorPutRequest{
    ID:        "sku-9281",
    Embedding: embedding768d,
    Dim:       768,
    Metric:    "cosine",
    Metadata: map[string]any{
        "category":     "running-shoes",
        "price_bucket": "100-200",
        "in_stock":     true,
    },
})

filtering at search time

The filter is an equality predicate on metadata keys. See Example 7 for the search call. Equality only - for range filters (e.g., price < 100), filter the result client-side.

common mistakes

Forgetting to bucket continuous values. Filter equality on prices is useless ($129.50 ≠ $129.99). Store a bucket field like "price_bucket": "100-200" instead.
Updating metadata. To change a vector's metadata, re-put with the new metadata. Partial metadata updates aren't supported.