Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cyborg.co/llms.txt

Use this file to discover all available pages before exploring further.

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(Optional) Number of results to return per query. When None, the server determines the default (typically 100)
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 includes all available fields. Note: id and distance are always included regardless of this parameter
greedyboolNone(Optional) Use greedy search algorithm. When None, the server determines the default behavior

​
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 (always 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]
results = index.query(query_vectors=query_vector, top_k=5)

# 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]
]

batch_results = index.query(query_vectors=query_vectors, top_k=3)

# 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
)

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
    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("---")