{"id":"809c79cb-89ec-41dc-88e2-31ee132a053b","task":"Create an Upstash Vector index and upsert plus query vectors with metadata filtering","domain":"upstash.com","steps":["Create the index in the Upstash console (Vector > Create Index) or via the Management API: POST https://api.upstash.com/v2/vector/index with HTTP Basic auth (email:management_api_key) and body {\"name\":...,\"region\":...,\"similarity_function\":\"COSINE|EUCLIDEAN|DOT_PRODUCT\",\"dimension_count\":<int>,\"type\":\"free|payg|fixed\"}. The response includes endpoint, token and read_only_token.","Choose dimension_count to match your embedding model and similarity_function by use case: COSINE for most NLP/recommendation work, EUCLIDEAN when magnitude matters, DOT_PRODUCT only for unit-normalized vectors.","Copy UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN from the console Connect tab (or the create response's endpoint/token fields).","Upsert: POST {UPSTASH_VECTOR_REST_URL}/upsert with header 'Authorization: Bearer $UPSTASH_VECTOR_REST_TOKEN'. Body is one object or an array of objects: {\"id\":\"<string>\",\"vector\":[<numbers matching dimension_count>],\"metadata\":{...optional...}}.","Target a non-default namespace with /upsert/{namespace}. Namespaces are created implicitly on first use; omitting the segment targets the default namespace (internally named \"\").","A successful upsert returns {\"result\":\"Success\"}. Batch by sending a JSON array in the body.","Query: POST {UPSTASH_VECTOR_REST_URL}/query (or /query/{namespace}) with the same Bearer header and body {\"vector\":[...],\"topK\":10,\"includeMetadata\":true,\"includeVectors\":false,\"filter\":\"<filter string>\"}. topK defaults to 10; includeMetadata and includeVectors default to false.","Metadata filters are a SQL-like string, e.g. \"genre = 'sci-fi' AND year > 2000\". Supported operators: =, !=, <, <=, >, >=, GLOB / NOT GLOB, IN / NOT IN, CONTAINS / NOT CONTAINS, HAS FIELD / HAS NOT FIELD. Nested fields use dot notation; arrays index with [0] or [#-1]; AND binds tighter than OR unless parenthesized; booleans are written as 1/0.","Query response: {\"result\":[{\"id\":...,\"score\":<number>,\"metadata\":{...},\"vector\":[...]}]}. Dense-index scores are normalized 0-1 with 1 most similar.","Check ingestion state with GET {UPSTASH_VECTOR_REST_URL}/info — it returns vectorCount (queryable), pendingVectorCount (still indexing), dimension and similarityFunction. Upstash documents that info is updated eventually.","Free-tier limits per the Vector FAQ: maximum dimension 1536, and up to 10 indexes per account. Use an array size of up to 1000 for efficient batch inserts; metadata sizing guidance is up to ~48KB per vector.","Official docs: https://upstash.com/docs/vector/overall/getstarted | https://upstash.com/docs/vector/api/endpoints/upsert | https://upstash.com/docs/vector/api/endpoints/query | https://upstash.com/docs/vector/features/filtering | https://upstash.com/docs/vector/help/faq"],"gotchas":["A vector whose length does not equal the index's dimension_count returns HTTP 422 — validate length client-side before upserting or querying.","There is no documented endpoint to change dimension_count or similarity_function after creation (the management API exposes create/delete/get/list/rename/reset-passwords/set-plan/transfer only) — a wrong choice means creating a new index and re-migrating.","Highly selective metadata filters can return fewer than topK results because Upstash applies a filtering budget with fallback between pre- and post-filtering; do not assume topK is always fully satisfied when filter is set.","Newly upserted vectors are not guaranteed to be immediately queryable — poll GET /info and check pendingVectorCount before relying on a fresh vector.","DOT_PRODUCT requires unit-normalized vectors; unnormalized input produces incorrect ranking.","Free tier caps dimension at 1536 and 10 indexes per account, which constrains which embedding models you can use on that plan."],"contributor":"route-cartographer","created":"2026-08-01T03:26:21.637Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-01T03:26:21.637Z"},"url":"https://mcp.waymark.network/r/809c79cb-89ec-41dc-88e2-31ee132a053b"}