Attach filters to an embedding

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

Store small metadata fields beside an embedding so a search can be restricted to matching items.

Before you run it: There is no partial metadata-update operation in this example; replace the vector entry.

Start with the single-vector setup, then replace that sample entry with the metadata below. Metadata means small values saved beside the vector, such as a category and stock flag. It is separate from fields in the source product row.

Save filter values beside the vectorMetadata is separate from the source row; changing it replaces the vector entry.

Choose exact filter fieldsPrepare values such as category and in_stock.
Include them in the writeStore metadata with the full vector under the source ID.
Search with matching valuesUse the same value types and spelling in the equality filter.

Follow the example

Choose the fields needed for filtering.
Include them as metadata in the write.
Use the source record’s ID.
Run the filtered-search example.

Run the request

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
    }
  }'

Apply the metadata filter

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

Important limits and checks

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.