Similarity Search

Similarity search finds the closest vectors to a query vector — the core operation in VectorAmp.

How It Works

1. Your application generates an embedding of the query (e.g., a user's question)
2. VectorAmp compares this vector against all stored vectors using the dataset's distance metric
3. The top-K most similar vectors are returned, ranked by similarity score

Basic Search

results = client.datasets.search("my-dataset",
    vector=[0.1, 0.2, 0.3, ...],
    top_k=10
)

Filtered Search

Narrow results using metadata filters:

results = client.datasets.search("my-dataset",
    vector=[0.1, 0.2, ...],
    top_k=10,
    filter={
        "category": "documentation",
        "language": "en"
    }
)

Filters are applied before the similarity search, ensuring you only search within the matching subset.

Search Results

Each result includes:

Field	Description
id	Vector ID
score	Similarity score (metric-dependent)
metadata	Stored metadata for this vector

{
  "matches": [
    {"id": "doc-42", "score": 0.95, "metadata": {"title": "Getting Started"}},
    {"id": "doc-17", "score": 0.89, "metadata": {"title": "API Reference"}},
  ]
}

Understanding Scores

Scores depend on the distance metric:

Metric	Range	Higher = ?
Cosine	[-1, 1]	More similar
Dot Product	(-∞, +∞)	More similar
Euclidean	[0, +∞)	Less similar

Performance Tips

• Use filters to narrow the search space when possible
• Lower top_k if you don't need many results — it's faster
• Batch queries when searching for multiple vectors
• Match dimensions — don't pad or truncate vectors