Skip to main content
Searches for nearest neighbors in the encrypted index using vector similarity search. Supports single vector queries, batch queries, and semantic search with text content. 
# Single vector query
index.query(query_vectors=vector, top_k=10)

# Batch vector queries
index.query(query_vectors=vectors, top_k=10)

# Semantic search with text
index.query(query_contents=text, top_k=10)

​
Parameters

ParameterTypeDefaultDescription
query_vectorsList[List[float]] or List[float] or np.ndarrayNone(Optional) Multiple query vectors for batch search
query_contentsstrNone(Optional) Text content for semantic search
top_kintNone (server default: 100)(Optional) Number of results to return per query.
n_probesintNone(Optional) Number of clusters to probe for search
filtersDictNone(Optional) Metadata filters to apply
includeList[str]None(Optional) Fields to include in results. None uses the server default ([] — only id is returned). Note: id is always included
greedyboolNone (server default: false)(Optional) Use greedy search algorithm.
rerank_multintNone(Optional) Multiplier for stage 1 retrieval in reranking indexes. Stage 1 returns top_k * rerank_mult candidates before the rerank pass narrows to top_k. Higher values trade query latency for recall. Server default is 10. Ignored by indexes that do not rerank.
When np.ndarray is passed as query_vectors, queries are automatically sent in an optimized binary format for better performance.
include defaults differ between endpoints: query returns [] (only id) by default, while get returns ["vector", "contents", "metadata"].

​
Returns

For single queries: List[Dict] - A list of result dictionaries. For batch queries: List[List[Dict]] - A list of result lists, one for each query vector.

​
Result Format

Single Query Result: 
[  # Returns a flat list of results
  {
    "id": str, # Vector identifier (always included)
    "distance": float, # Similarity distance (if included)
    "metadata": Dict, # Vector metadata (if included)
    "contents": str, # Vector contents (if included)
    "vector": List[float] # Vector data (if included)
  },
  ...
]
Batch Query Result: 
[
  [  # Results for first query vector
    {
      "id": str,
      "distance": float,
      "metadata": Dict,
      ...
    },
    ...
  ],
  [  # Results for second query vector
    ...
  ],
  ...
]

​
Exceptions

  • Throws if the API request fails due to network connectivity issues.
  • Throws if authentication fails (invalid API key).
  • Throws if the encryption key is invalid for the specified index.
  • Throws if there are internal server errors during the search.
  • Throws if query vectors or query contents is not provided.
  • Throws if vector dimensions don’t match the index configuration.
  • Throws if parameter values are out of valid ranges.
  • Throws if the include parameter contains invalid field names.

​
Example Usage

​
Single Vector Query

# Basic similarity search
query_vector = [0.1, 0.2, 0.3, 0.4]
# include defaults to [] (only `id`); pass include to request additional fields
results = index.query(query_vectors=query_vector, top_k=5, include=["distance", "metadata"])

# Access results (single query returns a flat list)
for result in results:
    print(f"ID: {result['id']}, Distance: {result['distance']}")
Batch vector queries: 
import numpy as np

# Query multiple vectors at once
query_vectors = [
    [0.1, 0.2, 0.3, 0.4],
    [0.5, 0.6, 0.7, 0.8],
    [0.9, 1.0, 1.1, 1.2]
]

# include defaults to [] (only `id`); pass include to request additional fields
batch_results = index.query(query_vectors=query_vectors, top_k=3, include=["distance"])

# Process each query's results
for i, query_results in enumerate(batch_results):
    print(f"Results for query {i+1}:")
    for result in query_results:
        print(f"  ID: {result['id']}, Distance: {result['distance']}")

​
Semantic Search with Text

# Search using text content
results = index.query(
    query_contents="machine learning healthcare applications",
    top_k=10,
    include=["contents"]
)

for result in results:
    print(f"Found: {result['id']}")
    if 'contents' in result:
        print(f"Content: {result['contents'][:100]}...")
Advanced filtering and options: 
# Query with metadata filters and custom options
results = index.query(
    query_vectors=[0.1] * 384,
    top_k=20,
    n_probes=5,        # Search more clusters for better recall
    rerank_mult=20,    # Stage 1 returns top_k * 20 candidates before rerank
    filters={'category': 'healthcare', 'priority': 'high'},
    include=['distance', 'metadata', 'contents'],  # Must include 'contents' to access it
    greedy=True        # Use greedy search for potentially better results
)

for result in results:
    print(f"ID: {result['id']}")
    print(f"Distance: {result['distance']:.4f}")
    print(f"Category: {result['metadata']['category']}")
    print(f"Content preview: {result['contents'][:50]}...")
    print("---")