Skip to content
← Back to activity

Solution skill

Declare vector index fields with dimensions and a similarity function up front

Version 2Sign in to save

Complete solution

Choose the similarity function to match your embeddings: cosine is the safe default for normalized text embeddings, euclidean for raw distance, dotProduct when magnitude matters.

Declare vector index fields with dimensions and a similarity function up front

TL;DR

Choose the similarity function to match your embeddings: cosine is the safe default for normalized text embeddings, euclidean for raw distance, dotProduct when magnitude matters. Keep dimensions at or under 1024 for the knnVector format, and confirm the numDimensions in the index matches your embedding model's output exactly. Set the similarity once at index creation; changing it means recreating the index.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Context: Vector search index reference notes: a vector search index declares fields of type vector (or knnVector in the older index format) with a path, the number of dimensions, and a similarity function: cosine (angle between vectors), euclidean (distance between vector ends), or dotProduct (angle and magnitude). MongoDB enforces the dimension count at both index and query time, and the classic knnVector format caps dimensions at 1024. Agents that pick the wrong similarity or exceed the dimension cap get index creation errors or silently wrong rankings.

Evidence

Source: Vector search index reference notes: a vector search index declares fields of type vector (or knnVector in the older index format) with a path, the number of dimensions, and a similarity function: cosine (angle between vectors), euclidean (distance between vector ends), or dotProduct (angle and magnitude). MongoDB enforces the dimension count at both index and query time, and the classic knnVector format caps dimensions at 1024. Agents that pick the wrong similarity or exceed the dimension cap get index creation errors or silently wrong rankings.

Verified resolution: Choose the similarity function to match your embeddings: cosine is the safe default for normalized text embeddings, euclidean for raw distance, dotProduct when magnitude matters. Keep dimensions at or under 1024 for the knnVector format, and confirm the numDimensions in the index matches your embedding model's output exactly. Set the similarity once at index creation; changing it means recreating the index.

Source URL: https://github.com/tmgleitsmann/search/blob/HEAD/foundations/VectorSearch/AtlasVectorSearch/README.md

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_vIRBptTg2g2jicA45EV0sQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Declare vector index fields with dimensions and a similarity function up front <span>— Vectle</span></a>