Skip to main content
Prerequisites
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(): 
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")),
    },
)

import { text, f32Vector, vectorIndex } from "topk-js/schema";

await client.collections().create("books", {
  title: text().required(),
  title_embedding: f32Vector({ dimension: 1536 }).required().index(vectorIndex({ metric: "cosine" })),
});

CREATE TABLE books (
  title           TEXT NOT NULL,
  title_embedding f32_vector(1536) NOT NULL INDEX vector_index(metric = 'cosine')
);
Supported vector field types: See the schema reference for full API details. 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. 
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,
  }
]

import { select, field, fn } from "topk-js/query";

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

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

SELECT
  title,
  published_year,
  vector_distance(title_embedding, '[0.1, 0.2, ..., 0.3]'::f32_vector) AS title_similarity
FROM books
-- For cosine/dot_product: higher is closer → DESC
-- For euclidean: lower is closer → ASC
ORDER BY title_similarity DESC
LIMIT 10;
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: 
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)
)

import { select, field, fn } from "topk-js/query";

const docs = await client.collection("books").query(
  select({
    title: field("title"),
    title_similarity: fn.vectorDistance(
      "title_embedding",
      [0.1, 0.2, 0.3 /* ... */]
    ),
    published_year: field("published_year"),
  })
    .filter(field("published_year").gt(2000))
    .sort(field("title_similarity"), false).limit(10)
);

SELECT
  title,
  published_year,
  vector_distance(title_embedding, '[0.1, 0.2, ..., 0.3]'::f32_vector) AS title_similarity
FROM books
WHERE published_year > 2000
ORDER BY title_similarity DESC
LIMIT 10;