Nearest Neighbor Query

The query vector is the high-dimensional numerical representation (embedding) of the search input, such as a piece of text, an image, or a user profile. This vector serves as the anchor point for the similarity search. The database compares this vector against all indexed vectors in the target collection using a specified distance metric.

• Source: Typically generated by the same embedding model used for the indexed data.
• Dimension: Must match the dimensionality of the vectors in the target collection.
• Example: A 768-dimensional float array representing the phrase "machine learning glossary."

The distance metric (or similarity function) is the mathematical formula used to quantify the proximity between the query vector and vectors in the database. The choice of metric is critical and depends on the embedding space's properties.

Common metrics include:

• Cosine Similarity: Measures the cosine of the angle between vectors, ideal for text embeddings where magnitude is less important.
• Euclidean Distance (L2): Measures the straight-line distance between points in the vector space.
• Inner Product (Dot Product): Calculates the product of vector magnitudes and the cosine of the angle between them.

Note: The index must be built to support the chosen metric for efficient search.

The top-k parameter (often named limit) defines the maximum number of most similar results to return from the query. It is a primary lever for controlling the result set size and query performance.

• Performance Impact: A larger k generally increases query latency as the search algorithm must refine more candidate results.
• Recall vs. Latency: In Approximate Nearest Neighbor (ANN) search, a larger k can improve recall but may require probing more index segments, increasing compute time.
• Typical Values: Often set between 10 and 100 for applications like recommendation or retrieval-augmented generation (RAG).

A filter expression applies conditional logic to vector metadata to perform a hybrid search. It restricts the nearest neighbor search to only those vectors whose metadata satisfies the filter criteria, combining semantic similarity with structured querying.

• Syntax: Uses operators like =, >, in, contains. (e.g., category = 'glossary' AND version > 2).
• Execution: Filters can be applied pre-search (to narrow the candidate set) or post-search (to filter the top-k results), impacting performance and accuracy.
• Use Case: Finding the most similar product vectors only within a specific price range and availability zone.

These are algorithm-specific knobs that control the trade-off between search speed (latency), result accuracy (recall), and resource utilization. They are unique to the underlying vector indexing algorithm.

Examples include:

• ef or efConstruction (HNSW): Controls the size of the dynamic candidate list during graph traversal.
• nprobe (IVF): The number of nearest inverted file clusters (Voronoi cells) to search.
• quantization (PQ): Settings for product quantization that affect the precision of distance calculations.

Tuning these is essential for optimizing production query performance.

This defines the structure and content of the results returned by the Query API. Beyond the vectors themselves, clients can specify what additional data to retrieve.

Key output components:

• Vector IDs: The unique identifiers for the returned nearest neighbors.
• Scores/Distances: The calculated similarity score or distance metric value for each result.
• Vector Values: The full embedding vector, if required for downstream processing.
• Metadata: The structured data (e.g., text, tags, timestamps) associated with each returned vector.

Payload control allows clients to minimize network transfer by retrieving only the fields necessary for their application.

A distance metric is the mathematical function used by a Query API to quantify the similarity or dissimilarity between two vectors, directly determining the results of a nearest neighbor query.

• Common Metrics: Euclidean distance (L2), cosine similarity, inner product (dot product), and Manhattan distance (L1).
• API Parameter: The metric is specified as a parameter (e.g., distance: 'cosine') in the query request payload.
• Impact on Results: The choice of metric is data-dependent; cosine similarity is standard for text embeddings, while Euclidean is common for image embeddings.

A filter expression is a conditional statement applied to vector metadata during a search, enabling hybrid search by combining semantic similarity with structured filtering.

• Syntax: Uses logical operators (AND, OR, NOT) and comparisons (==, >, in) on metadata fields (e.g., category == 'news' AND date > '2024-01-01').
• Execution: Filters are applied before or during the vector similarity search to narrow the candidate set, improving precision.
• API Integration: Passed as a parameter (e.g., filter) in the nearest neighbor query request.

Approximate Nearest Neighbor (ANN) search refers to algorithms that trade perfect accuracy for sub-linear query speed, enabling nearest neighbor queries on billion-scale vector datasets.

• Core Trade-off: Balances recall (fraction of true nearest neighbors found) against query latency and throughput.
• Common Algorithms: HNSW (Hierarchical Navigable Small World), IVF (Inverted File Index), and PQ (Product Quantization).
• API Abstraction: The specific ANN algorithm is typically configured via the Index API; the Query API executes searches against this pre-built index.

k-Nearest Neighbors (k-NN) specifies the number (k) of most similar vectors to return from a nearest neighbor query. It is a fundamental parameter of the Query API.

• API Parameter: Defined as top_k or limit in the query request (e.g., top_k: 10).
• Use Cases: Influences downstream applications; k=1 for direct lookup, k=10 for candidate retrieval in RAG, k=100 for clustering seed points.
• Performance Impact: Larger k values generally increase query latency and computational cost.

The query payload is the structured data sent in the body of a POST request to a vector database's Query API endpoint to execute a nearest neighbor search.

• Required Fields: Typically includes the vector (query embedding) and top_k.
• Optional Fields: Often includes filter, distance_metric, include_metadata, and include_vectors.
• Example JSON: {"vector": [0.1, 0.2, ...], "top_k": 10, "filter": {"status": "active"}}
• Role: This payload fully defines the intent and parameters of the nearest neighbor operation.

Recall and precision are the primary evaluation metrics for the accuracy of an approximate nearest neighbor query, measuring the trade-off between completeness and relevance.

• Recall: The fraction of the true k nearest neighbors (from an exact, brute-force search) that are returned by the ANN query. High recall is critical for RAG and recommendation systems.
• Precision: The fraction of returned vectors that are among the true k nearest neighbors.
• Tuning: Adjusted via index algorithm parameters (e.g., HNSW's ef or efConstruction), directly impacting query API performance.