Run your first vector search
Embeddings live on the same rows as everything else, so a filter on price and a nearest-neighbour search are one request, not a join between two systems.
Before you start
An instance, an API key, and a model that turns your content into vectors. The dimension you choose is fixed per column.
export OC_URL='https://<your-instance>'
export OC_TENANT='<your-tenant>'
export OC_TOKEN='<your-api-key>'The four steps
- 1.Declare a vector column
The type is spelled "vector". Its width goes in the column's [columns.params] block as vector_dim, and the optional top-level [vector] table pins the collection's dimension and distance metric. Declare both and the two dimensions must agree, or registration fails — see the schema reference and vector schema.
[[columns]] name = "embedding" ty = "vector" [columns.params] vector_dim = 768 # Optional collection config. If you declare it, its dim must # equal the column's vector_dim or registration fails. [vector] dim = 768 distance = "cosine" - 2.Write the row, then the vector
Vector values are not stored in the row body. They live in their own keyspace, keyed by (tenant, table, id), and are written through the vector-put path — sending an embedding to the rows endpoint does not index it. Reuse the row's id on both sides and a search hit reads straight back to the full row. No second system to keep in step.
// 1. the row - every column except the embedding curl -X POST "$OC_URL/v1/tenants/$OC_TENANT/rows/shop.products" \ -H "Authorization: Bearer $OC_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id":"sku-8842","name":"Carbon Marathon","price":149}' // 2. the embedding - same id, vector keyspace curl -X POST "$OC_URL/v1/tenants/$OC_TENANT/vector/shop.products/put" \ -H "Authorization: Bearer $OC_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id":"sku-8842","dim":768, "embedding":[0.011,-0.082,0.046]}' // 768 floats in practice - 3.Search for the nearest
Send a query vector and how many neighbours you want.
curl -X POST "$OC_URL/v1/tenants/$OC_TENANT/vector/shop.products/topk" \ -H "Authorization: Bearer $OC_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "query": [0.011, -0.082, 0.046], "k": 10, "dim": 768, "metric": "cosine" }' - 4.Filter while you search
Metadata filters apply during the search, not after it, so asking for ten results under a price cap returns ten — not whatever survives a post-filter.
// see the reference for the filter syntax and how it interacts with recall
Use the metric your embedding model was trained for. cosine is the usual answer for text embeddings; the wrong metric quietly returns plausible, worse neighbours rather than failing.