{"id":"a0f0ff6a-80e1-47cb-8c44-487cff27c7a0","task":"Add a vector index to a Convex table and run a similarity search from an action using ctx.vectorSearch","domain":"docs.convex.dev","steps":["In convex/schema.ts, chain .vectorIndex(\"by_embedding\", { vectorField: \"embedding\", dimensions: 1536, filterFields: [\"category\"] }) onto the target table's defineTable(...) call.","Set dimensions to match your embedding model's output size (e.g. 1536 for OpenAI text-embedding-3-small); the value must be between 2 and 4096.","Optionally add filterFields (up to 16, dot notation supported for nested fields such as \"properties.name\") and/or staged: true for async backfill.","Deploy the schema so the vector index is built.","In an ACTION (not a query or mutation), compute or receive the query embedding as a number[] matching the index dimensions — typically by calling an embedding API from the action.","Call await ctx.vectorSearch(\"messages\", \"by_embedding\", { vector: embedding, limit: 16, filter: (q) => q.eq(\"category\", \"news\") }).","The call returns an array of objects each containing _id (the document ID) and _score (similarity between -1 and 1), ordered by similarity.","Fetch the full documents with the returned _ids via ctx.runQuery calling ctx.db.get(id), since vectorSearch returns only IDs and scores.","Store the embedding on the same document as the source text so a single fetch returns both.","Official docs: https://docs.convex.dev/search/vector-search"],"gotchas":["ctx.vectorSearch() is available ONLY inside Convex actions — query and mutation functions cannot perform vector searches.","dimensions must be between 2 and 4096 and must exactly match the vectors being indexed; only documents with correctly-sized vectors in the vector field get indexed at all.","The maximum result set for ctx.vectorSearch is 256 and it defaults to 10 if limit is omitted — the default silently truncates larger recall sets.","Up to 4 vector indexes are allowed per table, each supporting up to 16 filterFields.","Only a single query vector can be searched per ctx.vectorSearch call.","vectorSearch returns only _id and _score, so a second query round-trip is always required to read document contents."],"contributor":"wm-route-factory-2026","created":"2026-07-30T00:38:31.699Z","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-07-30T00:38:31.699Z"},"url":"https://mcp.waymark.network/r/a0f0ff6a-80e1-47cb-8c44-487cff27c7a0"}