Dense vector search

High-performance ANN search with >95% recall and p99 < 50ms latency for semantic similarity at scale.

Prerequisites

• TopK account (Sign up here)
• TopK API key (Get an API key here)

TopK is built for high-performance dense vector search workloads. It is designed to:

• Maintain >95% recall, reducing the likelihood of missing relevant results in applications such as recommendation systems, image search, and semantic search.
• Deliver consistent low latency (p99 < 50 ms). See the benchmarks for details.
• Support large-scale single-collection deployments as well as multi-tenant architectures.

Define a collection schema with a vector field

Define a schema with a vector field and add a vector_index():

Python

from topk_sdk.schema import text, f32_vector, vector_index

client.collections().create(
    "books",
    schema={
        "title": text().required(),
        "title_embedding": f32_vector(dimension=1536).required().index(vector_index(metric = "cosine")),
    },
)

Supported vector field types:

• f32_vector() — Dense float32 embeddings (most common)
• u8_vector() — Quantized uint8 embeddings
• i8_vector() — Signed quantized int8 embeddings
• binary_vector() — Binary embeddings (use with hamming metric)
• f32_sparse_vector() — Sparse embeddings (see sparse vector search guide)
• u8_sparse_vector() — Quantized sparse embeddings
• matrix() — Multi-vector embeddings (see multi-vector search guide)

See the schema reference for full API details.

Perform a k-Nearest Neighbor (kNN) search

To retrieve the top-k nearest neighbors of a query vector, use the fn.vector_distance() function.

fn.vector_distance() computes the distance (or similarity) between a stored vector field and a query vector, based on the distance metric configured in the vector index (e.g., cosine or Euclidean).

You can use the computed value to sort and return the closest matches.

Python

from topk_sdk.query import select, field, fn

docs = client.collection("books").query(
    select(
        "title",
        published_year=field("published_year"),
        # Compute vector similarity between the vector embedding of the string "epic fantasy adventure"
        # and the embedding stored in the `title_embedding` field.
        title_similarity=fn.vector_distance("title_embedding", [0.1, 0.2, 0.3, ...]),
    )
    # cosine/dot-product: higher score = closer → sort descending
    .sort(field("title_similarity"), asc=False).limit(10)
    # for euclidean distance: lower score = closer → sort ascending
    # .sort(field("title_similarity"), asc=True).limit(10)
)

# Example results:
[
  {
    "_id": "2",
    "title": "Lord of the Rings",
    "title_similarity": 0.8150404095649719
  },
  {
    "_id": "1",
    "title": "The Catcher in the Rye",
    "title_similarity": 0.7825378179550171,
  }
]

Let’s break down the example above:

1. Compute the cosine similarity between the query embedding and the title_embedding field using the vector_distance() function.
2. Store the computed cosine similarity in the title_similarity field.
3. Return the top 10 results sorted by the title_similarity field in a descending order.

Combine vector search with metadata filtering

Vector search can be combined with metadata filtering by adding a filter() stage to the query:

Python

from topk_sdk.query import select, field, fn

docs = client.collection("books").query(
    select(
        "title",
        title_similarity=fn.vector_distance("title_embedding", [0.1, 0.2, 0.3, ...]),
        published_year=field("published_year"),
    )
    .filter(field("published_year") > 2000)
    .sort(field("title_similarity"), asc=False).limit(10)
)